triana.types

Class ComplexSpectrum

java.lang.Object

triana.types.TrianaType

triana.types.GraphType

triana.types.VectorType

triana.types.ComplexSpectrum

All Implemented Interfaces:

java.io.Serializable, Arithmetic, AsciiComm, SequenceInterface, Spectral

public class ComplexSpectrum
extends VectorType
implements Spectral, AsciiComm

ComplexSpectrum stores a one-dimensional array of double-precision complex numbers representing a complex Fourier spectrum. It includes a Triplet giving the integer values of the index of this array, and five new parameters: a double resolution giving the frequency resolution; a double highestFrequency giving the value of the largest frequency represented in the data set; an int nFull giving the number of points in the original data set from which the data here were derived (used if the data have been reduced to one-sided or narrow-band spectra); and two boolean flags, (i) a flag twoSided that says whether the ComplexSpectrum is one-sided or two-sided, and (ii) a flag narrow that says whether the data are a narrow bandwidth derived from a larger full-bandwidth spectrum. ComplexSpectrum is the basic Triana class for holding one-dimensional Fourier tranforms. It is derived from the VectorType class and implements the Spectral interface.

ComplexSpectrum implements the Triana model for storing spectral data. The model is general enough to contain a multi-dimensional Fourier transform derived from a complex data set containing an arbitrary number of points. It is complete enough to ensure that inverse Fourier transforms can be done correctly automatically, even if the data set is a narrow-band spectrum extracted from a full spectrum that obeys the Triana model. For two-sided spectra, the Triana storage model the same as that required by the Triana FFT unit and is one of the standard FFT storage models. For one-sided data it is not quite the same as the close packing that is used by most Fast Fourier Transform (FFT) methods, so the Triana FFT unit converts from the Triana storage model to its own internal format. The Triana model is described fully here. First we deal with two-sided complete spectra, then one-sided. At the end we describe the way narrow bands are handled. The various descriptions assume a one-dimensional data set (one independent variable), but they apply to each dimension of multi-dimensional sets.

All spectral representations assume that the frequency values are uniformly spaced and are represented by an integer index k. The value of resolution is the (positive) difference between the frequencies associated with consecutive values of k. The index k is non-negative.

A two-sided ComplexSpectrum contains spectral values at both negative and positive frequencies. Values at non-negative frequencies are stored in the first part of the data vector in order of increasing frequency, and values at negative frequencies are stored in the second part, again in order of increasing frequency. The details depend on whether the total length of the spectral data set, N, is even or odd.

Two-sided, full-bandwidth spectra of even length N (nFull = N even, narrow = false, twoSided = true):
The frequency corresponding to the index k contained in the interval [0, N/2-1] is k * resolution; the frequency corresponding to index k in [N/2, N-1] is (k - N) * resolution. Thus, the highest absolute value of the frequency is associated with k = N/2. This frequency is -(N/2) * resolution, and it is called the Nyquist frequency. It should be equal to -highestFrequency. This is a consistency check. For even N, the spectral amplitude at this largest negative frequency is the same as that which could be associated with the largest positive frequency, +(N/2) * resolution. If this spectrum was or could have been derived as a Fourier transform of a real data set, then the data values associated with k = 0 and k = N/2 are real, and the data values at indices k and N-k are complex-conjugates of one another. Such a spectrum can be converted to a one-sided representation without the loss of information.

Two-sided, full-bandwidth spectra of odd length N (nFull = N odd, narrow = false, twoSided = true):
The frequency corresponding to the index k contained in the interval [0, (N-1)/2] is k * resolution; the frequency corresponding to index k in [(N+1)/2, N-1] is (k - N) * resolution. Thus, the highest positive frequency is associated with k = (N-1)/2; the lowest negative frequency with k = (N+1)/2; both these frequencies have absolute value (N-1)/2 * resolution; and this is called the Nyquist frequency. This should equal highestFrequency (this is a consistency check). The spectral amplitudes at the lowest and highest-frequency points are generally different when N is odd. If this spectrum was or could have been derived as a Fourier transform of a real data set, then the data value associated with k = 0 is real, and the data values at indices k and N-k are complex-conjugates of one another. Such a spectrum can be converted to a one-sided representation without the loss of information.

A one-sided ComplexSpectrum includes only non-negative frequencies. The data model contains enough information to perform an inverse Fourier transform on the spectrum on the assumption that the resulting data set will contain only real values. Thus, values at the negative frequencies that are not represented in the data set will be assumed to be the complex conjugates of the values at the corresponding positive frequencies. Details depend on whether the total number of data points in the corresponding two-sided spectrum was even or odd. For transforms of real data, one-sided representations are preferable because they require only about half the memory of two-sided representations, and they nevertheless contain the same information.

One-sided, full-bandwidth spectra of length N derived from a two-sided spectrum with an even number of elements (nFull even, narrow = false, twoSided = false):
In a one-sided spectrum containing N data points, the frequency corresponding to element k contained in [0, N-1] is k * resolution. The highest such frequency is (N-1) * resolution, and this should be equal to highestFrequency. This is a consistency check. Since the orginal time-series is assumed to be real, the element at k = 0 should be real. For this case, where nFull is even, the original spectrum (or time-series) must have contained 2*N-2 points. This should be the value of nFull, and this is a further consistency check. The highest-frequency element of the current data set (index N-1) contains the value of the original spectrum at its highest frequency (index N-1 in that set), and this should be real as well. Thus a two-sided full-bandwidth spectrum derived from real data of length nFull = 2*N-2 can be converted to a one-sided spectrum just by extracting the first N elements. Since the first and last of these elements are real, this extracted set contains 2*N-2 independent numbers. This storage model differs from those used by some FFT methods, typically because in those methods the two real elements are combined into a single complex storage location, saving one complex storage element. The storage saving is small and it would make manipulating spectra in Triana (such as adding or graphing them) clumsy, so it is not implemented. FFT units in Triana must perform any requisite conversions to their internal storage model themselves.

One-sided, full-bandwidth spectra of length N derived from a two-sided spectrum with an odd number of elements (nFull odd, narrow = false, twoSided = false):
In a one-sided spectrum containing N data points, the frequency corresponding to element k contained in [0, N-1] is k * resolution. The highest such frequency is (N-1) * resolution, and this should be equal to highestFrequency. This is a consistency check. Since the orginal time-series is assumed to be real, the element at k = 0 should be real. For this case, where nFull is odd, the original spectrum (or time-series) must have contained 2*N - 1 points. This should be the value of nFull, and this is a further consistency check. The highest-frequency element of the current data set (index N-1) contains the value of the original spectrum at its highest frequency (index N-1 in that set), and this will in general be complex. Thus a two-sided full-bandwidth spectrum derived from real data of length nFull = 2*N-1 can be converted to a one-sided spectrum just by extracting the first N elements. Since the first of these elements is real, this extracted set contains 2*N-1 independent numbers. The remarks in the previous paragraph about the data storage model for FFT methods apply here as well.

The Triana spectral data model allows for the bandwidth of the data to be narrower than that of the set from which it was derived, and the parameter highestFrequency is included in this class mainly to indicate the value of the upper edge of the frequency band. The lower edge can be deduced from the other data, such as the number of points and resolution. The Triana data storage model for narrow-band spectra places certain restrictions on the way such spectra can be constructed, so as to preserve as much as possible of the information needed to invert the spectrum back to a time-series. The information enables one to convert the data back to a full-bandwidth spectrum by padding with zeros.

Two-sided, narrow-band spectra of length N derived from a two-sided spectrum with an even number of elements (nFull even, narrow = true, twoSided = true):
Two-sided narrow-band data must always contain data points for related positive and negative frequencies. Removing the upper part of the spectrum requires removing the single highest-frequency value and then pairs of values for the contiguous frequencies (each pair being a frequency and its negative), i.e. removing in total an odd number of data points. Removing the lower part of the spectrum similarly requires removing an odd number of data points. Since the original data set had an even number of elements, we can determine the nature of the bandwidth of the narrow-band spectrum as follows. If N (actual number of elements) is even, then the band has been shrunk from both sides; the lower frequency limit is highestFrequency - (N/2 - 1) * resolution and should not be zero. The whole original frequency range can be reconstructed from these numbers and nFull. If N is odd, then either the highest original frequency or the lowest is still present in the band; if the highest is still present then highestFrequency = nFull/2 * resolution; if the lowest is still present then the lower frequency limit in this case, highestFrequency - ( (N-1)/2 ) * resolution, must be zero. A consistency test is that one of these conditions must hold if N is odd.

Two-sided, narrow-band spectra of length N derived from a two-sided spectrum with an odd number of elements (nFull odd, narrow = true, twoSided = true):
Two-sided narrow-band data must always contain data points for related positive and negative frequencies. Removing the lower part of the spectrum requires removing the single zero-frequency value and then pairs of values for the contiguous frequencies (each pair being a frequency and its negative), i.e. removing in total an odd number of data points. This will make N (the actual number of elements) even. Removing the upper part of the spectrum or a portion in the middle requires removing an even number of data points in frequency pairs. This will make N odd. Therefore, if N is even, the lower part of the spectrum has been removed, and the upper part may or may not have been removed. In this case, if highestFrequency = (nFull-1)/2 * resolution, then the upper part of the original band is still present. If N is odd, then the lower part of the spectrum is still present and the upper has been removed.

One-sided narrow-band spectra of length N derived from a two-sided spectrum with an even number of elements (nFull even, narrow = true, twoSided = false):
A one-sided spectrum is assumed derived from a two-sided spectrum that came from a Fourier transform of a real data set. This is then made narrow-band by removing frequencies at the lower and/or upper ends of the full band. If highestFrequency = nFull/2 * resolution, then the top of the band is still present, and (for consistency) the highest-frequency data value should be real. The lower frequency limit is highestFrequency - (N-1) * resolution, and this should be larger than zero. If the top of the band is missing, then one can calculate the lower frequency limit as above; if this is zero then the bottom of the band is still present, and the lowest-frequency data value should be real (consistency again). If the lower frequency limit is positive, then the bottom of the band is missing. These data are sufficient to reconstruct the two-sided narrow-band spectrum associated with this data set on the assumption that the inverse transform produces a real data set.

One-sided narrow-band spectra of length N derived from a two-sided spectrum with an odd number of elements (nFull odd, narrow = true, twoSided = false):
A one-sided spectrum is assumed derived from a two-sided spectrum that came from a Fourier transform of a real data set. This is then made narrow-band by removing frequencies at the lower and/or upper ends of the full band. If highestFrequency = (nFull-1)/2 * resolution, then the top of the band is still present, and (for consistency) the highest-frequency data value should be real. The lower frequency limit is highestFrequency - (N-1) * resolution, and this should be larger than zero. If the top of the band is missing, then one can calculate the lower frequency limit as above; if this is zero then the bottom of the band is still present, and the lowest-frequency data value should be real (consistency again). If the lower frequency limit is positive, then the bottom of the band is missing. These data are sufficient to reconstruct the two-sided narrow-band spectrum associated with this data set on the assumption that the inverse transform produces a real data set.

ComplexSpectrum contains a number of methods for accessing and modifying these parameters.

See Also:

Spectral, SampleSet, Spectrum, GraphType, Triplet, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
double	frequencyResolution (Parameter that is kept for consistency with previous versions, but which is obsolete.
double[]	imag (Parameter that is kept for consistency with previous versions, but which is obsolete.
double[]	real (Parameter that is kept for consistency with previous versions, but which is obsolete.
double	samplingFrequency (Parameter that is kept for consistency with previous versions, but which is obsolete.

Fields inherited from class triana.types.VectorType

x, xlabel, y, ylabel

Fields inherited from class triana.types.TrianaType

NOT_CONNECTED, NOT_READY, OUT_OF_RANGE

Constructor Summary

Constructors

Constructor and Description
ComplexSpectrum() Create and empty ComplexSpectrum with no parameters set.
ComplexSpectrum(boolean ts, boolean nrw, double[] real, double[] imag, int nOrig, double df, double hf) Creates a new ComplexSpectrum with arguments giving the sidedness, whether it is narrow-band or broad-band, the data arrays, the number of points in the original broad-band spectrum, the frequency resolution, and the highest frequency in the current spectrum.
ComplexSpectrum(boolean ts, boolean nrw, int len, int nOrig, double df, double hf) Creates a new ComplexSpectrum with arguments giving the sidedness, whether it is narrow-band or broad-band, the data length, the number of points in the original broad-band spectrum, the frequency resolution, and the highest frequency in the current spectrum.
ComplexSpectrum(boolean ts, double[] real, double[] imag, int nOrig, double df) Creates a new ComplexSpectrum with given sidedness, data arrays, number of points in the two-sided spectrum, and frequency resolution.
ComplexSpectrum(boolean ts, int nOrig, double df) Creates a new ComplexSpectrum with a given sidedness, number of points that there would be in the two-sided spectrum, and frequency resolution.
ComplexSpectrum(double samplingFrequency, double[] real) This is an obsolete Constructor that creates a new one-sided ComplexSpectrum with a certain sampling frequency and the actual allocated real data.
ComplexSpectrum(double samplingFrequency, double[] real, double[] imag) This is an obsolete Constructor that creates a new one-sided ComplexSpectrum with a certain sampling frequency and the actual allocated complex data.
ComplexSpectrum(double sf, int points) This is an obsolete Constructor that will be eliminated when possible.
ComplexSpectrum(Spectrum s) Creates a ComplexSpectrum from a (real) Spectrum by setting the imaginary part of the data to zero.
ComplexSpectrum(Spectrum s, boolean copy) Creates a ComplexSpectrum from a (real) Spectrum by setting the imaginary part of the data to zero.

Method Summary

Methods

Modifier and Type	Method and Description
TrianaType	copyMe() This is one of the most important methods of Triana data.
protected void	copyParameters(TrianaType source) Copies modifiable parameters from the argument object to the current object.
boolean	equals(TrianaType obj) Determines whether the argument TrianaType is equal to the current ComplexSpectrum.
void	extendWithZeros(int newLength, boolean front) Extends the data set to a longer set by padding with zeros, keeping the frequency resolution unchanged.
double	frequencyResolution() Obsolete method for obtaining frequency resolution.
double[]	getFrequencyArray(int dim) Returns the frequency values of the independent data points for the given dimension, in the order of lowest frequency to highest, regardless of how the data are stored internally.
double	getFrequencyResolution() Returns the frequency resolution of the data.
double	getFrequencyResolution(int dim) Returns the frequency resolution of the data for the given dimension (independent variable).
java.lang.Object	getGraphArrayImag(int dv) Returns the imaginary part of the dependent variable ordered so that the frequency values all run monotonically upwards.
java.lang.Object	getGraphArrayReal(int dv) Returns the real part of the dependent variable ordered so that the frequency values all run monotonically upwards.
double[]	getIndependentScaleImag(int dim) Returns null because the data is real.
double[]	getIndependentScaleReal(int dim) Returns the independent data scaled the way they should be graphed.
double	getLowerFrequencyBound() Returns the (non-negative) value of the lowest frequency in the frequency band held in the object.
double	getLowerFrequencyBound(int dim) Returns the (non-negative) value of the lowest frequency in the frequency band held in the object, for the given dimension dim.
double	getNyquist() Returns the Nyquist frequency, defined to be the highest frequency that this data set could contain if it were not narrow-banded.
java.lang.Object	getOrderedSpectrumImag() Returns the imaginary parts of the values of the spectrum (data points) in a multidimensional array, ordered so that in each dimension the values correspond to frequencies running from the lowest to the highest, regardless of the internal data model.
java.lang.Object	getOrderedSpectrumReal() Returns the real parts of the values of the spectrum (data points) in a multidimensional array, ordered so that in each dimension the values correspond to frequencies running from the lowest to the highest, regardless of the internal data model.
int	getOriginalN() Returns the number of points in the data set whose transform could have led to the present data, or equivalently the number of points in the two-sided full-bandwidth spectrum from which the present spectrum could have been derived.
int	getOriginalN(int dim) Returns the number of points in the data set in the given dimension whose transform could have led to the present data, or equivalently the number of points in the two-sided full-bandwidth spectrum from which the present spectrum could have been derived.
double	getSamplingRate() Returns the sampling frequency that a time-series would have had if it had led to the present spectral data set.
double	getUpperFrequencyBound() Returns the (non-negative) value of the highest frequency in the frequency band held in the object.
double	getUpperFrequencyBound(int dim) Returns the (non-negative) value of the highest frequency in the frequency band held in the object, for the given dimension dim.
void	inputFromStream(java.io.BufferedReader dis) Used when Triana types want to be able to receive ASCII data from the output of other programs.
void	interpolateZeros(int factor, boolean before) Inserts zeros in between existing elements of the data set.
boolean	isCompatible(TrianaType obj) Tests the argument object to determine if it makes sense to perform arithmetic operations between it and the current object.
boolean	isNarrow() Returns true if the data represent a narrow bandwidth derived from a full-band spectrum.
boolean	isNarrow(int dim) Returns true if the data for the given dimension represent a narrow bandwidth derived from a full-band spectrum.
boolean	isTwoSided() Returns true if the data are stored as a two-sided transform, i.e.
void	outputToStream(java.io.PrintWriter dos) Used when Triana types want to be able to send ASCII data to other programs using strings.
int	points() Obsolete method for obtaining the number of data points.
static ComplexSpectrum	reduceNyquist(ComplexSpectrum inputNarrow, boolean allocMem)
double	samplingFrequency() Obsolete method for obtaining sampling frequency.
void	setDefaultAxisLabelling() Added by I.
void	setFrequencyResolution(double df) Sets the frequency resolution of the data to the given value.
void	setFrequencyResolution(double df, int dim) Sets the frequency resolution of the data for the given dimension to the given value.
void	setNarrow(boolean n) Sets the narrow-bandedness flag to the value of the argument.
void	setNarrow(boolean n, int dim) Sets the narrow-bandedness flag associated with the given dimension to the value of the argument.
void	setOriginalN(int nOrig) Sets to the given argument the number of points in the data set whose transform could have led to the present data, or equivalently the number of points in the two-sided full-bandwidth spectrum from which the present spectrum could have been derived.
void	setOriginalN(int nOrig, int dim) Sets to the given first argument nOrig the number of points in the data set in the dimension given by the second argument dim whose transform could have led to the present data, or equivalently the number of points in the two-sided full-bandwidth spectrum from which the present spectrum could have been derived.
void	setTwoSided(boolean s) Sets the two-sidedness flag to the value of the argument.
void	setUpperFrequencyBound(double hf) Sets the (non-negative) value of the highest frequency in the frequency band held in the object to the given value.
void	setUpperFrequencyBound(double hf, int dim) Sets or resets the (non-negative) value of the highest frequency in the frequency band held in the object for the given direction dim to the value of the given argument hf.
protected void	updateObsoletePointers()

Methods inherited from class triana.types.VectorType

getData, getDataImag, getDataReal, getGraph, getGraphImag, getGraphReal, getScale, getScaleImag, getScaleReal, getXArray, getXImag, getXReal, getXTriplet, initialiseData, initialiseDataComplex, initialiseDataReal, isTriplet, isUniform, length, setData, setData, setDataImag, setDataReal, setX, setX, setX, setXImag, setXReal, size, testDataModel

Methods inherited from class triana.types.GraphType

add, addToTitle, convertDependentDataArraysToBytes, convertDependentDataArraysToDoubles, convertDependentDataArraysToFloats, convertDependentDataArraysToInts, convertDependentDataArraysToLongs, convertDependentDataArraysToShorts, copyData, copyLabels, divide, equals, getDataArrayClass, getDataArrayImag, getDataArrayImag, getDataArrayImagAsBytes, getDataArrayImagAsDoubles, getDataArrayImagAsFloats, getDataArrayImagAsInts, getDataArrayImagAsLongs, getDataArrayImagAsShorts, getDataArrayReal, getDataArrayReal, getDataArrayRealAsBytes, getDataArrayRealAsDoubles, getDataArrayRealAsFloats, getDataArrayRealAsInts, getDataArrayRealAsLongs, getDataArrayRealAsShorts, getDataArrayTypeNames, getDependentLabels, getDependentVariableDimensions, getDependentVariables, getDimensionLengths, getDimensionLengths, getGraphArrayImagLog10, getGraphArrayRealLog10, getIndependentArrayImag, getIndependentArrayReal, getIndependentLabels, getIndependentScaleImagLog10, getIndependentScaleRealLog10, getIndependentTriplet, getIndependentVariables, getLabels, getLabelsColumn, getTitle, isArithmeticArray, isArithmeticData, isCompatible, isDependentComplex, isIndependentComplex, isPrimitiveArray, isPrimitiveData, isTriplet, isUniform, maxDependentGraphingValuesImag, maxDependentGraphingValuesReal, maxDependentVariablesImag, maxDependentVariablesReal, maxIndependentScalesImag, maxIndependentScalesReal, maxIndependentVariablesImag, maxIndependentVariablesReal, minDependentGraphingValuesImag, minDependentGraphingValuesReal, minDependentVariablesImag, minDependentVariablesReal, minIndependentScalesImag, minIndependentScalesReal, minIndependentVariablesImag, minIndependentVariablesReal, multiply, resetDependent, resetIndependent, restrictToSubdomain, restrictToSubdomain, setDataArrayImag, setDataArrayReal, setDependentLabels, setDependentVariableDimensions, setDimensionLengths, setDimensionLengths, setDimensions, setIndependentArrayImag, setIndependentArrayReal, setIndependentLabels, setIndependentTriplet, setIndependentTriplet, setLabels, setTitle, subtract

Methods inherited from class triana.types.TrianaType

containerSize, dataExists, deleteFromContainer, getDataContainer, getFromContainer, getSequenceNumber, insertIntoContainer, inspectDataContainer, setDataContainer, setSequenceNumber

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

samplingFrequency

public double samplingFrequency

(Parameter that is kept for consistency with previous versions, but which is obsolete. It must be kept to the right values by the updateObsoletePointers method and/or constructors and set... methods.)

The sampling frequency -- this will not be supported in later versions, since it is part of the Signal interface and not the Spectral interface

frequencyResolution

public double frequencyResolution

(Parameter that is kept for consistency with previous versions, but which is obsolete. It must be kept to the right values by the updateObsoletePointers method and/or constructors and set... methods.)

The frequency resolution -- this is obsolete because it is public, and has been replaced by the private parameter resolution.

imag

public double[] imag

(Parameter that is kept for consistency with previous versions, but which is obsolete. It must be kept to the right values by the updateObsoletePointers method and/or constructors and set... methods.)

The imaginary part of the signal

real

public double[] real

(Parameter that is kept for consistency with previous versions, but which is obsolete. It must be kept to the right values by the updateObsoletePointers method and/or constructors and set... methods.)

The real part of the signal

Constructor Detail

ComplexSpectrum

public ComplexSpectrum()

Create and empty ComplexSpectrum with no parameters set.

ComplexSpectrum

public ComplexSpectrum(double sf,
               int points)

This is an obsolete Constructor that will be eliminated when possible. It uses samplingFrequency, a parameter that is obsolete. It is distinguished from the constructors that should be used by not having a boolean argument. This Constructor creates a new one-sided ComplexSpectrum with a certain sampling frequency and number of points. It also allocates memory for the data but does not initialise it. Use initialiseData to set all elements to zero.

Parameters:

sf - is the sampling frequency

points - is the number of points

See Also:

VectorType.initialiseData()

ComplexSpectrum

public ComplexSpectrum(double samplingFrequency,
               double[] real)

This is an obsolete Constructor that creates a new one-sided ComplexSpectrum with a certain sampling frequency and the actual allocated real data. The imaginary data is allocated and intialised to 0. It uses samplingFrequency, a parameter that is obsolete. It is distinguished from the constructors that should be used by not having a boolean argument.

Parameters:

samplingFrequency - is the sampling frequency

real - the actual allocated data

ComplexSpectrum

public ComplexSpectrum(double samplingFrequency,
               double[] real,
               double[] imag)

This is an obsolete Constructor that creates a new one-sided ComplexSpectrum with a certain sampling frequency and the actual allocated complex data. It uses samplingFrequency, a parameter that is obsolete. It is distinguished from the constructors that should be used by not having a boolean argument.

Parameters:

samplingFrequency - is the sampling frequency

real - The real part of the given data

imag - The imaginary part of the given data

ComplexSpectrum

public ComplexSpectrum(boolean ts,
               boolean nrw,
               int len,
               int nOrig,
               double df,
               double hf)

Creates a new ComplexSpectrum with arguments giving the sidedness, whether it is narrow-band or broad-band, the data length, the number of points in the original broad-band spectrum, the frequency resolution, and the highest frequency in the current spectrum. It does not allocate data. Various checks are performed on the consistency of the input parameters with the Triana spectral storage model, and error messages are printed to System.out.

Parameters:

ts - True if the new ComplexSpectrum is to be two-sided

nrw - True if the new ComplexSpectrum is to be narrow-band

len - Number of points in the current data set

nOrig - Number of points in the original two-sided full spectrum

df - Frequency resolution

hf - Highest frequency in the current data set

ComplexSpectrum

public ComplexSpectrum(boolean ts,
               boolean nrw,
               double[] real,
               double[] imag,
               int nOrig,
               double df,
               double hf)

Creates a new ComplexSpectrum with arguments giving the sidedness, whether it is narrow-band or broad-band, the data arrays, the number of points in the original broad-band spectrum, the frequency resolution, and the highest frequency in the current spectrum.

Parameters:

ts - True if the new ComplexSpectrum is to be two-sided

nrw - True if the new ComplexSpectrum is to be narrow-band

real - Real part of the data

imag - Imaginary part of the data

nOrig - Number of points in the original two-sided full spectrum

df - Frequency resolution

hf - Highest frequency in the current data set

ComplexSpectrum

public ComplexSpectrum(boolean ts,
               int nOrig,
               double df)

Creates a new ComplexSpectrum with a given sidedness, number of points that there would be in the two-sided spectrum, and frequency resolution. It does not allocate memory for the data. It assumes that the data are full-bandwidth.

Parameters:

ts - True if the new ComplexSpectrum is to be two-sided

nOrig - Number of points in the equivalent two-sided spectrum

df - Frequency resolution

ComplexSpectrum

public ComplexSpectrum(boolean ts,
               double[] real,
               double[] imag,
               int nOrig,
               double df)

Creates a new ComplexSpectrum with given sidedness, data arrays, number of points in the two-sided spectrum, and frequency resolution. It assumes that the data are full-bandwidth. The lengths of the input data arrays will be shorter than the size of the two-sided spectrum if the input is one-sided.

Parameters:

ts - True if the new ComplexSpectrum is to be two-sided

real - The real part of the input spectrum

imag - The imaginary part of the input spectrum

nOrig - Number of points in the equivalent two-sided spectrum

df - Frequency resolution

ComplexSpectrum

public ComplexSpectrum(Spectrum s,
               boolean copy)

Creates a ComplexSpectrum from a (real) Spectrum by setting the imaginary part of the data to zero. The second argument is used to choose whether the real data are copied or passed by reference.

Parameters:

s - The input data set

copy - True if the new data are to be copied from the old, false if passed by reference

ComplexSpectrum

public ComplexSpectrum(Spectrum s)

Creates a ComplexSpectrum from a (real) Spectrum by setting the imaginary part of the data to zero. The real data are passed by reference.

Parameters:

s - The input data set

Method Detail

setDefaultAxisLabelling

public void setDefaultAxisLabelling()

Added by I. Taylor, August 2001 : This function sets the default labeling scheme used for the axis by this data type. All constructors call this function to set default values for the axis.

Overrides:

setDefaultAxisLabelling in class GraphType

getFrequencyResolution

public double getFrequencyResolution(int dim)

Returns the frequency resolution of the data for the given dimension (independent variable). Since there is only one dimension in this object, this argument is ignored. This form of the method is required by the Spectral interface.

Specified by:

getFrequencyResolution in interface Spectral

Parameters:

dim - The index of the independent variable being queried

Returns:

The frequency resolution

getFrequencyResolution

public double getFrequencyResolution()

Returns the frequency resolution of the data.

Returns:

double The frequency resolution

setFrequencyResolution

public void setFrequencyResolution(double df,
                          int dim)

Sets the frequency resolution of the data for the given dimension to the given value. Since the data are one dimensional, the dimension argument is in fact ignored. This form of the method is required by the Spectral interface.

Specified by:

setFrequencyResolution in interface Spectral

Parameters:

dim - The index of the independent variable being queried

df - The frequency resolution

setFrequencyResolution

public void setFrequencyResolution(double df)

Sets the frequency resolution of the data to the given value.

isTwoSided

public boolean isTwoSided()

Returns true if the data are stored as a two-sided transform, i.e. containing both the positive and negative frequency data. If false, the data are one-sided, containing only positive frequencies.

Specified by:

isTwoSided in interface Spectral

Returns:

boolean True if data are two-sided in frequency space

setTwoSided

public void setTwoSided(boolean s)

Sets the two-sidedness flag to the value of the argument.

Specified by:

setTwoSided in interface Spectral

Parameters:

s - True if the data will be two-sided

getOriginalN

public int getOriginalN(int dim)

Returns the number of points in the data set in the given dimension whose transform could have led to the present data, or equivalently the number of points in the two-sided full-bandwidth spectrum from which the present spectrum could have been derived. Because the set is one-dimensional, the dimension argument is ignored. This form of the method is required by the Spectral interface.

Specified by:

getOriginalN in interface Spectral

Parameters:

dim - The index of the independent variable being queried

Returns:

The number of points in the original data set

getOriginalN

public int getOriginalN()

Returns the number of points in the data set whose transform could have led to the present data, or equivalently the number of points in the two-sided full-bandwidth spectrum from which the present spectrum could have been derived.

Returns:

int The number of points in the original data set

setOriginalN

public void setOriginalN(int nOrig,
                int dim)

Sets to the given first argument nOrig the number of points in the data set in the dimension given by the second argument dim whose transform could have led to the present data, or equivalently the number of points in the two-sided full-bandwidth spectrum from which the present spectrum could have been derived. Because the data are one-dimensional, the value of dim is ignored.

Specified by:

setOriginalN in interface Spectral

Parameters:

dim - The index of the independent variable being queried

nOrig - The new number of points in the original data set

setOriginalN

public void setOriginalN(int nOrig)

Sets to the given argument the number of points in the data set whose transform could have led to the present data, or equivalently the number of points in the two-sided full-bandwidth spectrum from which the present spectrum could have been derived.

Parameters:

nOrig - The new number of points in the original data set

isNarrow

public boolean isNarrow(int dim)

Returns true if the data for the given dimension represent a narrow bandwidth derived from a full-band spectrum. This form of the method is required by the Spectral interface.

Specified by:

isNarrow in interface Spectral

Parameters:

dim - The index of the independent variable being queried

Returns:

True if data are narrow-band

isNarrow

public boolean isNarrow()

Returns true if the data represent a narrow bandwidth derived from a full-band spectrum.

Returns:

True if data are narrow-band

setNarrow

public void setNarrow(boolean n,
             int dim)

Sets the narrow-bandedness flag associated with the given dimension to the value of the argument. Since the data are one-dimensional, the value of dim is ignored. This form of the method is required by the Spectral interface.

Specified by:

setNarrow in interface Spectral

Parameters:

n - True if the data held are narrow-band

dim - The index of the independent variable being set

setNarrow

public void setNarrow(boolean n)

Sets the narrow-bandedness flag to the value of the argument.

Parameters:

n - True if the data held are narrow-band

getLowerFrequencyBound

public double getLowerFrequencyBound(int dim)

Returns the (non-negative) value of the lowest frequency in the frequency band held in the object, for the given dimension dim. The data are one-dimensional so dim is ignored. This form of the method is required by the Spectral interface.

Specified by:

getLowerFrequencyBound in interface Spectral

Parameters:

dim - The index of the independent variable being queried

Returns:

The lowest frequency represented in the given direction

getLowerFrequencyBound

public double getLowerFrequencyBound()

Returns the (non-negative) value of the lowest frequency in the frequency band held in the object.

Returns:

double The lowest frequency represented in the given direction

getUpperFrequencyBound

public double getUpperFrequencyBound(int dim)

Returns the (non-negative) value of the highest frequency in the frequency band held in the object, for the given dimension dim. The data are one-dimensional so dim is ignored. This form of the method is required by the Spectral interface.

Specified by:

getUpperFrequencyBound in interface Spectral

Parameters:

dim - The index of the independent variable being queried

Returns:

The highest frequency represented in the given direction

getUpperFrequencyBound

public double getUpperFrequencyBound()

Returns the (non-negative) value of the highest frequency in the frequency band held in the object.

Returns:

double The highest frequency represented in the given direction

setUpperFrequencyBound

public void setUpperFrequencyBound(double hf,
                          int dim)

Sets or resets the (non-negative) value of the highest frequency in the frequency band held in the object for the given direction dim to the value of the given argument hf. Should be used after altering parameters or data in the object if they have changed the upper frequency bound. Because the data are one-dimensional, the value of dim is ignored.

Specified by:

setUpperFrequencyBound in interface Spectral

Parameters:

dim - The index of the independent variable being queried

hf - The new highest frequency represented in the given direction

setUpperFrequencyBound

public void setUpperFrequencyBound(double hf)

Sets the (non-negative) value of the highest frequency in the frequency band held in the object to the given value. Should be used after altering parameters or data in the object if they have changed the upper frequency bound. This should also set the isNarrow flag if the given value is not the highest value of the original-length spectrum.

Parameters:

hf - The new highest frequency

getFrequencyArray

public double[] getFrequencyArray(int dim)

Returns the frequency values of the independent data points for the given dimension, in the order of lowest frequency to highest, regardless of how the data are stored internally.

Specified by:

getFrequencyArray in interface Spectral

Parameters:

dim - The dimension of the independent variable

Returns:

double[] Array of ordered frequency values

getOrderedSpectrumReal

public java.lang.Object getOrderedSpectrumReal()

Returns the real parts of the values of the spectrum (data points) in a multidimensional array, ordered so that in each dimension the values correspond to frequencies running from the lowest to the highest, regardless of the internal data model. These points then correspond to the values returned by getFrequencyArray for each dimension.

Specified by:

getOrderedSpectrumReal in interface Spectral

Returns:

Object Multidimensional arrray of ordered spectral values

getOrderedSpectrumImag

public java.lang.Object getOrderedSpectrumImag()

Returns the imaginary parts of the values of the spectrum (data points) in a multidimensional array, ordered so that in each dimension the values correspond to frequencies running from the lowest to the highest, regardless of the internal data model. These points then correspond to the values returned by getFrequencyArray for each dimension.

Specified by:

getOrderedSpectrumImag in interface Spectral

Returns:

Object Multidimensional arrray of ordered spectral values

getNyquist

public double getNyquist()

Returns the Nyquist frequency, defined to be the highest frequency that this data set could contain if it were not narrow-banded. For full-bandwidth sets, this is the same value as is returned by getUpperFrequencyBound(), but for narrow-band data sets it may be higher.

The general formula is that if the original number of data points (given by nFull = getOriginalN()) is even, then the Nyquist frequency is nFull * resolution / 2. If the original number of data points is odd, then the Nyquist frequency is (nFull -1 ) * resolution / 2.

Returns:

double The Nyquist frequency

getSamplingRate

public double getSamplingRate()

Returns the sampling frequency that a time-series would have had if it had led to the present spectral data set.

Returns:

double The sampling frequency

samplingFrequency

public double samplingFrequency()

Obsolete method for obtaining sampling frequency. Will be withdrawn.

Returns:

the sampling frequency

points

public int points()

Obsolete method for obtaining the number of data points. Will be withdrawn.

Returns:

the number of points in this ComplexSpectrum

frequencyResolution

public double frequencyResolution()

Obsolete method for obtaining frequency resolution. Will be withdrawn.

Returns:

the frequency resolution

getIndependentScaleReal

public double[] getIndependentScaleReal(int dim)

Returns the independent data scaled the way they should be graphed.

Overrides:

getIndependentScaleReal in class GraphType

Parameters:

dim - The independent dimension under consideration

Returns:

The scaled independent data values

getIndependentScaleImag

public double[] getIndependentScaleImag(int dim)

Returns null because the data is real.

Overrides:

getIndependentScaleImag in class GraphType

Parameters:

dim - The independent dimension under consideration

Returns:

The scaled independent data values

getGraphArrayReal

public java.lang.Object getGraphArrayReal(int dv)

Returns the real part of the dependent variable ordered so that the frequency values all run monotonically upwards.

Overrides:

getGraphArrayReal in class GraphType

Parameters:

dv - The dependent variable dimension

Returns:

Object An array containing the rearranged data values

getGraphArrayImag

public java.lang.Object getGraphArrayImag(int dv)

Returns the imaginary part of the dependent variable ordered so that the frequency values all run monotonically upwards.

Overrides:

getGraphArrayImag in class GraphType

Parameters:

dv - The dependent variable dimension

Returns:

Object An array containing the rearranged data values

extendWithZeros

public void extendWithZeros(int newLength,
                   boolean front)

Extends the data set to a longer set by padding with zeros, keeping the frequency resolution unchanged. If the new length is shorter than the old (as given by method getOriginalN, then nothing is done. This method does not use the method of the same name in VectorType. Instead it takes advantage of the narrow-band feature of the Triana spectral data model to add zeros "virtually", without increasing the storage required. The way this is done depends on the value of the given parameter front.

If front is true, then nothing is done and a warning message is printed to the debug stream, because it is not possible in the Triana spectral model to extend a spectrum "below" zero-frequency. Negative frequencies are already included in the spectrum either explictly or implicitly, so there is no room for more points at the "front" of the data set. Even if the data set is narrow-band and does not include zero frequency, the data down to zero frequency are already set to zero implicitly, so that there is no way to add more of them.

If the boolean argument front is false, then the method extends the spectrum to higher frequencies, but the extra zeros are added "virtually", i.e. by extending the length nFull of the original data set and not adding the zeros explicitly. If the original data set was broad-band, it is marked as narrow-band after extension.

The details of how this works are best understood by thinking of the original (un-extended) data set as having been obtained from the final (extended one) by low-pass filtering. It is a consequence of the Triana spectral data model that applying a low-pass filter to a full-bandwidth data set of any length nFull results in a data set whose new value of nFull is odd. If the data set before extension has an odd number of elements, then the extension requires only the actions described above.

On the other hand, if the data set before extension has an even value of nFull, then it must be converted to one with an odd number before it can be extended. This is done in this method by identifying all the elements of the old set with those of the new one with the same frequency except for the highest frequency. In the new (odd-length) set there are two elements for the highest frequency, one at positive frequency and one at negative. In the old (even-length) set there is only one, at the negative frequency. The elements of the new one are determined as follows: the negative-frequency element is set equal to the old negative-frequency element divided by sqrt(2), and the positive-frequency element is set equal to the complex-conjugate of this. This choice is rather arbitrary, but it ensures that, if this data set represents a Fourier transform, then the total power is unchanged. Of course, if the original data is narrow-band and has already lost its highest frequencies, then the new element is just set to zero, and this is done "virtually", by adjusting various parameters. If the data set is one-sided, then only the positive-frequency element is added. When an element is added, then the independent variable Triplet is extended by one as well.

Overrides:

extendWithZeros in class VectorType

Parameters:

newLength - The new length of the data set

front - True if padding is at the front, false for padding at the back

interpolateZeros

public void interpolateZeros(int factor,
                    boolean before)

Inserts zeros in between existing elements of the data set. The integer argument factor gives the number of zeros per existing data point that must be inserted. The boolean argument before regulates whether the zeros should be inserted before each element (if true) or after (false). The new values of the independent variable are interpolated between those of the old ones.

If the argument factor is zero or negative, nothing is done.

In ComplexSpectrum, the interpolation is done in such a way that the frequency resolution is increased and the pre-existing data points remain at the same value of the frequency. This means that it is illegal to add zeroes before the first element, which corresponds to zero frequency. So if before is true then the method returns without doing anything, and prints a warning.

If the value of before is false, then the interpolation is done in such a way that the frequency resolution is divided by (factor + 1) and the original number of points is changed by (factor + 1). This ensures that the original data points remain at the same values of the frequency. The requisite number of zeros is added after each data point. If the spectrum is two-sided, then the way interpolation as done in VectorType is correct here too, and only the parameters are changed, as just described. If the spectrum is one-sided, then ordinary interpolation adds too many at the end, and this method removes the extra ones.

Derived types should override this if necessary to provide for the correct handling of parameters and other special features.

Overrides:

interpolateZeros in class VectorType

Parameters:

factor - The number of zeros per data point to be inserted

before - True if the zeros go before each point, false if after

copyMe

public TrianaType copyMe()

This is one of the most important methods of Triana data. types. It returns a copy of the type invoking it. This must be overridden for every derived data type derived. If not, the data cannot be copied to be given to other units. Copying must be done by value, not by reference.

To override, the programmer should not invoke the super.copyMe method. Instead, create an object of the current type and call methods copyData and copyParameters. If these have been written correctly, then they will do the copying. The code should createTool, for type YourType:

 YourType y = null; try { y =
 (YourType)getClass().newInstance(); y.copyData( this ); y.copyParameters( this ); y.setLegend( this.getLegend()
 ); } catch (IllegalAccessException ee) { System.out.println("Illegal Access: " + ee.getMessage()); } catch
 (InstantiationException ee) { System.out.println("Couldn't be instantiated: " + ee.getMessage()); } return y;
 

The copied object's data should be identical to the original. The method here modifies only one item: a String indicating that the object was created as a copy is added to the description StringVector.

Overrides:

copyMe in class VectorType

Returns:

TrianaType Copy by value of the current Object except for an updated description

copyParameters

protected void copyParameters(TrianaType source)

Copies modifiable parameters from the argument object to the current object. The copying is by value, not by reference. Parameters are defined as data not held in dataContainer. They are modifiable if they have set... methods. Parameters that cannot be modified, but which are set by constructors, should be placed correctly into the copied object when it is constructed.

In ComplexSpectrum, the new parameters are resolution, highestFrequency, twoSided, narrow, nFull. The obsolete parameters samplingFrequency and frequencyResolution are generated automatically when the other parameters are copied and set.

This must be overridden by any subclass that defines new parameters. The overriding method should invoke its super method. It should use the set... and get... methods for the parameters in question. This method is protected so that it cannot be called except by objects that inherit from this one. It is called by copyMe().

Overrides:

copyParameters in class GraphType

Parameters:

source - Data object that contains the data to be copied.

outputToStream

public void outputToStream(java.io.PrintWriter dos)
                    throws java.io.IOException

Used when Triana types want to be able to send ASCII data to other programs using strings. This is used to implement socket and to run other executables, written in C or other languages. With ASCII you don't have to worry about ENDIAN'ness as the conversions are all done via text. This is obviously slower than binary communication since you have to format the input and output within the other program.

This method must be overridden in every subclass that defines new data or parameters. The overriding method should first call<

 super.outputToStream(dos) 

to get output from superior classes, and then new parameters defined for the current subclass must be output. Moreover, subclasses that first dimension their data arrays must explicitly transfer these data arrays.

Specified by:

outputToStream in interface AsciiComm

Overrides:

outputToStream in class GraphType

Parameters:

dos - The data output stream

Throws:

java.io.IOException

inputFromStream

public void inputFromStream(java.io.BufferedReader dis)
                     throws java.io.IOException

Used when Triana types want to be able to receive ASCII data from the output of other programs. This is used to implement socket and to run other executables, written in C or other languages. With ASCII you don't have to worry about ENDIAN'ness as the conversions are all done via text. This is obviously slower than binary communication since you have to format the input and output within the other program.

This method must be overridden in every subclass that defines new data or parameters. The overriding method should first call

 super.inputFromStream(dis) 

to get input from superior classes, and then new parameters defined for the current subclass must be input. Moreover, subclasses that first dimension their data arrays must explicitly transfer these data arrays.

Specified by:

inputFromStream in interface AsciiComm

Overrides:

inputFromStream in class GraphType

Parameters:

dis - The data input stream

Throws:

java.io.IOException

isCompatible

public boolean isCompatible(TrianaType obj)

Tests the argument object to determine if it makes sense to perform arithmetic operations between it and the current object.

In ComplexSpectrum, the method first tests that the input object is compatible with superior classes, and then (if it is a ComplexSpectrum( it tests if the input has the same frequency resolution, upper frequency bound, two-sidedness, and narrow-bandedness.

Classes derived from this should over-ride this method with further tests as appropriate. The over-riding method should normally have the first lines

 boolean test = super.isCompatible( obj ); 

followed by other tests. If other types not subclassed from GraphType or Const should be allowed to be compatible then other tests must be implemented.

Overrides:

isCompatible in class VectorType

Parameters:

obj - The data object to be compared with the current one

Returns:

True if the object can be combined with the current one

equals

public boolean equals(TrianaType obj)

Determines whether the argument TrianaType is equal to the current ComplexSpectrum. They are equal if the argument is a ComplexSpectrum with the same size, parameters, and data.

This method must be over-ridden in derived types. In a derived type called xxx the method should begin

 if ( !( obj instanceof xxx ) ) return
 false; if ( !isCompatible( obj ) ) return false; 

followed by tests that are specific to type xxx (testing its own parameters) and then as a last line

 return super.equals( obj ); 

This line invokes the other equals methods up the chain to GraphType. Each superior object tests its own parameters.

Parameters:

obj - The object being tested

Returns:

true if they are equal or false otherwise

updateObsoletePointers

protected void updateObsoletePointers()

Overrides:

updateObsoletePointers in class VectorType

reduceNyquist

public static ComplexSpectrum reduceNyquist(ComplexSpectrum inputNarrow,
                            boolean allocMem)