Xmgr: transformations

## Transformations

- Evaluate expression
- Load values
- Load & evaluate
- Histograms
- Fourier transforms
- Running averages
- Regression
- Non-linear curve fitting
- Differences
- Seasonal differences
- Integration
- Cross/auto-correlation
- Interpolation
- Splines
- Sample points
- Prune data
- Digital filter
- Linear convolution
- Geometric transformations
- Feature extraction

NOTE: Some of these operations generate new sets, if you run out of sets use Edit/Set operations (described below) to kill unneeded sets. Also, the scaling of the world coordinate system may be inappropriate for the results of many of these operations. Use the Status popup to determine the appropriate scaling factors to use in "Define world" (above), or use "Autoscale..." (in View/Autoscale above). Most functions operate on active sets only.

### Evaluate expressions

Evaluates a formula defined in infix fashion.

Select the set on which the formula will operate, (set must be active, use File/Status to find the current state of sets). If you desire the result be loaded to a new set rather than overwriting the set used for computations, use the panel cycle denoted `Result to' to inform xmgr you'd like the result placed in a new set (if there is one). A new set is created only if a single set is selected from step 1. If `All sets' are selected then the results will overwrite all active sets.

Enter the formula, the syntax is:

(x,y,a,b,c,d)=<expression>

where (x,y,a,b,c,d) are defined as the x and y of the currently selected set and a,b,c,d are scratch arrays that can be used to perform operations between sets. Case is ignored, so X=COS(X) is correct.

Click on Accept when you are satisfied with everything.

Variables:

- a == reference to scratch array
- b == reference to scratch array
- c == reference to scratch array
- d == reference to scratch array

Functions:

- abs(x) == absolute value
- acos(x) == arccosine
- acosh(x) == hyperbolic arccosine
- ai(x), bi(x) == Airy functions (two independent solutions of the differential equation `y"(x) = xy`).
- asin(x) == arcsine
- asinh(x) == hyperbolic arcsine
- atan(x) == arctangent
- atan2(y,x) == Fortran ATAN2
- atanh(x) == hyperbolic arctangent
- beta(x) == beta function
- ceil(x) == greatest integer function
- chdtr(df, x) == chi-square distribution
- chdtrc(v, x) == complemented Chi-square distribution
- chdtri(df, y) == inverse of complemented Chi-square distribution
- chi(x) == hyperbolic cosine integral
- ci(x) == cosine integral
- cos(x) == cosine
- cosh(x) == hyperbolic cosine
- dawsn(x) == Dawson's integral
- deg == 180.0/PI
- dx == span of world coordinate system in x
- dy == span of world coordinate system in y
- ellie(phi, m) == incomplete elliptic integral of the second kind
- ellik(phi, m) == incomplete elliptic integral of the first kind
- ellpe(m) == complete elliptic integral of the second kind
- ellpk(m) == complete elliptic integral of the first kind
- erf(x) == error function
- erfc(x) == complement of error function
- exp(x) == e^x
- expn(x) == exponential integral
- fac(n) == factorial function, n!
- fdtr(df1, df2, x) == F distribution function
- fdtrc(x) == complemented F distribution
- fdtri(x) == inverse of complemented F distribution
- floor(x) == least integer function
- fresnlc(x) == cosine Fresnel integral
- fresnls(x) == sine Fresnel integral
- gamma(x) == gamma function
- gdtr(a, b, x) == gamma distribution function
- gdtrc(a, b, x) == complemented gamma distribution function
- hyp2f1(a, b, c, x) == Gauss hyper-geometric function
- hyperg(a, b, x) == confluent hyper-geometric function
- i0e(x) == modified Bessel function of order zero, exponentially scaled
- i1e(x) == modified Bessel function of order one, exponentially scaled
- igam(a, x) == incomplete gamma integral
- igamc(a, x) == complemented incomplete gamma integral
- igami(a, p) == inverse of complemented incomplete gamma integral
- incbet(a, b, x) == incomplete beta integral
- incbi(a, b, y) == Inverse of incomplete beta integral
- index == the index of the current point in the selected set
- irand(n) == random integer less than n
- iv(v, x) == modified Bessel function of order v
- jv(v, x) == Bessel function of order v
- k0e(x) == modified Bessel function, third kind, order zero, exponentially scaled
- k1e(x) == modified Bessel function, third kind, order one, exponentially scaled
- kn(n, x) == modified Bessel function, third kind, integer order
- lbeta(x) == natural log of |beta(x)|
- lgamma(x) == log of gamma function
- ln(x) == natural log
- log10(x) == log base 10
- log2(x) == base 2 logarithm of x
- max(x,y) == returns greater of x and y
- min(x,y) == returns lesser of x and y
- mod(x,y) == mod function (also x % y)
- ndtr(x) == Normal distribution function
- ndtri(x) == inverse of Normal distribution function
- norm(x) == gaussian density function
- pdtr(k, m) == Poisson distribution
- pdtrc(k, m) == complemented Poisson distribution
- pdtri(k, y) == inverse Poisson distribution
- pi == constant PI
- psi(x) == psi (digamma) function
- rad == PI/180.0
- rand == pseudo random number distributed uniformly on (0.0,1.0)
- rint(x) == round to closest integer
- rgamma(x) == reciprocal gamma function
- rnorm(xbar,s) == pseudo random number distributed N(xbar,s)
- shi(x) == hyperbolic sine integral
- si(x) == sine integral
- sin(x) == hyperbolic sine
- sin(x) == sine function
- spence(x) == dilogarithm
- sqr(x) == x^2
- sqrt(x) == x^0.5
- stdtr(k, t) == Student's t distribution
- stdtri(k, p) == functional inverse of Student's t distribution
- struve(v, x) == Struve function
- tan(x) == tangent function
- tanh(x) == hyperbolic tangent
- x == currently selected set X
- y == currently selected set Y
- yv(v, x) == Bessel function of order v
- zeta(x, q) == Riemann zeta function of two arguments
- zetac(x) == Riemann zeta function

Note: See pars.yacc for the yacc grammar.

Examples:

y=-y

y=x*cos(2*x*PI/100)+sqr(x)

x=(index>10)*(x-5)+(index<=10)*x

If the index of the current point is greater than 10 then x=x-5 else x=x. Conditionals evaluate to 0 if false, anything else is true.

a=y

Store y of the current set into scratch array "a". You may now select another set and perform the operation y=somefunctionof(a)

Restrictions:

### Load values

Load a sequence to (x,y) or (a,b,c,d).

### Load and evaluate

Evaluate parametric functions.

Enter the functions to be used to define X and Y.

Select the independent variable (x,y,a,b,c,d).

Enter the start, stop and the number of points items.

Press the button Apply to evaluate the functions and load the result to a new set.

### Histogram

Compute a frequency histogram.

Select the set.

Enter the width of a bin (all bin widths are the same).

Enter the minimum and maximum values of the portion of the data you wish histoed (sic). Note that Xmin and Xmax refer to the RANGE (or Y) of the set, not the domain (or X).

Press Accept to compute the histogram.

### Fourier

Compute the Discrete Fourier transform.

Select the set

Select the type of data window, the default is the rectangular window, i.e., the data are transformed unmodified. The data windows are defined as follows:

None
  Use the default rectangular window
Triangular
  1.0 - |(i-0.5*(N-1))/(0.5*(N-1))|
Hanning
  0.5 * [1-cos(2*pi*i/(N-1))]
Welch
  1-((i-0.5*(N-1))/(0.5*(N+1)))^2
Hamming
  0.54-0.46*cos(2*pi*i/(N-1))
Blackman
  0.42-0.5*cos(2*pi*i/(N-1))+0.08*cos(4*pi*i/(N-1))
Parzen
  1.0 - |(i-0.5*(N-1))/(0.5*(N+1))|

Select the form of the output, magnitude (spectrum), phase, or the coefficients. The spectrum is computed by sqrt(x*x + y*y) where x, y are the coefficients computed by the DFT or FFT. Only N/2 values (representing frequencies 0 to PI) are loaded to the resulting set.

If the magnitude or phase is selected, then the next item, `X = `, determines what values should be loaded to X. The index runs from 0 to n/2, the frequency is the cyclical ith Fourier frequency, the period is the reciprocal of the frequency with the period of the 0th Fourier frequency plotted at T+delta, where T is the total length of the data and delta is the sampling interval.

Select transform or inverse transform.

Select real or complex data.

If real is selected, then the data to be transformed is assumed to be in Y, X is assumed equally spaced and is ignored. If complex is selected then the real part is assumed to be in X and the imaginary part in Y.

Press DFT (for small data sets whose length is not a power of 2) - or FFT (for data sets whose length is a power of 2).

Click on Window only to generated a windowed version of the data in a new set.

NOTE: Small for the DFT is < 1000 points. The DFT is O(N**2) and can be quite time consuming to compute for large N.

### Running averages

Compute a running average, median, minimum, maximum, or standard deviation.

Select the method.

Select the set.

Set the length of the running method in the text item marked Length, it must be less than the set length.

Click on Accept.

### Regression

Perform linear or polynomial regression.

Select the set.

Select the degree of fit.

Select fitted curve or residuals to load.

Press the button marked "Regress".

A set is loaded (if there is one) with the resulting curve and a summary of the statistical results are written to the Result popup.

Notes: The fitting techniques used by xmgr are as follows: For linear fits (y=ax+b) a straightforward least squares procedure is used. For exponential and power fits, the function to fit is linearized, it is important to note that the statistics generated refer to the parameters of the linearized function and not the original function.

### Non-linear curve fitting

1. Select the set you would like to approximate.
2. The unknown parameters to fit are labeled A0 to A9 (case insensitive). Type in the function using the parameters, starting with A0.
3. Enter the number of parameters.
4. Adjust the tolerance.
5. Choose initial values (1 by default) and specify bounds (if required) for the parameters.
6. Specify what you would like to view from Options/Load
   Fitted values
     Value of approximating function at abscissa of selected set
   Residuals
     Error in approximating function at abscissa of selected set
   Function
     Approximating function at abscissa defined by Start, Stop and # of points
7. Run the fitting routine by specifying the number of convergence steps you wish to perform (5/20/100).
8. At any time, you may Load as is the values if Options/autoload is not selected.
9. Look at the results and repeat any of the above steps until satisfied. Results will continue to be loaded to the same newly created set.
10. Press Accept to make the new set permanent or Cancel to destroy it.

Fit definitions can be saved/loaded from the File pull-down menu of the Non-linear fitting popup.

### Differences

Numerical differentiation.

Select the set.

Select the method - one of forward, backward, or centered difference. Assumes unevenly spaced data, increasing in X.

Click on Accept.

A set is loaded (if there is one) with the resulting curve.

### Seasonal differences

Difference a set by a given lag.

Select the set.

Enter the value for the lag. Assumptions are evenly spaced data, increasing in X.

Press the button marked Accept.

Use Pick to use the mouse to select the set by clicking near a point in the set as displayed in the drawing area.

A set is loaded (if there is one) with the resulting curve.

### Integration

Numerical integration.

Select the set.

Select the form of the results, the item marked cumulative sum will construct a set composed of the current value of the integral at a given X. Sum only reports just the value on the next line. Assumes unevenly spaced data, increasing in X.

Press the button marked Integrate.

A set is loaded (if there is one) with the resulting curve if cumulative sum is chosen.

### X-corr

Cross/auto-correlation

Select both sets (use the same set if autocorrelation is desired).

Select the lag, N/3 is a reasonable value (your mileage may vary).

Select bias - generally this will not make any difference for large data sets with lags << the length of the set, I was just curious. The difference is division by N (biased) or N-lag (unbiased). A set is loaded (if there is one) with the resulting curve.

### Interpolation

Create a new set by performing interpolation on one set at abscissas from another set. All sets are in the current graph. This will allow pointwise mathematical operations to be performed between the new set and the set providing the abscissas using the command interpreter.

Choose the set on which to interpolate which will provide the Y values. Select a second set which will provide the X values for the new set.

The interpolation method can be a cubic or Akima spline or linear.

### Spline

Compute a spline fit to a set

Select the set.

Select the starting value of X for the fitted curve.

Select the ending value of X.

Select the number of samples. The spline curve will be evaluated at X+i*(MaxX - MinX)/Nsteps for each i in (0, Nsteps-1).

Select the type of the spline. It could be either plain cubic one or Akima spline. The latter should be preferred when approximating sufficiently non-smooth series.

Press "Spline"

A set is loaded (if there is one) with the resulting curve.

Notes: The code to compute the spline is a literal translation of the code in FMM.

### Sample

Sample a set pointwise or by a logical expression.

Select the set.

Select the type of sample, either Start/step or Logical expression. If Start/step is selected then enter the starting index to begin the sample.

Select the number of points to skip between samples in Step. If Logical expression is selected, enter the expression in the text item denoted Expr:. Values of the expression not equal to zero are interpreted as TRUE, and the point is accepted. Any expression evaluating to zero will result in the point being ignored.

### Prune data

Prune the data of a set by removing points. This is useful if the resolution of your data is higher than the resolution of the graphics device (screen or hardcopy). You can reduce the size of project files and increase the speed of redraws by removing redundant points.

1. Select the set.

2. Select the type of data pruning:

   Interpolation:
     The interpolation type calculates for each point a linear interpolation of that point based on its neighbors and removes the point if real y-value and interpolated y-value differ by less than Delta-Y. The interpolation type requires that the set is sorted: if both x and y are functions of another variable t, i.e. x(t) and y(t), the set has to be sorted by t. It is, of course, possible that x(t)=t.

   Circle, Ellipse, Rectangle:
     These three types remove all points within a circular, elliptical, or rectangular surrounding of previous points in the set. No particular order of points is required. Those types are useful, e.g., for sets that are not quasi-continuous time series but rather discrete maps (just an example: depict the current heart period versus the previous heart period).

3. Select the size of the surrounding (Delta-X and/or Delta-Y).

4. Select whether the size of the surrounding is specified as viewport or world coordinates.

   Viewport coordinates:
     Delta-X and Delta-Y are specified as viewport coordinates. This is most useful if you just want to make a graph and don't care about absolute errors.

   World coordinates:
     Sometimes (for example, in bifurcation diagrams) points (approximately) coincide, and you want to compress the data by removing the "doubles" without significantly increasing the granularity of the data. In other words, you don't care about any specific graphics device but rather about the maximum absolute error caused by pruning. This is important, for example, if you want to use the pruned set for further calculations. In that case, it is better to use world coordinates. You need to specify the type of Delta-X and Delta-Y (linear or logarithmic). They default to the axes types of the current graph. If one of the Deltas is logarithmic, it is considered a factor. For example, interpolation type pruning with logarithmic Delta-Y type and Delta-Y = 2 means to remove all points for which interpolated and real value differ by a factor of less than two.

### Digital filter

Apply a digital filter to a set.

Select the set to be filtered

Select the set with the filter weights.

### Linear convolution

Perform convolution of 2 sets.

### Geometric transformations

Apply rotations, scaling, and translations to a set.

Select the order in which to apply the transformations.

Press the button Apply to perform the transformation.

Press the Reset to reset values and return to the identity transformation.

Press the Reset to reset values and return to the identity transformation.

Restrictions: Only the set X and Y are transformed, additional vectors attached to a set, such as error bars, are not transformed.

### Feature extraction

Given a set of curves in a graph, extract a feature from each curve and use the values of the feature to provide the Y values for a new curve.

Results to graph:
  graph to which new curve is to be assigned. It must be an active graph.
Feature
  feature to be extracted. See table below.
X values from:
  source of X values for the new curve to be generated.
  1. Index - use the number of the curve in the graph, i.e., 1,2,3,...
  2. Legend - use the legend from the curve from which the feature is extracted. This must be a number.
  3. X from set - use the X values from a set specified below
  4. Y from set - use Y values from set specified below
Accept
  generate the curve

Feature | Description
--- | ---
Y minimum | Minimum Y value of set
Y maximum | Maximum Y value of set
Y average | Average Y value of set
Y std. dev. | Standard deviation of Y values
Y median | Median Y value
X minimum | Minimum X value of set
X maximum | Maximum X value of set
X average | Average X value of set
X std. dev. | Standard deviation of X values
X median | Median X value
Frequency | Perform DFT (FFT if set length a power of 2) to find largest frequency component
Period | Inverse of above
Zero crossing | Time of the first zero crossing, + or - going
Rise time | Assume curve starts at the minimum and rises to the maximum, get time to go from 10% to 90% of rise. For single exponential curves, this is 2.2*time constant
Fall time | Assume curve starts at the maximum and drops to the minimum, get time to go from 90% to 10% of fall
Slope | Perform linear regression to obtain slope
Y intercept | Perform linear regression to obtain Y-intercept
Set length | Number of data points in set
Half maximal width | Assume curve starts from the minimum, rises to the maximum and drops to the minimum again. Determine the time for which the curve is elevated more than 50% of the maximum rise.
Barycenter X | Barycenter along X axis
Barycenter Y | Barycenter along Y axis