Action Documentation:


  • y = value(x)

    Returns an identical copy of x in y.


  • y = size(x)

    Returns the length of x.

    The argument x must be an object derived from Sequence.
    The return value y is a Scalar<int>.


  • y = min(x)

    Returns the minimum value of x.

    The argument x must be an object derived from a real Sequence and must have size > 0.
    The return value y is a Scalar<double>


  • y = max(x)

    Returns the maximum value of x.

    The argument x must be an object derived from a real Sequence and must have size > 0.
    The return value y is a Scalar<double>.


  • y = mean(x)

    Returns the mean of x.

    The argument x must be an object derived from a Sequence (which may have complex elements) and must have size > 0.
    The return value y is either a Scalar<double> or a Scalar<complex<double> >.


  • y = rms(x)

    Returns the root-mean-square of x.

    The argument x must be an object derived from a Sequence (which may have complex elements) and must have size > 0.
    The return value y is either a Scalar<double> or a Scalar<complex<double> > and is given by

    y = sum(xk2)/size(x)


  • y = variance(x)

    Returns the variance of x.

    The argument x must be an object derived from a Sequence (which may have complex elements) and must have size > 1.
    The return value y is either a Scalar<double> or a Scalar<complex<double> > and is given by

    y = sum([xk - mean(x)]2)/(size(x) - 1)


  • y = skewness(x)

    Returns the skewness of x.

    The argument x must be an object derived from a Sequence (which may have complex elements) and must have size > 1.
    The return value y is either a Scalar<double> or a Scalar<complex<double> > and is given by

    y = sum([(xk - mean(x)/std(x)]3)/(size(x) - 1)


  • y = kurtosis(x)

    Returns the kurtosis of x.

    The argument x must be an object derived from a Sequence (which may have complex elements) and must have size > 1.
    The return value y is either a Scalar<double> or a Scalar<complex<double> > and is given by

    y = sum([(xk - mean(x)/std(x)]4)/(size(x) - 1) - 3


  • y = all(x)

    Returns the statistics size, min, max, mean, rms, variance, skewness, and kurtosis for x.

    The arguments array x must be an object derived from a real Sequence with size > 1.
    The returned object y is a Stats object whose components are the same as those for the individual statistics.


  • y = slice(x, start, size, stride)

    Copies the indicated subarray (slice) of x into y.

    The slice() action acts on any type derived from a Sequence and returns an object of the same type, consisting of the first size elements of x, starting at start and increasing by stride. Metadata is interpreted for types derived from Sequence.

    The return value y is of the same type as x and is given by

    yk = xstart + k*stride         for k = 0, 1, ..., size - 1

    Example 1
    This example copies the first 1024 elements of raw into x.

    
    x = slice(raw, 0, 1024, 1);
    
    

    Example 2
    This example copies every 2nd element of raw into x.

    
    x = slice(raw, 0, 1024, 2);
    
    


  • y = fft(x)

    Takes the discrete Fourier transform of x using the Fast Fourier Transform algorithm where possible.

    The input sequence x may be real or complex, and of single or double precision.

    The return value y is a sequence in the frequency domain with the same precision and size as x.
    Note that a DFT frequency series is a distinct data type from the sequences manipulated by other actions. It's elements are always complex numbers, although a real frequency series may be represented as having vanishing imaginary components.

    The convention adopted for the Fourier transform is that the coefficient of i in the exponential is -1, that is

    yk = sum(xn e-i2 pi k n/N),        n = 0, 1, ..., N-1

    Example
    This example copies the first 1024 elements of raw into x, then takes the Fourier transform of x, putting the result into y.

    
    x = slice(raw, 0, 1024, 1);
    y = fft(x);
    
    


  • y = fillgaps(x [, method ])

    Returns a time-series y which is identical to x, except that data known to be missing in x is filled in.

    The input x must be a real time-series.
    The input method must be an integer. See below for allowed values.

    When channel data is read from the frame API, it is possible that there are gaps in the data where frame files are missing or corrupted. Time-series objects in the dataconditioning API keep a record of the position of any missing data. The fillgaps() action returns a time-series object which is an identical copy of its first argument, except that any missing data is filled in using the method indicated in the second argument. The allowed values for method are:

    0 - fill the gaps with zero. This is the default.
    1 - fill the gaps with the average value of all data in x which is not part of a gap.
    2 - fill the gaps by drawing a straight line between the value immediately before the gap and and the value immediately after the gap. If the gap includes the first sample, then the whole gap is filled with the value immediately following the gap. If the gap includes the last sample, the whole gap is filled with the value immediately preceding the gap.

    Example
    This example copies the elements of x into y, except for data in the gaps of x. In y, the gaps are filled with the average of all the data in x which is not in a gap. This means that if all the elements of x are one except in a gap, y will be all ones.

    
    y = fillgaps(x, 1);
    
    


  • b = firlp(fc, order [, window ])

    Returns an array of coefficients suitable for constructing a FIR low-pass filter.

    Input arguments:
    fc - the frequency cutoff of the low-pass filter, in units of Nyquist frequency. Must be a Scalar<double> between 0.0 and 1.0.
    order - the order of the filter. Must be a positive Scalar<int>. The length of the returned sequence of coefficients will be order + 1.
    window - a window used in construction of the filter coefficients. By default a
    KaiserWindow() with beta = 5.0 is used. This is the same as the default low-pass filter used in resample().

    This action returns a Sequence<double> of length order + 1 containing the filter coefficients of a FIR low-pass filter, which may be used as an argument to the linfilt() action. The filter removes frequency components above the cutoff frequency fc, which must be provided in units of the Nyquist frequency and so is always a value between 0.0 and 1.0.

    Example
    Create a filter that passes frequencies below 0.5 Nyquist:

    
    w = KaiserWindow(5.0);
    b = firlp(0.5, 100, w);
    y = linfilt(b, x);
    
    


  • y = lineardetrend(x)

    Returns a sequence or time-series y obtained by detrending x with a least-squares linear fit.

    The input x must be a sequence or time-series.
    Note: Time-series objects keep track of "gaps" in their data ie. portions of time where the data was unavailable. Data in gaps is ignored for the purpose of detrending: it does not contribute to the least-squares fit and is not changed by detrending. The
    fillgaps() action may be used to set data values in gaps.

    Example

    
    y = lineardetrend(x);
    
    


  • y = meandetrend(x)

    Returns a sequence or time-series y obtained by detrending x by subtracting the mean.

    The input x must be a sequence or time-series.
    Note: Time-series objects keep track of "gaps" in their data ie. portions of time where the data was unavailable. Data in gaps is ignored for the purpose of detrending: it does not contribute to the mean and is not changed by detrending. The
    fillgaps() action may be used to set data values in gaps.

    Example

    
    y = meandetrend(x);
    
    


  • y = ifft(x)

    Takes the inverse discrete Fourier transform of the x using the Fast Fourier Transform algorithm where possible.

    The input sequence x must be a frequency series with either single or double precision.
    The return value y is a sequence with the same precision and size as x. If x is conjugate symmetric then y is a real sequence, otherwise it is complex.

    The conventions adopted for the inverse Fourier transform are that the coefficient of i in the exponential is +1 and the returned sequence is scaled by 1/N where N is the length of x, that is

    yk = (1/N) sum(xn ei2 pi k n/N),        n = 0, 1, ..., N-1

    Example
    This example copies the first 1024 elements of raw into x, then takes the Fourier transform of x, putting the result into y. The inverse Fourier transform of y is then copied into x2. Because of our choice of conventions, x2 should be identical to x up to rounding error.

    
    x = slice(raw, 0, 1024, 1);
    y = fft(x);
    x2 = ifft(y);
    
    


  • y = integer(x)

    Converts a floating-point scalar value to an integer.

    The input parameter x must be either a Scalar<float> or Scalar<double>.
    The return value y is a Scalar<int>.

    This action rounds x to the nearest whole floating-point value, casts it to an integer type and returns it in y.


  • w = HannWindow()

    Generates a Hanning window for use in psd() or csd().

    When applied to a sequence x of length n, the result is to multiply the kth element of x by 0.5*(1.0 - cos(2*pi*k/(n-1))).

    NOTE: this is not the same definition used by Matlab.

    No size argument is required: a window resizes itself to operate on any length input.


  • w = KaiserWindow([beta])

    Generates a Kaiser window for use in psd() or csd().

    The optional input parameter beta must be a non-negative real number. The default is 0.
    No size argument is required: a window resizes itself to operate on any length input.


  • w = RectangularWindow()

    Generates a Rectangular window for use in psd() or csd().

    No size argument is required: a window resizes itself to operate on any length input.


  • y = psd(x , [ fft_length ], [ window ], [ overlap_length ], [ detrend ])

    Returns an estimate of the power spectral density of x using Welch's method.

    A Welch PSD estimate is defined by an FFT length, overlap length, a choice of window function, and a detrend option.
    The input sequence x may be real or complex, and of single or double precision.
    The optional input parameter fft_length must be a positive integer (default is 1024).
    The optional input parameter window indicates which type of windowing is to be used (default is to use a Hanning window).
    The optional input parameter overlap_length must be a non-negative integer (default is 0).
    The optional input parameter detrend indicates which type of detrending is to be used. A value of 0 indicates no detrending, a value of 1 indicates that the mean will be removed from the data, and a value of 2 indicates that linear trends will be removed (default is 0).

    Any optional parameter may be replaced with an underscore character _ to indicate that the default value should be used.
    Any trailing optional parameter may be omitted.

    The PSD is estimated by averaging modified periodograms of (possibly) overlapping segments of the input data. The return value y is a real sequence with the same precision as x. When the x is real, the output is a 1-sided power spectrum with length fft_length/2 + 1 and the result is scaled so that

    y0 = 1/(srate×N×wrms2) × <|X0|2>
    yk = 2/(srate×N×wrms2) × <|Xk|2>, 1 <= k <= [(N - 1)/2]
    yN/2 = 1/(srate×N×wrms2) × <|XN/2|2> (only if N even)

    where X denotes the DFT of x, srate is the sampling rate of x, N = fft_length and wrms is the root-mean-square of the window being used. The brackets denote ensemble average.

    When the x is complex, the output is a 2-sided power spectrum with length fft_length and the result is scaled so that

    yk = 1/(srate×N×wrms2) × <|X(N+1)/2 + k|2>, 0 <= k <= N/2 - 1
    yk = 1/(srate×N×wrms2) × <|Xk - N/2|2>, N/2 <= k <= N - 1

    That is, the value of the spectrum at DC frequency is moved to the center of the range at yN/2, and the value at Nyquist frequency is moved to y0. In either case, the scaling conventions guarantee that the equality

    (1/srate) × sum(|x|2) = number_of_segments × sum(y)

    holds when a RectangularWindow is used and the overlap between segments is set to zero.

    Example 1
    In the following, a default window is indicated by the underscore, and default detrending is indicated by omitting the last parameter.

    
    x = slice(raw, 0, 4096, 1);
    y = psd(x, 1024, _, 512);
    
    

    Example 2
    In the following, a Kaiser window and linear detrending are used.

    
    x = slice(raw, 0, 4096, 1);
    w = KaiserWindow(0.1);
    y = psd(x, 1024, w, 512, 2);
    
    


  • x = ramp(n, dx [, x0])

    Returns a Sequence<double> with values set from a ramp.

    Input arguments:
    n - length of the sequence to be produced. Must be a non-negative integer.
    dx - step-size of the ramp. Must be an integer or double.
    x0 - starting value of the ramp (default 0). Must be an integer or double.

    The output x is a Sequence<double> of length n where

    xk = x0 + k*dx,        k = 0, 1, ..., n - 1

    Example 1
    Produces a ramp sequence of length 100, starting at 2.0 with a step-size of 0.01:

    
    x = ramp(100, 0.01, 2.0);
    
    

    Example 2
    Produces a sequence of length 50 and constant value 1.0:

    
    x = ramp(50, 0.0, 1.0);
    
    


  • y = rmvm(x, freqs, Qs, fc, deltaf, W, V, down, fs)

    Removes lines from input data x via Kalman filtering.

    Input arguments:
    x - the input data, provided as a real TimeSeries or Sequence.
    freqs - a list of frequencies of lines to be removed, provided as a real Sequence or Scalar.
    Qs - a list of Q values, one for each frequency in freqs, provided as a real Sequence or Scalar, indicies of Qs correspond to those of indicies of freqs.
    fc -the frequency that will be shifted to zero in the z-transformation, this corresponds to the central frequency of the band to be filtered and for best results should be as close to the values in freqs as possible provided as a real Scalar.
    deltaf - the width of the region around fc (in Hz) to be filtered (so the filter works on data from fc - deltaf/2 to fc + deltaf/2). This should be a power of 2.
    W - the process noise(s) that correspond to each line, provided in a real Sequence or Scalar with indicies corresponding to those of the freqs.
    V - the measurement noise, which is a single number.
    down - the factor to downsample by when performing the z-transform (it should be fs/deltaf and must be a Scalar<int>).
    fs - the sampling frequency of of input data x.

    The length of data must be an integer multiple of down due to restrictions in resample(), and the lengths of freqs, Qs, and W must be the same. The action zero-pads the incoming data to account for delays induced by resampling so the output is the same length as the input.

    Output:
    y - the output data, this is the input data with the line contributions as predicted by the Kalman Filter removed.

    This action uses a Kalman Filter algorithm to estimate the line contributions to the signal so they can be subtracted. The Kalman filter is an adaptive filter that uses a transform from the observations of the detector to produce the state of the system producing the line. With this information it is possible to predict the component of the detector output that is due to the noise sources that need to be removed.

    The arguments f0s, Qs, fc, and deltaf are used in the calculation of the transfrom of the prediction of the state from one sample time to the next.
    The arguments fs, fc, and down are used to restrict the region the filter operates on to a narrow region in the frequency domain around the lines that are to be removed.
    The W and V arguments represent noise of the process and measurement respectively. As the observable is assumed to be contaminated by an additive Gaussian measurement noise while the dynamical system described by the state is driven by a known input and a Gaussian process noise.

    See Finn and Mukherjee 2001 for an indepth explanation and derivation of the algorithm this action uses.

    Example 1
    This example removes a single line at 513.049. Currently MATLAB is used in the determination of the arguments.

    
    y = rmvm(data,513.049,56000,513,8,.3408e-9,.9738e-7,2048,16384);
    
    

    Example 2
    This example removes multiple lines. In this example f0s_arg, Qs_arg, and W_arg are read in from files.

    
    y = rmvm(data, f0s_arg, Qs_arg, 513, 8, W_arg,.9738e-7,2048,16384);
    
    


  • z = csd(x, y, [ fft_length ], [ window ], [ overlap_length ], [ detrend ])

    Returns an estimate of the cross-spectral density of x and y using Welch's method.

    A Welch CSD estimate is defined by an FFT length, overlap length, a choice of window function, and a detrend option.
    The input sequences x and y must be the same length but may be real or complex, and of single or double precision.
    The optional input parameter fft_length must be a positive integer (default is 1024).
    The optional input parameter window indicates which type of windowing is to be used (default is to use a Hanning window).
    The optional input parameter overlap_length must be a non-negative integer (default is 0).
    The optional input parameter detrend indicates which type of detrending is to be used. A value of 0 indicates no detrending, a value of 1 indicates that the mean will be removed from the data, and a value of 2 indicates that linear trends will be removed (default is 0).

    Any optional parameter may be replaced with an underscore character _ to indicate that the default value should be used.
    Any trailing optional parameter may be omitted.

    The CSD is estimated by taking segments of length fft_length of x and y and averaging the product of conj(fft(x)) and fft(y) over each segment of (possibly) overlapping segments of the input data. The return value z is a complex sequence of length fft_length with the same precision as the highest precision of x or y. When both x and x are real, the output is a 1-sided spectrum with length fft_length/2 + 1 and the result is scaled so that

    z0 = 1/(srate×N×wrms2) × <X0*Y0>
    zk = 2/(srate×N×wrms2) × <Xk*Yk>, 1 <= k <= [(N - 1)/2]
    zN/2 = 1/(srate×N×wrms2) × <XN/2*YN/2> (only if N even)

    where X denotes the DFT of x, * is the complex conjugate, srate is the sampling rate of x, N = fft_length and wrms is the root-mean-square of the window being used. The brackets denote ensemble average.

    When either of the inputs is complex, the output is a 2-sided spectrum with length fft_length and the result is scaled so that

    zk = 1/(srate×N×wrms2) × <X(N+1)/2 + k*Y(N+1)/2 + k>, 0 <= k <= N/2 - 1
    zk = 1/(srate×N×wrms2) × <Xk - N/2*Yk - N/2>, N/2 <= k <= N - 1

    Example 1
    In the following, a default window is indicated by the underscore, and default detrending is indicated by omitting the last parameter.

    
    z = csd(x, y, 1024, _, 512);
    
    

    Example 2
    In the following, a Kaiser window and linear detrending are used.

    
    w = KaiserWindow(0.1);
    z = csd(x, y, 1024, w, 512, 2);
    
    


  • y = resample(x, p, q[, z])
  • y = resample(x, p, q, n[, z])
  • y = resample(x, p, q, n, beta[, z])
    or
  • y = resample(x, z)

    Resample a Sequence or TimeSeries x by the ratio p/q, or using the information contained in the state variable z. Metadata such as start-time and sampling rate is altered according to the type of x.

    The input x may be real or complex, and of single or double precision.
    The length of x must be a multiple of q.
    The upsampling ratio p and downsampling ratio q must be positive integers. If p and q are not relatively prime, they are divided by their greatest common divisor before resampling is performed.
    The integer n has a default value of 10. It controls the order of the anti-aliasing filter, which is given by 2*n*max(p, q).
    NOTE: The value of n should not be altered from its default value without good reason. If set too small, it can affect the integrity of the resampled data by making the anti-aliasing filter too short. On the other hand, making it larger can greatly increase the computation time of the resampling operation.
    The positive real number beta has a default value of 5 and is the shape parameter of the
    Kaiser window used to construct the anti-aliasing filter.
    The return value y is of the same type as x, and has size (p/q)*size(x).
    The argument z holds the internal state of the resampler. This allows an input sequence or time series to be broken up into several parts and filtered as though it were a continuous sequence or time-series. If resample() is called in one of the first three forms, z is an output-only parameter and whatever value (if any) it has are overwritten. If resample() is called in the in the fourth form, z is an input-output parameter. It must have been initialised to a ResampleState variable by a previous call to resample(), and on output the state is updated to reflect the resampling done in that stage.

    As an alternative to resampling in the dataconditioning API, a subset of resampling restricted to downsampling by powers of 2 is available in the -framequery option. This has the advantage of performing resampling "upstream" in the data pipeline to greatly reduce memory useage, CPU useage and communication overhead.

    Note that resampling introduces a delay so that the start-time of y is n*max(p, q)/q samples earlier than the start-time of x. The delay can be removed by first obtaining its value from z using getResampleDelay(), then removing it from y using shift(). An exception to this is when p == q, in which case no actual resampling is done: the output is identical to the input and the delay is zero.

    Example 1

    
    x1 = slice(raw,0,100,1);
    x2 = slice(raw,100,50,1);
    x3 = slice(raw,0,200,1);
    y1 = resample(x1, p, q, z);
    y2 = resample(x2, z);
    y3 = resample(x3, p, q);
    
    y1 is equal to slice(y3,0,100,1);
    y2 is equal to slice(y3,100,50,1);
    

    Example 2

    The script

    
    ldasJob { -name myname -password mypasswd } {
       dataPipeline
         -framequery { F H {} 658020034-658020035 Adc(H2:LSC-AS_Q!resample!8!) }
         -datacondtarget frame
         -aliases { rgw = _ch0; }
         -algorithms {
            output(rgw, _, _, rgw, resampled gw data);
         }
    }
    
    
    produces the same result as
    
    ldasJob { -name myname -password mypasswd } {
       dataPipeline
         -framequery { F H {} 658020034-658020035 Adc(H2:LSC-AS_Q) }
         -datacondtarget frame
         -aliases { gw = _ch0; }
         -algorithms {
            rgw = resample(gw, 1, 8); 
            output(rgw, _, _, rgw, resampled gw data);
         }
    }
    
    


  • y = resample2(x, srate[, z])
  • y = resample2(x, srate, n[, z])
  • y = resample2(x, srate, n, beta[, z])
    or
  • y = resample2(x, z)

    Resample a TimeSeries x to the target sampling rate srate, or using the information contained in the state variable z. Metadata such as start-time and sampling rate is altered according to the type of x.

    The input x may be real or complex, and of single or double precision. The length of x must be such that (srate/old_srate)*size(x) is an integer.
    The input srate must be a strictly positive real number.
    The integer n has a default value of 10. It controls the order of the anti-aliasing filter.
    NOTE: The value of n should not be altered from its default value without good reason. If set too small, it can affect the integrity of the resampled data by making the anti-aliasing filter too short. On the other hand, making it larger can greatly increase the computation time of the resampling operation.
    The positive real number beta has a default value of 5 and is the shape parameter of the
    Kaiser window used to construct the anti-aliasing filter.
    The return value y is of the same type as x, and has size (srate/old_srate)*size(x).
    The argument z holds the internal state of the resampler. This allows an input time-series to be broken up into several parts and filtered as though it were a continuous time-series. If resample2() is called in one of the first three forms, z is an output-only parameter and whatever value (if any) it has are overwritten. If resample2() is called in the in the fourth form, z is an input-output parameter. It must have been initialised to a ResampleState variable by a previous call to resample2(), and on output the state is updated to reflect the resampling done in that stage.

    The resample2() action is implemented using the same underlying mechanism as resample(). The only extra step is to first find integers p and q such that p/q is close to srate/old_srate. For many cases of practical interest (such as LIGO data analysis) the sampling rates will be whole numbers to begin with and so p and q may be found exactly. In other cases a close approximation will be used but it should be noted that this could yield impractically large values of p and q.

    As in resample(), resampling introduces a delay so that the start-time of y is n*max(p, q)/q samples earlier than the start-time of x. The delay can be removed by first obtaining its value from z using getResampleDelay(), then removing it from y using shift(). An exception to this is when srate == old_srate, in which case no actual resampling is done: the output is identical to the input and the delay is zero.

    Example
    Suppose x is a TimeSeries<float> of length 128 with a sampling rate of 16384 Hz. We can resample it to 2048 Hz in one step:

    
    y = resample2(x, 2048.0);
    
    
    or multiple steps:
    
    x1 = slice(x, 0, 64, 1);
    x2 = slice(x, 64, 64, 1);
    y1 = resample2(x1, 2048.0, z);
    y2 = resample2(x2, z);
    y = concat(y1, y2);
    
    
    and get the same result.


  • y = respfilt(x, response, sense, alphas, gammas [, direction])

    Contruct a transfer function from calibration data and apply it to a time-series.

    Input parameters:

  • x - a real TimeSeries.
  • response - a FrequencySequence<complex<float> > representing a response function.
  • sense - a FrequencySequence<complex<float> > representing a sensing function.
  • alphas and gammas - TimeSeries<complex<float> >s representing calibration measurements taken over a period of time.
  • direction (optional) - a Scalar<int> flag indicating direction in which to perform the transformation. A value of 0 indicates that the input is transformed using the constructed transfer function, while a value of 1 indicates that the inverse of the transfer function is used. The default is 0.

    Result:

  • y - a real TimeSeries with the same precision, size and meta-data as x, containing data obtained by applying the transfer function to x.

    This action uses calibration information from a frame file to construct a transfer function, which is applied to the input time-series.

    The function has an option to specify the "direction" of the transformation. If the value of direction is 0, it is assumed that the input contains data in units of "strain". On return, the time-series will have been convolved with the transfer function so that it is in the form of "ADC counts".

    If the value of direction is 1, it is assumed that the input contains data in units of "ADC counts". On return, the time-series will have been convolved with the inverse of the transfer function so that it is in the form of "strain".

    The input arguments are the response function R(f), the sensing function C(f), and time-series alphas(t) and gammas(t) representing a series of measurements based on calibration lines injected into the interferometer data. The transfer function T(f) is constructed in the following manner. First, the values of alpha and gamma at the start-time of x are determined (if this start-time falls outside the time-interval spanned by either alphas or gammas, an error is generated). Then, the transfer function is obtained via

    T = alpha*C/(1 + gamma*H) where H = C*R - 1

    T(f) is then interpolated to the frequency-spacing of x, and extended to a 2-sided transfer function. The Fourier transform of x is then calculated and multiplied by T(f) (or 1/T if direction is 1). The final result y is obtained using the inverse Fourier transform.

    An error will be generated if any of the following conditions occur:

  • x has zero size.
  • response and sense have different frequency content ie. different start frequency, frequency resolution or size.
  • response and sense have size < 2.
  • the start-time of x lies outside the range of times spanned by alphas or gammas.
  • either the calculated alpha or gamma has a magnitude close to zero (less than 1.0e-12).
  • the final transfer function has any infinite or NaN points (this could happen if the denominator of the transfer function contains zeros).
  • direction has a value other than 0 or 1.

    NOTE: This action is still in the experimental stage of development and results from it should be treated as preliminary.

    Example
    Use of
    respfilt() requires data in a specific form, as provided in LIGO calibration frame files generated by SenseMon. For this reason we provide a full dataPipeline example. The conventions adopted for the names of the calibration channels in SenseMon frames are:

  • CAL-RESPONSE - response
  • CAL-CAV_GAIN - sense
  • CAL-CAV_FAC.mean - alphas
  • CAL-OLOOP_FAC.mean - gammas
    preceded by an interferometer identifier (H1:, H2: or L1:). Since the SenseMon data is stored as an array of real double-precision numbers, we first need to convert them to single-precision complex numbers.
    dataPipeline
      -framequery {
       { R H {} 727577888-727578207 adc(H1:LSC-AS_Q!resample!4!) }
       { SenseMonitor_H1_M H {} 727577872-727640271 adc(H1:CAL-CAV_FAC.mean,H1:CAL-OLOOP_FAC.mean) }
       { CAL_REF H {} 715156759-715156822 Proc(H1:CAL-CAV_GAIN!0!2048!,H1:CAL-RESPONSE!0!2048!) }
      }
      -aliases {
        as_q = LSC-AS_Q;
        R = CAL-RESPONSE;
        C = CAL-CAV_GAIN;
        A = CAL-CAV_FAC;
        G = CAL-OLOOP_FAC;
      }
      -algorithms {
        # Promote SenseMon data to complex float 
        alphas = float(A);
        alphas = complex(alphas);
    
        gammas = float(G);
        gammas = complex(gammas);
    
        # Apply the calibration data
        result = respfilt(as_q, R, C, alphas, gammas, 1);
        output(result, _, _,, Data as strain);
      }
      -datacondtarget datacond
      -outputformat { ilwd ascii }
    


  • y = reverse(x)

    Returns a Sequence-based object of the same type as x but with the elements reversed.

    The argument x may be of any type derived from Sequence.
    The return value y has the same type and meta-data as x. The elements of y are the elements of x in reverse order.


  • getFilterCoeffs(state, fir_coefficents [, iir_coeffiecents])

    Extracts the FIR (and optionally IIR) filter coefficients from a suitable state object.

    The input state must be a state object for an action that uses a linear filter. Actions for which getFilterCoeffs() is currently supported are arls(), oelslr(), mix() and resample().
    The output fir_coefficents will contain the Finite Impulse Response filter coefficients associated with state, in a format suitable for initialising a linear filter.
    The optional output iir_coefficents will contain the Infinite Impulse Response filter coefficients associated with state, in a format suitable for initialising a linear filter. If the state contains only an FIR filter, the identity IIR filter is returned.

    Example:

    y = resample(x, 1, 2, z);
    getFilterCoeffs(z, b);
    


  • delay = getResampleDelay(z)

    Returns the delay associated with the ResampleState x, in samples. Can be used as the input to shift() to correct for the resampling delay.

    Example

    Resample some data, and then shift it by the correct number of samples so that y2 starts at the same time as x.

    
    y1 = resample(x, p, q, z);
    offset = getResampleDelay(z);
    y2 = shift(y1, offset, 1);
    
    


  • y = getSequence(x)

    Returns the Sequence component of x.

    Input arguments:
    x - must be an object derived from Sequence

    The purpose of this action is to extract the Sequence component from a more specialised object such as a TimeSeries, ignoring any other meta-data associated with the object. This is useful when, for example, it is necessary to do arithmetic on two TimeSeries that start at different times.

    The output y is a Sequence with the same Sequence data as x.


  • y = linfilt(b, x [, z ])
  • y = linfilt(b, a, x [, z ])
    or
  • y = linfilt(x, z)

    Applies a linear filter to the sequence x.

    The transfer function coefficients b and a must be double-precision real sequences.
    The input x is either a Sequence<T> or a TimeSeries<T>, where T may be float, double or complex<float> or complex<double>.
    The optional argument z stores the internal state of the linear filter. This allows a sequence that is broken up into several parts to be filtered as though it were a continuous sequence.
    The return value y is of the same type and size as x and has the same metadata (except for the channel name, which is derived from the input and the transfer function).

    This action applies a linear filter to the sequence x, returning the result in y. When invoked in the first form, the transfer function is constructed from the input sequences b and (optionally) a. If a is omitted it defaults to a sequence of length 1 with a0 = 1. If the state parameter z is provided, it is initialized with state information including the filter coefficients. On return, it also contains a record of previous calculations which allows the filter to be applied to a new sequence as if it were contiguous with the previous sequence.

    When invoked in the second form, the filter coefficients are read from the state variable z, which must have been initialized by a previous call to linfilt(). The state variable carries a record of previous data that it has been applied to, so the input sequence x is filtered as if it continued on from where the last sequence that z was applied to ended.

    Before being applied to the input data, the coefficients provided by the user are divided by a0, that is, we apply the substitutions

    b := b/a0
    a := a/a0.

    With b and a redefined as above, the output sequence y is given by

    yk = b0 xk + b1 xk-1 + ... + bN xk-N - a1 yk-1 - a2 yk-2 - ... - aM yk-M

    where N+1 is the length of b and M+1 is the length of a. Note that a0, the coefficient of yk, does not appear because it has been scaled to 1.

    The calculation is carried out using the "direct form II transposed" method, that is,

    yk = b0 xk + z0
    z0 = b1 xk - a1 yk + z1
    z1 = b2 xk - a2 yk + z2
    .
    .
    .
    zL-2 = bL-1 xk - aL-1 yk + zL-1
    zL-1 = bL xk - aL yk

    where the length of z is L = max(M, N) and the filter coefficient sequences have been padded with zeroes to length L+1.

    Note: When the filter is applied to data for the first time, samples prior to the start of the sequence are treated as zero. This is implemented by initially setting all values z0, z1, ..., zL-1 to zero. On exit from linfilt(), the current values of the z sequence are stored in the state variable for use on the next segment of data.

    In the z-transform domain, the description of the filtering operation is

    Y(z) = H(z) X(z)

    where

    H(z) b0 + b1 z-1 + ... + bN z-N
    =
    1 + a1 z-1 + ... + aM z-M

    is the filter transfer function.

    Example 1:

    
    y1 = linfilt(b, a, x);
    y2 = linfilt(b, x);
    
    
    y1 is the result of filtering x by the IIR filter whose transfer function coefficients are b and a.
    y2 is the result of filtering x by the FIR filter whose transfer function coefficients are b.

    Example 2:

    
    y = linfilt(b, a, x);
    
    x1 = slice(x, 0, 50, 1);
    x2 = slice(x, 50, 50, 1);
    
    y1 = linfilt(b, a, x1, z1);
    y2 = linfilt(x2, z1);
    
    
    y is the result of filtering x using the coefficients b and a.
    x1 is the first 50 elements of x.
    x2 is the second 50 elements of x.
    y1 is the result of filtering x1 using the coefficients b and a i.e., it is equal to the first 50 elements of y.
    z1 is set to the filter state after the last sample of x1 is processed. Any initial information in z1 is replaced.
    y2 is the result of filtering x2 using the filter information in the state z1 i.e., it is equal to the last 50 elements of y.
    z1 is set to the filter state after the last sample of x2 is processed.


  • y = filtfilt(b, x)
  • y = filtfilt(b, a, x)

    Applies a zero-phase forward and reverse filter to x.

    The transfer function coefficients b and a may be either single- or double-precision real sequences.
    The input x is either a Sequence<T> or a TimeSeries<T>, where T may be float, double or complex<float> or complex<double>.
    The return value y is of the same type and size as x and has the same metadata.

    This action applies the linear filter defined by b and a to the sequence x, exactly as described in the linfilt() action, then it reverses the result, applies the filter to the reversed data, and reverses the data again, returning the result in y. The result has zero phase distortion. Note that unlike the Matlab function of the same name, no attempt is made to correct for end effects, the data is simply treated as if it were padded with zeroes at each end. In the case of a simple FIR filter (ie. when a == 1) the first and last size(b)-1 samples are affected and should be ignored or sliced off.

    Example 1:

    
    y = filtfilt(b, a, x);
    
    
    produces the same result as
    
    y = linfilt(b, a, x);
    y = reverse(y);
    y = linfilt(b, a, y);
    y = reverse(y);
    
    


  • z = zpg2linfilt(zeroes, poles, gain)

    Constructs a linfilt() state from the zeroes, poles and gain of a transfer function.

    Input parameters:

  • zeroes - a Sequence<complex<double> > representing the roots of the numerator of the transfer function.
  • poles - a Sequence<complex<double> > representing the roots of the denominator of the transfer function.
  • gain - a Scalar<double> representing the overall gain applied to the numerator of the transfer function.

    Result:

  • z - a LinFilt state.

    The zpg2linfilt() action allows a linear filter state object to be constructed from a specification of the zeroes, poles and gain of the z-domain transfer function H(z). The zeroes (poles) must be provided as a sequence of double-precision complex numbers, which are expanded to give the coefficients of the numerator (resp. denominator) polynomial in z. In this implementation the polynomials are required to have real coefficients, so the array of zeroes (resp. poles) is expanded in the following fashion. If the kth element of zeroes (resp. poles) rk is purely real, then rk contributes the linear factor (z - rk) to the polynomial. On the other hand, if rk has non-zero imaginary component, then in order for the polynomial to be real its complex conjugate must also be a root. For this reason, if rk has non-zero imaginary component it contributes a quadratic factor (z - rk)(z - conj(rk)) to the polynomial. Note that only one element of the complex-conjugate pair of roots should be specified in the zeroes (resp. poles) array. In the case that the zeroes (resp. poles) array is empty, the result is the constant polynomial P(z) = 1. This allows for the specification of an all-zeroes (resp. all-poles) filter. Finally, the coefficients of the numerator polynomial are multiplied by the (real) gain factor.

    Example:

    If the parameter to zpg2linfilt() have the values:

        zeroes[0] = 1
        zeroes[1] = 1 + i
    
        poles[0] = 1
        poles[1] = 1 - 2 i
        poles[2] = 1 + 3 i
    
        gain = 3
    
    then the transfer function expands to:
    H(z) 3(z - 1)(z - (1 + i))(z - (1 - i))
    =
    (z - 1)(z - (1 - 2i))(z - (1 + 2i))(z - (1 + 3i))(z - (1 - 3i))
     
    -6 + 12 z - 9 z2 + 3 z3
    =
    -50 + 80 z - 49 z2 + 23 z3 - 5 z4 + z5

    To apply this transfer function to data x, the linear filter state object is constructed and then used as an argument to the linfilt() action:

        z = zpg2linfilt(zeroes, poles, gain);
        y = linfilt(x, z);
    
    This is equivalent to filtering x using filter coefficients b and a where b contains the coefficients of the numerator of H(z) and a contains the coefficients of the denominator of H(z).


  • y = mix(phi, freq, x [, z ])
    or
  • y = mix(x, z)

    Mixes a sequence x with phase phi and frequency freq.

    The phase phi and frequency freq must be double-precision real numbers. Phase is always specfied in radians and frequency as a fraction of the Nyquist frequency, so that -1 <= freq <= 1.
    The input x must be a Sequence or a TimeSeries; the output is a Sequence or a TimeSeries, of complex type: i.e., if the input is a TimeSeries<float> the output is a TimeSeries<complex<float> >.
    Metadata is interpreted: e.g., when applied to a TimeSeries, the frequency is internally converted to physical units.
    The value of the phase argument phi is updated to reflect the final internal phase of the mixer. This allows a sequence that is broken up into several parts to be mixed as though it were a continuous sequence.
    z is a MixerState object. When used in the form

  • y = mix(phi, freq, x, z)
    z is ignored on input but set on return.
    When used in the form
  • y = mix(x, z)
    the phase and frequency are obtained from z, which is updated on return.


    Unary Functions

    With all unary functions, the output type is the same as the input type. Except as noted, unary functions operate on the following data types:

    Supported data types for Unary Functions
    Input Type
    Scalar<int>
    Scalar<double>
    Scalar<complex<double > >
    Sequence<float>
    Sequence<double>
    Sequence<complex<float > >
    Sequence<complex<double > >


  • y = ceil(x)
  • For a list of supported input types for x, please refer to Unary Functions.

    Computes the ceil of x. When x is complex, the ceil operation is perfomed on the real and the imaginary components of x. When x is a sequence, then the ceil operation is performed on each element of the sequence.


  • y = floor(x)
  • For a list of supported input types for x, please refer to Unary Functions.

    Computes the floor of x. When x is complex, the floor operation is perfomed on the real and the imaginary components of x. When x is a sequence, then the floor operation is performed on each element of the sequence.


  • y = round(x)
  • For a list of supported input types for x, please refer to Unary Functions.

    Computes the rounded value of x. When x is complex, the round operation is perfomed on the real and the imaginary components of x. When x is a sequence, then the round operation is performed on each element of the sequence.


    Arithmetic functions

    Four basic binary arithmetic operations are supported: add(), sub(), mul() and div(). Arithmetic on several combinations of data types (Sequence, Scalar) and element types (float, double, complex float, complex double) are supported, but not all. The following table lists the combinations that are currently allowed:

    Supported combinations of types
    Result typeFirst argument typeSecond argument type
    Scalar<int>Scalar<int>Scalar<int>
    Scalar<double>Scalar<double>Scalar<int>
    Scalar<double>Scalar<int>Scalar<double>
    Scalar<double>Scalar<double>Scalar<double>
    Sequence<float>Sequence<float>Scalar<int>
    Sequence<float>Scalar<int>Sequence<float>
    Sequence<float>Sequence<float>Scalar<double>
    Sequence<float>Scalar<double>Sequence<float>
    Sequence<float>Sequence<float>Sequence<float>
    Sequence<double>Sequence<double>Scalar<int>
    Sequence<double>Scalar<int>Sequence<double>
    Sequence<double>Sequence<double>Scalar<double>
    Sequence<double>Scalar<double>Sequence<double>
    Sequence<double>Sequence<double>Sequence<double>

    When both arguments to an arithmetic operation are Sequences, they must have the same size.

  • y = add(x, z)

    Not all combinations of arguments are currently supported, see Arithmetic functions.

    Adds x and z to produce y.
    The arguments x and z may be of any type. If both are sequences, they must be of the same size.
    The return value y is of same precision as the arguments, or, if the precisions of the arguments are different, is of single precision (unless neither argument is a sequence, in which case the return precision is double).
    If either or both of the arguments is complex, the return value y is complex.
    If either or both of the arguments are sequences of some size, the return value y is a sequence of that size.


  • y = sub(x, z)

    Not all combinations of arguments are currently supported - see Arithmetic functions.

    Subtracts z from x to produce y.
    The arguments x and z may be of any type. If both are sequences, they must be of the same size.
    The return value y is of same precision as the arguments, or, if the precisions of the arguments are different, is of single precision (unless neither argument is a sequence, in which case the return precision is double).
    If either or both of the arguments is complex, the return value y is complex.
    If either or both of the arguments are sequences of some size, the return value y is a sequence of that size.


  • y = mul(x, z)

    Not all combinations of arguments are currently supported - see Arithmetic functions.

    Multiplies x by z to produce y.
    The arguments x and z may be of any type. If both are sequences, they must be of the same size.
    The return value y is of same precision as the arguments, or, if the precisions of the arguments are different, is of single precision (unless neither argument is a sequence, in which case the return precision is double).
    If either or both of the arguments is complex, the return value y is complex.
    If either or both of the arguments are sequences of some size, the return value y is a sequence of that size.


  • y = div(x, z)

    Not all combinations of types are currently supported - see Arithmetic functions.

    Divides x by z to produce y.
    The arguments x and z may be of any type. If both are sequences, they must be of the same size.
    The return value y is of same precision as the arguments, or, if the precisions of the arguments are different, is of single precision (unless neither argument is a sequence, in which case the return precision is double).
    If either or both of the arguments is complex, the return value y is complex.
    If either or both of the arguments are sequences of some size, the return value y is a sequence of that size.


  • y = real(x)

    Returns the real part of x.

    The argument x may be of any type.
    The return value y is always of real type and the same precision as x (unless x is a single-precision complex number, in which case the precision is double).
    If x is real, y is equal to x. If x is a sequence, y is a sequence of the same size.


  • y = imag(x)

    Returns the imaginary part of x.

    The argument x may be of any type.
    The return value y is always of real type and the same precision as x (unless x is a single-precision complex number, in which case the precision is double).
    If x is real, y is equal to zero (or a sequence of zeros). If x is a sequence, y is a sequence of the same size.


  • y = shift(x, offset, order, [, z])
  • y = shift(x, z)

    Shift the start-time of a TimeSeries by offset samples, using Lagrange interpolation when necessary.

    Input arguments:
    x - a Sequence or TimeSeries.
    offset - a real number representing the number of samples to shift the TimeSeries by. Need not be a whole number of samples but must be non-negative.
    order - a non-negative integer representing the order of the Lagrange polynomial used to interpolate when offset is not a whole number.
    z - a "state" object created in a previous call (corresponding to a C++ ShiftState object).

    Output arguments:
    z - a "state" object which can be used for split interpolations.
    y - the shifted data, which will be of the same type and precision as x.

    If x is a TimeSeries with start-time t[0] and step-size dt, the first form of shift() produces an output TimeSeries with start-time

    t'[0] = t[0] + offset*dt .

    If requested, it also returns a "state" object z which can be used to shift several independent TimeSeries as if they were one continuous TimeSeries. The details of the resulting TimeSeries depends on whether offset is a whole number:

    Case 1: offset is a whole number.

    In this case, the first form of shift() removes offset samples from the beginning x and returns the result in y, thus the size of y is size(x) - offset. Subsequent calls using the second form of shift() with a state object simply return x in y without change. The order argument is ignored in this case. This behaviour is provided so that users can write "generic" scripts which produce TimeSeries starting at a guaranteed time, without worrying about whether or not the offset is a whole number.

    Case 2: offset has a fractional part ie. offset = floor(offset) + alpha, alpha > 0

    In this case, for the first form of shift() the procedure is to remove the first floor(offset) samples as above, then to use a length (order+1) FIR filter to shift the data by the fractional sample alpha ie. by alpha*dt seconds in time.

    Because the implementation uses a causal linear filter, some additional samples are removed from the beginning of the output to compensate for the filter delay. Thus, the size of y in this case is size(x) - floor(offset) - floor((order + 1)/2).

    Subsequent calls using the second form of shift() with a state object return data obtained by applying the interpolating filter directly to x, thus y will be the same size as x. However, the time-stamps of y will be shifted by the filter delay in addition to alpha. The time-stamp t'[k] of y[k] is given by

    t'[k] = t[k] + (alpha - floor((order+1)/2))*dt

    where t[k] are the time-stamps of x[k] and dt is the (common) time-step size of x and y.

    In either case, the result obtained by shifting a TimeSeries x0 using the first form of shift(), then shifting another TimeSeries x1 starting exactly one sample after the end of x0 using the second form of shift() is the same as applying the first form of shift() to the concatenation of x0 and x1.

    Example

    In this example we break up a series into two halves and shift them both. The resulting series, if joined back together, would be identical to interpolating the original series.

    # Create a 100-sample sine wave TimeSeries
    xData = sine(100, 0.1);
    x = tseries(xData, 16384.0, 6000000);
    
    # Use a linear interpolator (order 1), giving a 99-sample TimeSeries
    y = shift(x, 0.1, 1);
    
    # Break x into two halves
    x0 = slice(x, 0, 50, 1);
    x1 = slice(x, 50, 50, 1);
    
    # Shift x0, creating a state z and giving a 49-sample TimeSeries
    y0 = shift(x, 0.1, 1, z);
    
    # Shift y0 using z, giving a 50-sample TimeSeries
    # The sequence y0[0] ... y0[48] y1[0] ... y1[49] will be identical to y
    y1 = shift(x, z);
    


  • y = interpolate(x, alpha, order, [, z])
  • y = interpolate(x, z)

    Uses a Lagrange filter to interpolate a Sequence or TimeSeries.

    Input arguments:
    x - a Sequence or TimeSeries.
    alpha - a real number, 0.0 < alpha < 1.0
    order - a non-negative integer.
    z - a "state" object created in a previous call (corresponding to a C++ InterpolateState object).

    Output arguments:
    z - a "state" object which can be used for split interpolations.
    y - the interpolated data, which will be of the same type and precision as x.

    The interpolate() action uses a length (order+1) FIR filter to interpolate the data in x by a fraction of a sample specified by alpha.

    The filter consists of the coefficients of a Lagrange polynomial of degree order. For each index k, the FIR filter calculates the interpolated value x((k + alpha)dt) using the samples x[k - floor(order/2)] to x[k + floor((order + 1)/2)] ie. the same number of samples either side of (k + alpha)dt, or one more sample to the left when there is an odd number of points.

    Because the implementation uses a causal linear filter, there is an adjustment made to the start-time of the output series y which depends on the filter order. The values of y are given by

    y[k] = x((k - floor((order + 1)/2) + alpha)dt)

    and the time-stamp t'[k] of y[k] is given by

    t'[k] = t[k] - (floor((order + 1)/2) - alpha)dt

    where t[k] are the time-stamps of x[k] and dt is the (common) time-step size of x and y.

    When invoked in the first form, the action creates a new interpolator object and (optionally) returns it in z. When first created, the interpolator assumes that values before x[0] are zero, so the output samples up to and including y[order-1] are not reliable.

    When invoked in the second form, a state created previously can be used to interpolate the input x, in which case the state assumes that values before x[0] are from the end of the last series that was interpolated with z. The state must have originally been created using the same data type as x. The state remembers enough information from the previous call so that two series can be interpolated in succession as if they were one continuous series.

    Example

    In this example we break up a series into two halves and interpolate them both. The resulting series, if joined back together, would be identical to interpolating the original series.

    # Create a 100-sample sine wave
    x = sine(100, 0.1);
    
    # Use a linear interpolator (order 1)
    y = interpolate(x, 0.1, 1);
    
    # Break x into two halves
    x0 = slice(x, 0, 50, 1);
    x1 = slice(x, 50, 50, 1);
    
    # Interpolate x0, creating a state z
    y0 = interpolate(x, 0.1, 1, z);
    
    # Interpolate y0 using z.
    # The sequence y0[0] ... y0[49] ... y1[0] ... y1[49] will be identical to y
    y1 = interpolate(x, z);
    


  • y = abs(x)

    Returns the absolute magnitude(s) of (the elements of) x.

    The argument x may be of any type.
    The return value y is always of real type and the same precision as x (unless x is a single-precision complex number, in which case the precision is double).
    If x is a sequence, y is a sequence of the same size.


  • y = arg(x)

    Returns the argument(s) (phase angle(s)) of (the elements of) x.

    The argument x may be of any type.
    The return value y is always of real type and the same precision as x.
    If x is a sequence, y is a sequence of the same size.


  • z = complex(x [, y])

    Returns the complex scalar or sequence x + i*y.

    Input parameters:

  • x - an object derived from Scalar<double>, Sequence<float> or Sequence<double>.
  • y - an object derived from Scalar<double>, Sequence<float> or Sequence<double>. If x and y are both Sequences then they must have the same size and precision. If the second parameter is omitted, the default is 0.0.

    Result:

  • If x and y are both Scalar<double> then the result will be a Scalar<complex<double> > with x as real part and y as imaginary part.
  • If x is derived from Sequence and y is derived from a Scalar<double> then the result will be an object of the same class and precision as x and having identical meta-data, but with a complex template parameter. The real part of the result will be taken from x while the imaginary part will be taken from y. For example, if x is a TimeSeries<float> and y is a Scalar<double> then z will be a TimeSeries<complex<float> > with x as real part and y as imaginary part, having the same time-series meta-data as x.
  • Similarly, if x is derived from Scalar<double> and y is derived from a Sequence then the result will be an object of the same class and precision as y and having identical meta-data, but with a complex template parameter. The real part of the result will be taken from x while the imaginary part will be taken from y.
  • If both x and y are derived from Sequence then the result will be an object of the same class and precision as x and having identical meta-data, but with a complex template parameter. The real part of the result will be taken from x while the imaginary part will be taken from y. Any meta-data or additional structure present in y will be ignored.
    The sequences x and y must have the same precision (float or double) and the same size.


  • z = coherence(x, y, [ fft_length ], [ window ], [ overlap_length ], [ detrend ])

    Returns an estimate of the coherence of two time-series x and y.

    The input sequences x and y must be the same length but may be real or complex, and of single or double precision.
    The optional input parameters have the same meaning as for the
    psd() and csd() actions.
    The optional input parameter fft_length must be a positive integer (default is 1024).
    The optional input parameter window indicates which type of windowing is to be used (default is to use a Hanning window).
    The optional input parameter overlap_length must be a non-negative integer (default is 0).
    The optional input parameter detrend indicates which type of detrending is to be used. A value of 0 indicates no detrending, a value of 1 indicates that the mean will be removed from the data, and a value of 2 indicates that linear trends will be removed (default is 0).
    The return value z is a complex sequence of length fft_length with the same precision as the highest precision of x or y.
    Any optional parameter may be replaced with an underscore character _ to indicate that the default value should be used.
    Any trailing optional parameter may be omitted.

    Coherence is computed as

    csd(x, y [, options ]) / sqrt(psd(x [, options]) * psd(y [, options]))

    Note that the MATLAB definition of coherence is the (absolute) square of the LDAS definition.


  • x = concat(x0, x1, [ x2, ... ])

    Returns the concatenation of x0, x1, x2 ...

    This action takes any number of TimeSeries or Sequences and concatenates them into a single TimeSeries or Sequence. The type and meta-data of the result x is determined by the first argument.

    If x0 is a Sequence, x will also be a Sequence. Subsequent arguments may be either TimeSeries or Sequences but any TimeSeries meta-data will be ignored.

    If x0 is a TimeSeries, x will also be a TimeSeries whose start-time and sampling rate are the same as x0. Subsequent arguments may be either TimeSeries or Sequences but any TimeSeries meta-data will be ignored.

    In either case, the size of x is the sum of the sizes of the arguments.

    The elememts contained in each of the arguments must be the same type ie. float, double, complex float or complex double.

    Example

    Create a TimeSeries of size 3*16384 samples with sample rate 16384 Hz starting at 610000000 (roughly May 5, 1999) consisting of a sequence of zeroes, then a sinewave, then another sequence of zeroes. Note that to produce a TimeSeries, the first argument must be a TimeSeries. The remaining arguments may be either Sequences or TimeSeries.

    x0 = ramp(16384, 0.0, 0.0);
    x0 = tseries(x0, 16384.0, 610000000);
    
    x1 = sine(16384, 0.1);
    x2 = ramp(16384, 0.0, 0.0);
    
    x = concat(x0, x1, x2);
    

  • y = conj(x)

    Returns the conjugate(s) of (the elements of) x.

    The argument x may be of any type.
    The return value y is always of the same precision as x.
    If x is a sequence, y is a sequence of the same size.


  • y = double(x)

    Returns a double-precision representation of x.

    This function attempts to produce a double-precision version of its argument while preserving the container type and associate meta-data. For example, a TimeSeries<float> will be converted to a TimeSeries<double> with the same values, start-time, sampling rate and so on.
    The argument x may be of any type except those derived from State.
    The return value y is a double-precision version of x.


  • y = float(x)

    Returns a single-precision representation of x.

    This function attempts to produce a single-precision version of its argument while preserving the container type and associate meta-data. For example, a TimeSeries<double> will be converted to a TimeSeries<float> with the same values, start-time, sampling rate and so on.
    The argument x may be of any type except those derived from State.
    The return value y is a single-precision version of x.


  • clear(x)

    Destroys the symbol x and frees any memory used by it.

    The argument x may be of any type.
    Any memory associated with x is freed.


  • y = cos(x)

    Returns the cosine(s) of (the elements of) x.

    The argument x may be of any type.
    The return value y is always of the same type as x.
    If x is a sequence, y is a sequence of the same size.


  • y = cosh(x)

    Returns the hyperbolic cosine(s) of (the elements of) x.

    The argument x may be of any type.
    The return value y is always of the same precision as x.
    If x is a sequence, y is a sequence of the same size.


  • y = exp(x)

    Returns the exponential(s) of (the elements of) x.

    The argument x may be of any type.
    The return value y is always of the same type as x.
    If x is a sequence, y is a sequence of the same size.


  • y = log(x)

    Returns the natural logarithm(s) of (the elements of) x.

    The argument x may be of any type.
    The return value y is always of the same type as x.
    If x is a sequence, y is a sequence of the same size.


  • y = sin(x)

    Returns the sine(s) of (the elements of) x.

    The argument x may be of any type.
    The return value y is always of the same type as x.
    If x is a sequence, y is a sequence of the same size.


  • y = sinh(x)

    Returns the hyperbolic sine(s) of (the elements of) x.

    The argument x may be of any type.
    The return value y is always of the same type as x.
    If x is a sequence, y is a sequence of the same size.


  • y = sqrt(x)

    Returns the square root(s) of (the elements of) x. Branch cut is the negative real axis.

    The argument x may be of any type.
    The return value y is always of the same type as x.
    If x is a sequence, y is a sequence of the same size.


  • y = sum(x)

    Returns the sum of the elements of x.

    The argument x must be an object derived from a Sequence. An error will occur if the size of x is zero.
    The return value y is either a Scalar<double> or a Scalar<complex<double> >, depending on whether x is real or complex.


  • y = cpu_time()

    Returns the number of seconds spent in kernel space since the last call.


  • y = user_time()

    Returns the number of seconds spent in user space since the last call.


  • y = wall_time()

    Returns the number of seconds elapsed since the last call.


  • y = time()

    Returns the cpu_time, user_time, and wall_time in a single Sequence<double>, indexed from 0.

    0cpu time
    1user time
    2wall time


  • y = fseries(x, f0, df, start_s, start_ns, stop_s, stop_ns)

    Returns a frequency-series constructed from the values in the Sequence x, with starting frequency f0 and frequency step-size df.

    The time-range for which the frequency series is valid starts at start_s seconds and start_ns nanoseconds and ends at stop_s seconds and stop_ns nanoseconds. Times are measured from the start of the GPS epoch.

    The sequence x may have elements which are float, double, complex float or complex double. The returned frequency-series has the same type and precision.
    The parameters f0 and df must be Scalars.
    The parameters start_s, start_ns, stop_s and stop_nsmust be Scalar<int>s.


  • y = tseries(x, srate, [ start_s, ] [ start_ns, ] [ base_freq, ] [ phase ])

    Returns a TimeSeries constructed from the values in the sequence x, with sampling rate srate, start-time start_s seconds and start_ns nanoseconds, base frequency base_freq and initial phase phase.

    The sequence x may have elements which are float, double, complex float or complex double sequence. The returned TimeSeries has the same type and precision.
    The parameters srate, base_freq and phase must be Scalars.
    The parameters start_s and start_ns must be Scalar<int>s.

    Example
    Construct a time-series with sampling rate 2048 Hz, starting at 6100000s

    
    ts = tseries(x, 2048.0, 6100000);
    
    


  • output(variable, format, protocol, name, comment)

    This action stores the current value of variable according to the format and protocol arguments.

    The variable argument specifies the name of a variable previously created by another action.

    The format argument specifies the final output representaion.
    Supported Values for Format
    ValueDescription
    frame frame:gzip:[1-6] frame:raw Binary frame files. Optionally include the compression method and comprssion level. Default is 'gzip:1' when 'frame' is specified.
    Note that specifying the compression parameter for scalar values will have no effect on the output, so it is a good rule to specify the compression parameters for all outputs when one has an interest in modifying the compression format.
    ilwd ascii This is an ascii text file using LDAS' internal data representation. It can be viewed with any text editor or viewer. The tags are similar html start/end tag pairs. Their meaning is only defined within the context of LDAS.
    ilwd binary This is an mixed mode file which has ascii tags, but the data is stored in binary mode. This form cannot be viewed with text editors or viewer, but is useful for sample data sets as they can be read by the LDAS system much quicker than their ascii counter parts.
    LIGO_LW This is an XML representation of the output.

    The protocol argument is either a URL or is set to the name of an LDAS API for the directing of data products to other API's (wrapper, frame, metadata) via data sockets. The name of the target API is entered in the protocol field and the data is forwarded after attaching the jobid. When the protocol is specified to be the name of an API, the format option is always forced to the value ilwd.

    Supported Values for Protocol
    ValueDescription
    http://dirname
    ftp://dirname
    With this form, dirname corresponds to an existing directory in the anonymous ftp area of the LDAS system. All output files will be copied into the directory. In some cases a filename can be specified and will be used; in this case .ba* files may be created to avoid overwriting of data.
    NOTES: 1
    ftp://hostname/dirname/filename With this form, the LDAS system will attempt to copy the output data via anonymous ftp to hostname into the dirname as filename.
    NOTES: 1, 2
    wrapper Output is formatted as an ilwd appropriate for the wrapperAPI.
    NOTES: 3
    frame Output is formatted as an ilwd appropriate for the frameAPI.
    NOTES: 3
    metadata Output is formmatted as an ilwd appropriate for the metadataAPI.
    NOTES: 3

    NOTES:

    1. The data in the file will be ilwd formatted according to the -datacondtarget option.
    2. The user will need to run tests to make certain that this form works with the specified site.
    3. This protocol forces ilwd format.

    Data Products Appropriate for API
    Data Productwrapperframemetadata
    FrequencySequence<>yesyesno
    Sequence<>yesyesno
    Statsnonoyes
    TimeSeries<>yesyesno
    WelchCSDSpectrum<>yesyesyes
    WelchSpectrum<>yesyesyes

    The name argument will be used as the name attribute of the ilwd element produced by the processing of the output action. The name argument is a freeform string. The name argument can be used to override the default name given to an ILWD element before being sent to the next API. For example, when writing data to frame format, the name argument can be used to set the corresponding channel name to a user-defined value.
    When the name is formatted such that it ends in :primary, as in foo:bar:primary, the element will be treated as the "primary" element in the output object when the protocol is wrapper.
    If any output is to be sent to the wrapperAPI and no explicate primary was specified, the system will assign the first output that specifies a start time, duration, and is formatted for wrapper output as the primary. If no primary can be found for a job sending data to the wrapperAPI, an exception is thrown and the job is aborted.

    The comment argument is a freeform string which will be used for the comment attribute of the ilwd element produced by the processing of the output action. The string will be substituted twice: once when the alias list is substituted, and again by the ilwd engine, which may render some characters as escape codes. If this option is missing or is incomplete, a default value will be used which makes no attempt to be descriptive of the result value.
    The comment argument will have all spaces in the string replaced with underscores. This will change! At some point the comment string will be able to pass unmodified.
    The format and protocol arguments can be set to '_', as in output(x,_,_,x,value of x), which will cause the default behaviour of writing the ouput into the result ilwd as an additional element.


  • y = sine(n, f[, phi[, A[, x0]]])

    Generate a discrete sinewave with length n, frequency f, phase phi, amplitude A and offset x0.

         y[k] = A * sin(2 * pi * f * k + phi) + x0   k = 0, 1, ..., n-1

    n must be a positive integer.
    f must be between -0.5 and 0.5 (inclusive). If the result is used to construct a TimeSeries, the sinewave would have frequency f*srate Hz.
    phi is given in radians and must be between -pi and pi (inclusive). The default value of phi is zero.
    A is a scalar multiplier and may take any value. The default value of A is unity.
    x0 is an additive scalar and may take any value. The default value of x0 is zero.
    The return type of y is always a real double sequence.

    Examples

    y1 = sine(10, 0.5, 1.57, 0.5, 0.5);
    y2 = sine(300, -0.02);
    


  • y = cosine(n, f[, phi[, A[, x0]]])

    Generate a discrete sinewave with length n, frequency f, phase phi + pi/2, amplitude A and offset x0.

         y[k] = A * cos(2 * pi * f * k + phi) + x0   k = 0, 1, ..., n-1

    n must be a positive integer.
    f must be between -0.5 and 0.5 (inclusive). If the result is used to construct a TimeSeries, the sinewave would have frequency f*srate Hz.
    phi is given in radians and must be between -pi and pi (inclusive). The default value of phi is zero.
    A is a scalar multiplier and may take any value. The default value of A is unity.
    x0 is an additive scalar and may take any value. The default value of x0 is zero.
    The return type of y is always a real double sequence.

    Examples

    y1 = cosine(10, 0.5, 1.57, 0.5, 0.5);
    y2 = cosine(300, -0.02);
    


  • y = sawtooth(n, f[, phi[, A[, x0]]])

    Generate a discrete sawtooth wave with length n, frequency f, phase phi, amplitude A and offset x0.

         y[k] = A * (2 * pi * f * k + phi (mod 2 * pi)) / (2 * pi) + x0

    n must be a positive integer.
    f must be between -0.5 and 0.5 (inclusive). If the result is used to construct a TimeSeries, the sawtooth wave would have frequency f*srate Hz.
    phi is given in radians and must be between -pi and pi (inclusive). The default value of phi is zero.
    A is a scalar multiplier and may take any value. The default value of A is unity.
    x0 is an additive scalar and may take any value. The default value of x0 is zero.
    The return type of y is always a real double sequence.

    Examples

    y1 = sawtooth(10, 0.5, 1.57, 0.5, 0.5);
    y2 = sawtooth(300, -0.02);
    


  • y = square(n, f[, phi[, A[, x0]]])

    Generate a discrete square wave with length n, frequency f, phase phi, amplitude A and offset x0.

         y[k] = x0 + A,  0 <= 2 * pi * f * k + phi (mod 2 * pi) <    pi
              y[k] = x0 - A, pi <= 2 * pi * f * k + phi (mod 2 * pi) < 2* pi  k = 0, 1, ..., n-1

    n must be a positive integer.
    f must be between -0.5 and 0.5 (inclusive). If the result is used to construct a TimeSeries, the square wave would have frequency f*srate Hz.
    phi is given in radians and must be between -pi and pi (inclusive). The default value of phi is zero.
    A is a scalar multiplier and may take any value. The default value of A is unity.
    x0 is an additive scalar and may take any value. The default value of x0 is zero.
    The return type of y is always a real double sequence.

    Examples

    y1 = square(10, 0.5, 1.57, 0.5, 0.5);
    y2 = square(300, -0.02);
    


  • y = triangle(n, f[, phi[, A[, x0]]])

    Generate a discrete triangle wave with length n, frequency f, phase phi, amplitude A and offset x0.

         y[k] = A * (2 * phi/pi - 1) + x0,  0 <= 2 * pi * f * k + phi (mod 2 * pi) <    pi
              y[k] = A * (3 - 2*phi/pi) + x0, pi <= 2 * pi * f * k + phi (mod 2 * pi) < 2* pi  k = 0, 1, ..., n-1

    n must be a positive integer.
    f must be between -0.5 and 0.5 (inclusive). If the result is used to construct a TimeSeries, the triangle wave would have frequency f*srate Hz.
    phi is given in radians and must be between -pi and pi (inclusive). The default value of phi is zero.
    A is a scalar multiplier and may take any value. The default value of A is unity.
    x0 is an additive scalar and may take any value. The default value of x0 is zero.
    The return type of y is always a real double sequence.

    Examples

    y1 = triangle(10, 0.5, 1.57, 0.5, 0.5);
    y2 = triangle(300, -0.02);
    


  • y = ran0(n [, s])
  • y = ran1(n [, s])
  • y = ran2(n [, s])
  • y = ran3(n [, s])
  • y = ran4(n [, s])
  • y = gasdev(n [, s])

    Generates sequences of random numbers of length n.
    ran0() through ran4() generate numbers which are equidistributed between 0 and 1 (through different means).
    gasdev() generates normally distributed numbers (i.e. zero mean and unit variance).
    Note that gasdev() uses ran2() to generate its numbers.
    n must be a positive integer.
    s is the optional seed argument - it has a default value of -248673140. For best results when specifying the seed use a number between -299999999 and -100000000.
    The return type of y is always a real single-precision sequence.


  • y = getElement(x, k)

    Returns x[k] as a scalar.

    Input arguments:
    x - an object derived from Sequence.
    k - a Scalar<int>.

    Output arguments:
    y - a Scalar<double> if x is a Sequence<float> or Sequence<double>, or a Scalar<complex<double> > if x is a Sequence<complex<float> > or Sequence<complex<double> >.


  • setElement(y, k, x)

    Sets y[k] equal to x.

    Input arguments:
    y - an object derived from Sequence.
    k - a Scalar<int>.
    x - a Scalar, which will automatically be cast to the element type of y, except that attempting to set an element of a float or double Sequence using a complex Scalar will generate an error.


  • srate = getSampleRate(x)

    Returns the sampling rate of a TimeSeries object.

    Input arguments:
    x - an object derived from TimeSeries.

    Output arguments:
    srate - the sampling rate in Hertz of x as a Scalar<double>.


  • stepSize = getStepSize(x)

    Returns the step-size (in appropriate units) of a TimeSeries or FrequenceySequence object.

    Input arguments:
    x - an object derived from TimeSeries or FrequencySequence.

    Output arguments:
    stepSize - the step-size of x as a Scalar<double>. If x is derived from a TimeSeries the step-size is in seconds, while if x is derived from a FrequencySequence it is in Hertz.


  • b = arls(x, n)
  • b = arls(x, n, z)
  • b = arls(x, z)

    Returns the FIR coefficents b of a linear filter fitted to predict x[i] from x[i-1] ... x[i-n] with least squares error. These coeffients describe an Auto-Regression (AR) system model, a method of linearly predicting the determinsitic components of a noisy system output.
    x must be a sequence (the system output the AR model is fitted to).
    n must be a positive integer (the order of the ARModel, small values 2-4 work well).
    z the action state, written to if n is supplied, used to refine existing b otherwise.


  • z = oelslr(y, u, f, d, n)
  • z2 = oelslr(y, u, z)
  • w = oelslr(u, z)

    Output Error model Least Squares fitted for Line Removal. Returns a prediction w of the system output y from an Output Eror (OE) model on the system input u, tailored to only predict narrow frequency bands (containing spectral lines). The central frequency of the lowest harmonic f, and a bandwidth frequency delta enclosing the spectral line must be supplied (in Hertz), as well as an integer number of harmonics to be removed n > 0. If a state z is included it will be written to and may be used in place of these parameters in subsequent calls. Continuous line removal over segemented data sets is supported thus. There are known problems in the OE model predictor that limit the effectiveness of the current implementation.
    y must be a time series (the system output the OE model is fitted to).
    u must be a time series (the system input the OE model predicts from).
    f must be a scalar frequency in Nyquist frequencies (the centre of the line).
    d must be a positive integer (the fraction of the freuqncy range to apply to).
    n must be a positive integer (the order of the line remover).
    z the action state.


  • w = Haar([ type ])
  • The action creates a wavelet object w of type Haar. It specifies the Haar discrete wavelet transform. The object w is used as an input parameter of the action function WaveletForward.

    Input arguments:

    type is the type of wavelet decomposition tree:


  • w = Biorthogonal([n [, type [, border ] ] ])
  • The action creates a wavelet object w of type Biorthogonal. It specifies a Biorthogonal discrete wavelet transform. The object w is used as an input parameter of the action function WaveletForward.

    Input arguments:

    type is the type of wavelet decomposition tree:


    n is the length of wavelet filters. n must be even integer number from 4 to 30 (4 is default), otherwise the value 2*int(n/2) is taken.

    border is the type of data border processing method, which can be: B_CYCLE, B_PAD_ZERO, B_PAD_EDGE, B_POLYNOM. By default the polynomial interpolation of data on the edges (B_POLYNOM) is used.
     


  • w = Daubechies([n [, type [, border ] ] ])
  • The action creates a wavelet object w of type Daubechies. It specifies a Daubechies discrete wavelet transform. The object w is used as an input parameter of the action function WaveletForward.

    Input arguments:

    type is the type of wavelet decomposition tree:


    n is the length of wavelet filters. n must be even integer number from 4 to 60 (8 is default), for odd n the value 2*int(n/2) is taken. If n is out of the range 4..60 then default value8 will be taken.

    border is the type of data border processing method. Currently only the B_CYCLE method (connect the beginning and the end of data sample to make a ring)is available for the Daubechies wavelets and this argument is ignored.
     


  • w = Symlet([n [, type [, border ] ] ])
  • The action creates a wavelet object w of type Symlet. It specifies a Symlet discrete wavelet transform. The object w is used as an input parameter of the action function WaveletForward.

    Input arguments:

    type is the type of wavelet decomposition tree:


    n is the length of wavelet filters. n must be even integer number from 4 to 60 (8 is default), for odd n the value 2*int(n/2) is taken. If n is out of the range 4..60 then default value8 will be taken.

    border is the type of data border processing method. Currently only the B_CYCLE method (connect the beginning and the end of data sample to make a ring)is available for the Daubechies wavelets and this argument is ignored.



  • u = WaveletForward( ts, w, n )
  • Returns result of wavelet decomposition of a time series.

    Input arguments:

    ts is the input time series.

    w is the decomposition method.

    n is the number of decomposition steps. Tt must be a positive integer or -1, which means a complete decomposition.

    Example

    w = Biorthogonal( 8, 0 );
    u = WaveletForward( ts, w, -1 );
     


  • ts = WaveletInverse(u)
  • Returns a time series, which is a result of wavelet reconstruction.

    Example

    w = Daubechies( 20, 1 );
    u = WaveletForward( ts, w, -1 );
    ts2 = WaveletInverse( u );

    Time-series ts2 is equivalent to the time series ts.
     


  • s = GetLayer( u, n )
  • Returns a sequence, which contains wavelet coefficients taken from layer n. Layer 0 is the approximation wavelet layer (lowest frequency). Layers 1..n are the details wavelet layers, sorted in the order of increasing frequency.

    Example

    w = Symlet( 10, 0 );
    u = WaveletForward( ts, w, -1 );
    s = GetLayer( u, 1 );


  • y = signum(x [, t1 [, t2 ] ])
  • The input x is a Sequence of float or double or derived from Sequence. The type of output is the same as input. Metadata preserved. Optional thresholds t1 and t2 are double scalars. The action returns sequence of +1, -1 and 0 depending on input elements relation to the values of thresholds, according to rules:

    Example
    Set to zero elements which values are between thresholds

    y = signum( x, t1, t2 );
    mask = abs( y );
    z = mul( y, mask );