Instruction-based Time Series Editing

• Instruction-based time series editing is defined as modifying an existing sequence with natural language instructions to selectively change target attributes while keeping non-target features intact.
• It employs a multimodal framework combining multi-resolution CNN encoders and transformer decoders to bridge textual and temporal data effectively.
• Empirical evaluations using metrics like RaTS and ΔDTW demonstrate its capability for precise counterfactual modifications with minimal disruption to preserved properties.

Instruction-based time series editing is the task of taking an existing time series and an instruction describing new conditions, then generating a modified series that satisfies the requested change while preserving the original structure as much as possible. In its explicit natural-language form, the task is formalized as learning a function $$\hat{\mathbf{x}} = f_\theta(\mathbf{x}, \mathbf{c})$$, where $\mathbf{x}$ is the input series and $\mathbf{c}$ is a textual instruction; the output should realize the target condition without unnecessarily altering non-target properties (Qiu et al., 2 Aug 2025). Closely related formulations include diffusion-driven editing under point-wise and segment-level constraints, as in CocktailEdit, and instruction-conditioned in-context editing in which the “instruction” is given by structured demonstrations rather than natural language (Yu et al., 5 Jun 2025, Saha et al., 23 Mar 2026).

1. Definition and problem scope

Time series editing differs from ordinary generation, forecasting, and imputation because it starts from an existing trajectory and seeks a controlled counterfactual variant rather than a wholly new sample or a reconstruction of what actually happened. The central requirement is selective modification: some properties should change, while others and the instance-specific idiosyncrasies should remain similar to the source. In the formal definition used by InstructTime, the goal is to transform $\mathbf{x} \in \mathbb{R}^T$ into $\hat{\mathbf{x}}$ under a natural-language instruction $\mathbf{c} = [c_1,\dots,c_L]$, with the model inferring the original condition from $\mathbf{x}$ itself rather than receiving an original attribute vector as input (Qiu et al., 2 Aug 2025).

The application scenarios described for this task are explicitly counterfactual and “what-if” in character. Physiological signals are a canonical example: a neonatal ICU heart-rate trace may be edited so that a normal record acquires a plausible early bradycardia event while retaining patient-specific variability. Other examples include changing the city or season condition for weekly PM2.5 trajectories, or editing synthetic sequences to alter trend direction, seasonality, abrupt mean shifts, or noise level (Qiu et al., 2 Aug 2025).

Within the broader time-series literature, time series editing combines conditional generation, counterfactual reasoning, and per-instance preservation. Forecasting generates future values from history; imputation fills missing values; anomaly detection identifies unusual segments; unconditional generation samples new trajectories; time series editing instead modifies an already observed trajectory under alternate conditions. The diffusion-oriented framing of Time Series Editing (TSE) emphasizes this difference by defining editing as precise modification under local and segment-level constraints while preserving temporal coherence (Yu et al., 5 Jun 2025).

2. From attribute-conditioned diffusion editing to instruction-based editing

A major precursor to instruction-based editing is attribute-conditioned diffusion editing. Recent editors such as TimeWeaver and TEdit are described as conditional diffusion models that typically consume an input time series, an original attribute vector, and a target attribute vector. TEdit extends TimeWeaver into an editing framework that denoises toward a target-conditioned series while remaining close to the learned data distribution (Qiu et al., 2 Aug 2025).

The principal criticism of that design is twofold. First, conditions are represented as rigid, predefined attribute vectors: the attribute space must be manually enumerated, future edits must remain expressible in that fixed space, and nuanced real text cannot be used directly. Second, editing is “all-or-nothing” through sampling: the diffusion sampler runs under the target condition, but there is no explicit continuous control over editing strength; variation arises through stochastic sampling rather than a dedicated edit-intensity parameter (Qiu et al., 2 Aug 2025).

CocktailEdit addresses a different limitation of diffusion editing: insufficient control granularity. It introduces a framework that combines confidence-weighted anchor control for point-wise constraints with classifier-based control for statistical properties such as sums and averages over segments. These controls are applied during denoising inference, are intended to maintain temporal coherence, and are designed to integrate seamlessly with conditionally trained diffusion-based time-series models. The stated aim is simultaneous, flexible control across different constraint types for human-in-the-loop time series generation and editing (Yu et al., 5 Jun 2025).

Taken together, these two lines of work define two complementary notions of “instruction.” In the InstructTime formulation, the instruction is free-form text describing target conditions. In the CocktailEdit formulation, the effective instruction is a structured set of point-wise and segment-level controls. The walkthrough associated with CocktailEdit further presents it as a foundation for instruction-based editing by mapping user requests into anchors, confidence masks, and segment constraints; this suggests a backend architecture in which natural language or UI actions are translated into diffusion-time controls rather than directly decoded from text (Yu et al., 5 Jun 2025).

3. InstructTime architecture

InstructTime is introduced as the first instruction-based time series editor. Its architecture has three components: a multi-resolution time-series encoder $\mathcal{E}_\phi$, an instruction encoder $\mathcal{E}_\theta$, and a conditional time-series decoder $\Psi$. These define a unit-norm time-series embedding $\mathbf{x}$0, a unit-norm instruction embedding $\mathbf{x}$1, and a decoder output $\mathbf{x}$2 (Qiu et al., 2 Aug 2025).

The time-series encoder is explicitly multi-resolution. It uses $\mathbf{x}$3 parallel 1D CNN branches, each with kernel size proportional to $\mathbf{x}$4; in the reported experiments, $\mathbf{x}$5, with kernel sizes corresponding to the fractions $\mathbf{x}$6, $\mathbf{x}$7, $\mathbf{x}$8, $\mathbf{x}$9, $\mathbf{c}$0, $\mathbf{c}$1, $\mathbf{c}$2, and $\mathbf{c}$3 of the sequence length. Large kernels are intended to capture global structure such as trend and seasonality, whereas small kernels target local structure such as abrupt shifts, local variability, and events. The branch outputs are concatenated into a $\mathbf{c}$4 dimensional representation and normalized to lie on a unit-radius hypersphere (Qiu et al., 2 Aug 2025).

The instruction encoder aligns text with that same hyperspherical space. A frozen pretrained sentence embedding model encodes the instruction; the default implementation uses SentenceTransformer paraphrase-mpnet-base-v2, while all-mpnet-base-v2 and roberta-base-nli-mean-tokens are also evaluated. The resulting sentence embedding is passed through $\mathbf{c}$5 parallel MLPs, each producing one chunk of the final embedding, so that the text representation is decomposed resolution by resolution in the same manner as the time-series representation (Qiu et al., 2 Aug 2025).

A shared multimodal representation space is then learned by a CLIP-style symmetric InfoNCE loss. Matching time-series/instruction pairs are pulled together, and mismatched pairs are pushed apart. Reconstruction is learned with an MSE loss through the decoder, and training proceeds in two stages: first contrastive alignment only, then joint optimization of contrastive and reconstruction losses. The reconstruction term is weighted relative to the contrastive term via a parameterization using $\mathbf{c}$6, with the default setting $\mathbf{c}$7, corresponding to a reconstruction contribution of approximately $\mathbf{c}$8 relative to contrastive (Qiu et al., 2 Aug 2025).

The decoder treats the time-series and instruction embeddings as a sequence of two tokens, applies positional encoding, and passes them through a Transformer-style stack of 8 self-attention blocks with feedforward and residual connections. The hidden state associated with the time-series token is projected by a linear head to the full output sequence. This design is intended to support inter-modality interaction while allowing information from different temporal resolutions to mix inside the transformer (Qiu et al., 2 Aug 2025).

4. Editing strength, local–global control, and instruction modalities

The defining mechanism for controllable editing in InstructTime is linear interpolation in the shared embedding space: $\mathbf{c}$9 followed by decoding

$\mathbf{x} \in \mathbb{R}^T$0

At $\mathbf{x} \in \mathbb{R}^T$1, the model reconstructs the input; at $\mathbf{x} \in \mathbb{R}^T$2, it generates a series purely from the instruction; intermediate values yield partial edits that interpolate between the original instance and the target condition (Qiu et al., 2 Aug 2025).

This interpolation is presented as the solution to the “all-or-nothing” limitation of prior diffusion-based editors. The reported behavior is a deterministic, monotonic progression of edit strength controlled by a single scalar $\mathbf{x} \in \mathbb{R}^T$3. In the synthetic experiments, as $\mathbf{x} \in \mathbb{R}^T$4 increases from 0 to 1, a flat trend becomes mildly upward and then strongly upward, while seasonality and mean-shift patterns remain preserved over a broad range of intermediate values. Quantitatively, $\mathbf{x} \in \mathbb{R}^T$5 becomes more negative as $\mathbf{x} \in \mathbb{R}^T$6 increases, RaTS increases for edited attributes, and $\mathbf{x} \in \mathbb{R}^T$7 for preserved attributes remains small for low to moderate $\mathbf{x} \in \mathbb{R}^T$8 before growing near $\mathbf{x} \in \mathbb{R}^T$9 (Qiu et al., 2 Aug 2025).

Local and global edits are handled primarily through the multi-resolution design. Global attributes such as trend, seasonality, and noise level are associated with larger receptive fields, whereas local attributes such as abrupt mean shifts and bradycardia episodes are associated with smaller receptive fields. The text embedding is chunked accordingly, and the transformer jointly processes all chunks. At the same time, the model has no explicit mask or explicit temporal localization mechanism; instructions of the form “add an event at 5 minutes” are not handled through direct indexing, and localization is instead implicit in the learned representation (Qiu et al., 2 Aug 2025).

A distinct but related instruction modality appears in the foundation-model line represented by iAmTime. There, the instruction is not natural language but a structured prompt built from example episodes and a query. The prompt serializes targets, covariates, histories, and futures using semantic tokens such as [START], [TARGET_SERIES], [EXOG], [MID], [FUTURE_EXOG], and [END], and the model infers the task from demonstrated input–output mappings rather than textual descriptions. The same framework covers forecasting, imputation, reconstruction, anomaly correction, classification, and source de-mixing, so that editing becomes an in-context transformation learned from examples (Saha et al., 23 Mar 2026).

The comparison between these modalities is technically consequential. InstructTime offers explicit natural-language conditioning and a scalar control parameter $\hat{\mathbf{x}}$0. iAmTime offers structured, example-based instructions and non-autoregressive quantile outputs over edited futures. CocktailEdit, by contrast, offers direct constraint enforcement through denoising-time controls. These are different operationalizations of instruction-based editing rather than interchangeable implementations (Qiu et al., 2 Aug 2025, Saha et al., 23 Mar 2026, Yu et al., 5 Jun 2025).

5. Datasets, metrics, and empirical results

The empirical evaluation of InstructTime spans three datasets. The synthetic benchmark contains 18,000 univariate time series of length $\hat{\mathbf{x}}$1, generated from combinations of 5 trend types, 2 seasonality levels, 3 abrupt mean-shift levels, and 2 local-variability levels, giving $\hat{\mathbf{x}}$2 attribute combinations with 300 samples each. The air-quality benchmark contains 3,684 weekly PM2.5 series of length $\hat{\mathbf{x}}$3, with attributes city and season. The NICU heart-rate benchmark contains 36,679 series of length $\hat{\mathbf{x}}$4, with attributes heart-rate variability and bradycardia events (Qiu et al., 2 Aug 2025).

Evaluation separates editability from preservability. The principal metrics are RaTS, the log ratio of target-to-source classifier probabilities,

$\hat{\mathbf{x}}$5

and $\hat{\mathbf{x}}$6, which measures whether the edited output is closer than the source to real series from the target attribute configuration. Higher RaTS is desirable for edited attributes, lower $\hat{\mathbf{x}}$7 is desirable for preserved attributes, and more negative $\hat{\mathbf{x}}$8 indicates stronger movement toward the target distribution. On synthetic data, MSE and MAE are additionally reported against synthetic ground truth (Qiu et al., 2 Aug 2025).

Dataset	InstructTime results in the instruction-based setting	Notes
Synthetic	$\hat{\mathbf{x}}$9, RaTS $\mathbf{c} = [c_1,\dots,c_L]$0, $\mathbf{c} = [c_1,\dots,c_L]$1, MSE $\mathbf{c} = [c_1,\dots,c_L]$2, MAE $\mathbf{c} = [c_1,\dots,c_L]$3	Best reported setting among compared methods
Air quality	$\mathbf{c} = [c_1,\dots,c_L]$4, RaTS $\mathbf{c} = [c_1,\dots,c_L]$5, $\mathbf{c} = [c_1,\dots,c_L]$6	Other methods have positive $\mathbf{c} = [c_1,\dots,c_L]$7
NICU heart rate	$\mathbf{c} = [c_1,\dots,c_L]$8, RaTS $\mathbf{c} = [c_1,\dots,c_L]$9, $\mathbf{x}$0	Lower preserved-attribute error than baselines

These results are reported against instruction-adapted versions of TimeWeaver and TEdit, where the baselines replace attribute vectors with embeddings from the same sentence encoder used in InstructTime. In the instruction-based setting, InstructTime is reported as achieving stronger editability and markedly better preservability, especially on synthetic data where $\mathbf{x}$1 indicates minimal disruption to preserved attributes (Qiu et al., 2 Aug 2025).

Generalization is evaluated in two distinct senses. For unseen phrasings of known conditions, 50 paraphrases per attribute level are generated with GPT-4o, with 70% used for training and 30% held out. In this setting, InstructTime maintains strong performance; on the synthetic dataset it achieves $\mathbf{x}$2, RaTS $\mathbf{x}$3, and $\mathbf{x}$4. For entirely unseen attribute levels, zero-shot editing is weak, but few-shot tuning with even one real example is reported to improve editability substantially, and larger numbers of examples bring performance close to a model trained on all levels (Qiu et al., 2 Aug 2025).

The ablation studies identify several architectural and optimization dependencies. Values $\mathbf{x}$5 give similar good results, whereas $\mathbf{x}$6 harms RaTS and $\mathbf{x}$7 on synthetic and NICU data. Small numbers of resolutions are insufficient, with $\mathbf{x}$8 underperforming on synthetic and NICU data, and $\mathbf{x}$9 providing the best balance. Among pretrained text encoders, Paraphrase MPNet is best on the synthetic dataset with long instructions describing four attributes, MPNet is better than RoBERTa on short instructions, and RoBERTa yields poorer preservability (Qiu et al., 2 Aug 2025).

6. Related directions, misconceptions, limitations, and future work

One common misconception is that “instruction-based” necessarily implies natural-language prompts. The literature described here supports at least three distinct instruction channels. InstructTime uses free-form text. CocktailEdit uses structured constraints, notably point-wise anchors and segment-level statistical controls. iAmTime uses example-based instructions encoded by demonstrations and semantic tokens. The term therefore refers less to a specific modality than to conditioning editing on externally specified target behavior (Qiu et al., 2 Aug 2025, Yu et al., 5 Jun 2025, Saha et al., 23 Mar 2026).

A second misconception is that instruction-based editing automatically provides exact temporal localization. InstructTime does not include an explicit temporal mask or index-based mechanism; its handling of locality is implicit through multi-resolution representations. CocktailEdit is closer to explicit localization because it directly supports point-wise and segment-level controls during denoising. iAmTime’s localization is likewise structural: the prompt format specifies which parts of examples and queries serve as inputs, outputs, targets, and covariates, but it does not provide natural-language temporal grounding (Qiu et al., 2 Aug 2025, Yu et al., 5 Jun 2025, Saha et al., 23 Mar 2026).

The limitations reported across these works are correspondingly different. InstructTime may struggle with complex or ambiguous real-world text, lacks explicit support for instructions such as “add an event at 5 minutes,” is currently evaluated on univariate and moderate-length sequences, and appears weaker than diffusion methods on pure noise attributes such as local variability (Qiu et al., 2 Aug 2025). CocktailEdit acknowledges a trade-off between control precision and distribution preservation, noting that “obvious distribution drift still exists” under strong guidance (Yu et al., 5 Jun 2025). iAmTime does not take natural language, does not explicitly enforce exact constraints such as mass conservation, and depends on prompt construction and pretraining coverage for behavior under novel domains (Saha et al., 23 Mar 2026).

The future directions identified in the source material are technically specific. For InstructTime, proposed directions include variational extensions such as hyperspherical VAEs, step-wise editing for sequential instructions, integration with foundation models, deployment on real multimodal time-series-plus-text corpora, and bidirectional use of the shared embedding space for text generation from time series (Qiu et al., 2 Aug 2025). For CocktailEdit, future work is framed around improving the control-precision versus distribution-preservation trade-off and developing more advanced control mechanisms (Yu et al., 5 Jun 2025). For example-based instruction-conditioned foundation models, the implied directions include richer instruction modalities, broader task coverage, improved example selection and prompt construction, and tighter integration of user-specified constraints into decoding (Saha et al., 23 Mar 2026).

Instruction-based time series editing therefore comprises a family of methods rather than a single architecture. In its natural-language form, it is exemplified by InstructTime’s shared multimodal embedding space, multi-resolution encoding, and interpolation-based control of edit strength. In its constraint-based form, it appears as diffusion-time control over anchors and segment statistics. In its demonstration-based form, it becomes in-context editing through structured prompts and example-conditioned decoding. The common objective across these variants is selective transformation of a given trajectory under externally specified conditions, with preservation of temporal coherence and non-target structure as the central technical constraint (Qiu et al., 2 Aug 2025, Yu et al., 5 Jun 2025, Saha et al., 23 Mar 2026).