triana.types

Class Spectrum

java.lang.Object

triana.types.TrianaType

triana.types.GraphType

triana.types.VectorType

triana.types.Spectrum

All Implemented Interfaces:

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

public class Spectrum
extends VectorType
implements Spectral, AsciiComm

Spectrum is a subclass of VectorType that stores one or two one-dimensional arrays of double-precision real numbers representing either a real Fourier spectrum (normally a power spectrum or an amplitude spectrum) or a complex Fourier spectrum (normally the Fourier transform of a data set), a Triplet giving the integer values of the index of this array, and introduces 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 Spectrum 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. Where ComplexSpectrum is the basic Triana class for holding one-dimensional Fourier tranforms, Spectrum is the basic class for power spectra. It implements the Spectral interface. In particular it implements the same Triana data storage model for storing spectral data.

The full Triana 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. The full Triana model is described fully in the ComplexSpectrum documentation. Spectrum implements those parts that do not require the complex phase of the full spectrum. In particular, it can contain spectra that are full-bandwidth or narrow-band.

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 many could apply to each dimension of multi-dimensional sets. However, Spectrum can only handle one-dimensional data.

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 Spectrum 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 at indices k and N-k are equal to one another. Such a real 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 values at indices k and N-k are equal to one another. Such a spectrum can be converted to a one-sided representation without the loss of information.

A one-sided Spectrum includes only non-negative frequencies. The data model assumes that the data come from a spectrum that was the transform of a data set containing only real values. Thus, values at the negative frequencies that are not represented in the data set will be assumed to be equal to 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. 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). 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.

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. 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). 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.

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 (in the case of ComplexSpectrum data sets) to preserve as much as possible of the information needed to invert the spectrum back to a time-series.

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 than 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.

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. 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. If the lower frequency limit is positive, then the bottom of the band is missing.

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

See Also:

Spectral, SampleSet, ComplexSpectrum, Triplet, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
double[]	data (Parameter that is kept for consistency with previous versions, but which is obsolete.
double	frequencyResolution (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
Spectrum() Create and empty Spectrum with no parameters set.
Spectrum(boolean ts, boolean nrw, double[] real, double[] imag, int nOrig, double df, double hf) Creates a new complex Spectrum 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.
Spectrum(boolean ts, boolean nrw, double[] data, int nOrig, double df, double hf) Creates a new real Spectrum with arguments giving the sidedness, whether it is narrow-band or broad-band, the data array, the number of points in the original broad-band spectrum, the frequency resolution, and the highest frequency in the current spectrum.
Spectrum(boolean ts, boolean nrw, int len, int nOrig, double df, double hf) Creates a new Spectrum 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.
Spectrum(boolean ts, double[] real, double[] imag, int nOrig, double df) Creates a new complex Spectrum with given sidedness, data arrays, number of points in the two-sided spectrum, and frequency resolution.
Spectrum(boolean ts, double[] data, int nOrig, double df) Creates a new real Spectrum with given sidedness, data arrays, number of points in the two-sided spectrum, and frequency resolution.
Spectrum(boolean ts, int nOrig, double df) Creates a new Spectrum with a given sidedness, number of points that there would be in the two-sided spectrum, and frequency resolution.
Spectrum(ComplexSpectrum cs) Creates a Spectrum from a ComplexSpectrum by keeping only the real part of the data.
Spectrum(ComplexSpectrum cs, boolean copy) Creates a Spectrum from a ComplexSpectrum by keeping only the real part of the data.
Spectrum(double samplingFrequency, double[] data) Obsolete Constructor that creates a new one-sided Spectrum with a certain sampling frequency and the actual allocated data.
Spectrum(double sf, int points) This is an obsolete Constructor that will be eliminated when possible.

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 Spectrum.
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 in the independent dimension dim.
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 direction 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 dimension 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.
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 direction 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 represent a narrow bandwidth derived from a full-band spectrum in the independent dimension dim.
boolean	isTwoSided() Returns true if the data are stored as a two-sided transform, i.e. containing both the positive and negative frequency data.
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 Spectrum	reduceNyquist(Spectrum inputNarrow, boolean allocMem) Class method that takes an input narrow-band Spectrum and reduces nFull to be compatible with the upper frequency bound, so that the set is no longer narrow-band at the top.
double	samplingFrequency() Obsolete method for obtaining sampling frequency.
void	setDefaultAxisLabelling() Added by I.
void	setFrequencyResolution(double df) Sets the frequency resolution of the data.
void	setFrequencyResolution(double f, int dim) Sets the frequency resolution of the data in the independent dimension dim.
void	setNarrow(boolean n) Sets the narrow-band flag to the value of the argument.
void	setNarrow(boolean n, int dim) Sets the narrow-band flag associated with the independent dimension dim (second argument) to the value of the first 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, true if the data are two-sided.
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 given value 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. Constructors and methods ensure that this is kept equal to resolution.

data

public double[] data

(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 signal data, a pointer which is kept pointing at the appropriate location in dataContainer.

Constructor Detail

Spectrum

public Spectrum()

Create and empty Spectrum with no parameters set.

Spectrum

public Spectrum(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 now be used by not having a boolean argument. This Constructor creates a new one-sided Spectrum with a certain sampling frequency and number of points. It also allocates memory for the data but does not initialise it. Use method initialiseData to set all elements to zero.

Parameters:

sf - is the sampling frequency

points - is the number of points

See Also:

VectorType.initialiseData()

Spectrum

public Spectrum(double samplingFrequency,
        double[] data)

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

Parameters:

samplingFrequency - is the sampling frequency

data - the actual allocated data

Spectrum

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

Creates a new Spectrum 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 Spectrum is to be two-sided

nrw - True if the new Spectrum 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

Spectrum

public Spectrum(boolean ts,
        boolean nrw,
        double[] data,
        int nOrig,
        double df,
        double hf)

Creates a new real Spectrum with arguments giving the sidedness, whether it is narrow-band or broad-band, the data array, 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 Spectrum is to be two-sided

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

data - The data

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

df - Frequency resolution

hf - Highest frequency in the current data set

Spectrum

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

Creates a new complex Spectrum 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 Spectrum is to be two-sided

nrw - True if the new Spectrum 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

Spectrum

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

Creates a new Spectrum 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 Spectrum is to be two-sided

nOrig - Number of points

df - Frequency resolution

Spectrum

public Spectrum(boolean ts,
        double[] data,
        int nOrig,
        double df)

Creates a new real Spectrum 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 Spectrum is to be two-sided

data - The real part of the input spectrum

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

df - Frequency resolution

Spectrum

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

Creates a new complex Spectrum 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 Spectrum 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

Spectrum

public Spectrum(ComplexSpectrum cs,
        boolean copy)

Creates a Spectrum from a ComplexSpectrum by keeping only the real part of the data. The boolean parameter determines whether the data of the new object are copied from the old or simply referenced.

Parameters:

cs - The input data set

copy - True if the new data will be a copy of the old

Spectrum

public Spectrum(ComplexSpectrum cs)

Creates a Spectrum from a ComplexSpectrum by keeping only the real part of the data. The data of the new object are simply referenced from the old.

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 in the independent dimension dim. Because the data are really one-dimensional, the dimension argument is ignored.

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 f,
                          int dim)

Sets the frequency resolution of the data in the independent dimension dim. Because the data are one-dimensional, dim is ignored.

Specified by:

setFrequencyResolution in interface Spectral

Parameters:

dim - The index of the independent variable being queried

f - The frequency resolution

setFrequencyResolution

public void setFrequencyResolution(double df)

Sets the frequency resolution of the data.

Parameters:

df - The frequency resolution

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, true if the data are two-sided.

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 dimension 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:

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 represent a narrow bandwidth derived from a full-band spectrum in the independent dimension dim. Because the data are one-dimensional, the value of dim is ignored.

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:

boolean true if data are narrow-band

setNarrow

public void setNarrow(boolean n,
             int dim)

Sets the narrow-band flag associated with the independent dimension dim (second argument) to the value of the first argument. Because the data are one-dimensional, the value of dim is ignored.

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-band 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 direction dim. Because the data are one-dimensional, the value of dim is ignored.

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 direction dim. Because the data are one-dimensional, the value of dim is ignored.

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

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 given value hf. 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. 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 Spectrum

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 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. If the spectrum is real, then it is assumed to be a power spectrum, and the negative-frequency element is set equal to the old negative-frequency element divided by 2, and the positive-frequency element is set equal to this. If the spectrum is complex, then it is assumed to represent a Fourier transform, and the negative-frequency element is set equal to the old negative-frequency element divided by sqrt(2), while the positive-frequency element is set equal to the complex- conjugate of this value. This choice is rather arbitrary, but it ensures that, under the assumptions, 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 Spectrum, 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 Spectrum, 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 Spectrum, this method first tests for compatibility with superior classes, and then (if the input object is a Spectrum) tests that the input has the same frequency resolution, upper frequency bound, two-sidedness, and narrow-bandedness as the current object.

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 Spectrum. They are equal if the argument is a Spectrum 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 Spectrum reduceNyquist(Spectrum inputNarrow,
                     boolean allocMem)

Class method that takes an input narrow-band Spectrum and reduces nFull to be compatible with the upper frequency bound, so that the set is no longer narrow-band at the top. This is useful in doing resampling of time-series data. The Nyquist frequency is the highest frequency allowed by the sampling rate. If the input is not narrow-band, then the method returns null.

Parameters:

inputNarrow - The input narrow-band spectrum

allocMem - True if the output is a modified copy of input

Returns:

The reduced-sampling-rate spectrum