1. Home
2. ALIGNCURVE procedure

# ALIGNCURVE procedure

Forms an optimal warping to align an observed series of observations with a standard series (D.B. Baird).

### Options

`PRINT` = string tokens What to print (`criterion`, `ss`, `warps`); default `*` i.e. nothing What to plot (`series`, `warping`); default `*` i.e. no plots The relative penalty to add to the criterion when jumping a unit in one series but not the other; default 1 The largest jump that can be made between the two series at a single point; default 1 Sets a limit on size of difference between the series to be squared and added to the criterion (differences greater than this are truncated to `MAXDIFFERENCE`, thus allowing the effects of outliers to be down-weighted); default `*` i.e. no limit Whether to use the means of points covered in one step, rather than the final value, when calculating the sums of squares between the two series (`yes`, `no`); default `no` Whether to force the ends of the two series to align, so that warping happens only in the middle of the series (`yes`, `no`); default `no` Window number for the plots; default 1 Window for the key (zero for no key); default 2

### Parameters

`Y` = variates Series to be aligned with the standard series Standard series for each `Y` Weights for the contribution of each point to the criterion; default `*` no weighting The warped positions of the unit numbers, required to align `Y` with `STANDARD` The warped series for `Y`, i.e. the optimally aligned y-values The criterion value (as optimized during the alignment) Title for the plots

### Description

`ALIGNCURVE` is useful when you have a series of observations of a theoretical curve in which the x-axis may have been distorted by stretching or compression. The aim is to “warp” the units of the curve so that it optimally matches a standard series. (This can be used, for example, to align electrophoresis gels.) The observed and standard series are specified, in variates, by the `Y` and `STANDARD` parameters respectively.

The warping takes the form of one of the series jumping values, so it that makes several steps for a single step of the other series. There is no limitation on the number of times that this can happen along the series, but you can set option `FORCEENDALIGNMENT=yes`, to require the two series to match at their final values.

The dynamic warping algorithm that is used, seeks to optimize a criterion that is based on the sum of squares of residuals between the warped observed series and the standard series at each point, plus a penalty that depends on the amount of warping.

The `WEIGHTS` parameter can supply a variate of weights to use for the contribution of each point to the criterion. If the standard curve has non-constant variance around it, typically you would set the weights to be the reciprocal of the variance or equivalently, one over the square of the standard deviation. Suppose, for example, if the curve is the mean of a Poisson process. the mean is equal to the variance for a Poisson distribution, so the you could use weights of `1/STANDARD` to allow for the non-constant variance. Alternatively, if the points on the curves were means of differing numbers of replicated observations, you could weight by the recriprocals of the replications. By default there is no weighting.

The `MAXDIFFERENCE` option sets a limit on contribution of each residual: differences greater than this are truncated (to `MAXDIFFERENCE`), thus allowing the effects of outliers to be down-weighted. By default there is no limit.

The `WARPPENALTY` option defines the relative penalty to be added to the criterion when the series are warped by one step in either direction; default 1. The penalty is given by `WARPPENALTY` multiplied by a scale factor equal to the average mean square of the initial (unwarped) differences between `Y` and `STANDARD`. (It is thus scale independent, so multiplying both `Y` and `STANDARD` by a constant will still give the same solution.) Setting `WARPPENALTY` to zero finds the optimally aligned series with no constraint on warping. Conversely, setting `WARPPENALTY` to a large value discourages warps, as a jump will be taken only if the decrease in the sum of squares is greater than the penalty.

The `MAXSTEP` option sets a limit on the number of units that can be jumped at any one point (default 1).

By default, the y-value after a jump is taken to be the value at the end of the jump, but you can set option `USEMEANS=yes` to use the mean of the values at the end and intervening (jumped) points.

The `UWARP` parameter can save a variate containing the warped units, i.e. the unit of `Y` that corresponds (after warping) to each unit of `STANDARD`. The `YWARP` parameter can save the y-values of the optimally aligned series, and the `CRITERIONVALUE` parameter can save the optimal criterion value.

The `PRINT` option controls printed output, with settings:

    `criterion` to print the smoothing weight, maximum step size and optimal criterion value, to print the location of the warps, to print sums of squares before and after alignment.

By default nothing is printed.

The `PLOT` option controls the plots that are displayed, with settings:

    `series` plots the aligned and standard series, plots the steps in the warping that have been used to align the two series.

By default nothing is plotted. The `WINDOW` option specifies the window to use for the plots (default 1), and the `KEYWINDOW` option specifies the window for their keys (default 2). You can supply a title for the plots using the `TITLE` parameter.

Options: `PRINT`, `PLOT`, `WARPPENALTY`, `MAXSTEP`, `MAXDIFFERENCE`, `USEMEANS`, `FORCEENDALIGNMENT`, `WINDOW`, `KEYWINDOW`.

Parameters: `Y`, `STANDARD`, `WEIGHTS`, `UWARP`, `YWARP`, `CRITERIONVALUE`, `TITLE`.

### Action with `RESTRICT`

Any restrictions are ignored.

Procedures: `BASELINE`, `PEAKFINDER`.

Commands for: Calculations and manipulation.

### Example

```CAPTION    'ALIGNCURVE examples'; STYLE=meta
CALCULATE  X = !(1...1000)/80
&          S = SIN(X)
&          Y = SIN(1.2*X)        " Y has an increased rate from S "
ALIGNCURVE [PRINT=criterion,ss; PLOT=series,warping; WARPPENALTY=0;\
FORCEENDALIGNMENT=yes] Y; STANDARD=S;\
UWARP=WarpedunitsY; YWARP=WWarpedY; CRITERIONVALUE=CY
CALCULATE  Z = SIN(X + SIN(X/2)) " Z has an varying rate from S "
ALIGNCURVE [PRINT=criterion,ss; PLOT=series,warping; WARPPENALTY=0]\
Z; STANDARD=S; UWARP=WarpedunitsZ; YWARP=WarpedZ; CRITERIONVALUE=CZ
" penalize warps "
ALIGNCURVE [PRINT=criterion,ss,warps; PLOT=series,warping; WARPPENALTY=1]\
Z; STANDARD=S; UWARP=WarpedunitsZp; YWARP=WarpedZp;\
CRITERIONVALUE=CZp; TITLE='Z aligned to S, penalty=1'
```
Updated on June 20, 2019