triana.types

Class Spectrum2D

java.lang.Object

triana.types.TrianaType

triana.types.GraphType

triana.types.MatrixType

triana.types.Spectrum2D

All Implemented Interfaces:

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

public class Spectrum2D
extends MatrixType
implements AsciiComm, Spectral

Spectrum2D is the class derived from MatrixType to represent a two-dimensional array whose elements contain the two-dimensional Fourier transform of a two-dimensional data set. Spectrum2D implements the Spectral Interface and the Triana spectral data model, as described in the documentation for ComplexSpectrum, with the exception that it does not allow data to be narrow-band or one-sided; these would make the storage in two dimensions excessively complicated. Spectrum2D allows data to be real or complex, so it combines the 2D analogues of Spectrum and ComplexSpectrum.

Spectrum2D assumes the variables are uniformly sampled in both directions. It introduces new parameter arrays resolution, twoSided (set to true, highestFrequency, narrow (set to false), and nFull. These parameters have the same meaning as in ComplexSpectrum, but are 2-dimensional arrays for the 2 spectral dims.

See Also:

MatrixType, TrianaType, GraphType, Spectrum, ComplexSpectrum, Spectral, Serialized Form

Field Summary

Fields inherited from class triana.types.TrianaType

NOT_CONNECTED, NOT_READY, OUT_OF_RANGE

Constructor Summary

Constructors

Constructor and Description
Spectrum2D() Creates a new empty Spectrum2D, with no parameters set
Spectrum2D(boolean complex, int[] lengths, double[] df) Creates a new Spectrum2D with arguments giving whether the data are to be complex.
Spectrum2D(double[][] zr, double[][] zi, double[] df) Creates a new Spectrum2D with argument arrays giving the 2D data matrix, or two matrices if the data is complex, and the frequency resolution in each dimension.

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 Spectrum2D.
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(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(int dim) Returns the (non-negative) value of the lowest frequency in the frequency band held in the object, for the given dimension dim.
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 two-dimensional array, ordered so that in both dimensions the values correspond to frequencies running from the lowest to the highest, regardless of the internal data model.
int	getOriginalN(int dim) Returns the number of points in the data set in the frequency 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	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.
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(int dim) Returns false.
boolean	isTwoSided() Returns true.
void	outputToStream(java.io.PrintWriter dos) Used when Triana types want to be able to send ASCII data to other programs using strings.
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, int dim) Does nothing.
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) Does nothing.
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.

Methods inherited from class triana.types.MatrixType

getData, getDataImag, getDataReal, getXorYArray, getXorYImag, getXorYReal, getXorYTriplet, initialiseData, initialiseDataComplex, initialiseDataReal, length, setData, setData, setXorY, setXorY, 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, setDefaultAxisLabelling, 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, updateObsoletePointers

Methods inherited from class java.lang.Object

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

Constructor Detail

Spectrum2D

public Spectrum2D()

Creates a new empty Spectrum2D, with no parameters set

Spectrum2D

public Spectrum2D(boolean complex,
          int[] lengths,
          double[] df)

Creates a new Spectrum2D with arguments giving whether the data are to be complex. Arrays give the sidedness, the data length, the number of points in the original broad-band spectrum, and the frequency resolution for each dimension. The constructor allocates memory for the data but expects the data to be defined later.

Parameters:

complex - True if the data is to be complex

lengths - Number of frequency points in the current data set

df - Frequency resolution in each dimension

Spectrum2D

public Spectrum2D(double[][] zr,
          double[][] zi,
          double[] df)

Creates a new Spectrum2D with argument arrays giving the 2D data matrix, or two matrices if the data is complex, and the frequency resolution in each dimension.

Parameters:

zr - the real part of the data

zi - the imaginary part of the data, null if absent

df - Frequency resolution

Method Detail

getFrequencyResolution

public double getFrequencyResolution(int dim)

Returns the frequency resolution of the data for the given dimension (independent variable).

Specified by:

getFrequencyResolution in interface Spectral

Parameters:

dim - The index of the independent variable being queried

Returns:

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.

Specified by:

setFrequencyResolution in interface Spectral

Parameters:

dim - The index of the independent variable being queried

df - The frequency resolution

isTwoSided

public boolean isTwoSided()

Returns true. Included because Spectral demands it.

Specified by:

isTwoSided in interface Spectral

Returns:

boolean True if data are two-sided in frequency space

setTwoSided

public void setTwoSided(boolean s)

Does nothing.

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

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

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.

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

isNarrow

public boolean isNarrow(int dim)

Returns false. Included because Spectral demands it.

Specified by:

isNarrow in interface Spectral

Parameters:

dim - The index of the independent variable being queried

Returns:

True if data are narrow-band

setNarrow

public void setNarrow(boolean n,
             int dim)

Does nothing.

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

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. In this version, all data start at zero frequency; no narrow-banding is allowed. 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

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.

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

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. Since narrow-banding is not allowed, this can only be reset if the frequency resolution is changed. This method makes that change.

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

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 two-dimensional array, ordered so that in both dimensions 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

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

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 MatrixType

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.

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 Spectrum2D, this method tests for compatibility with superior classes, to see that the input object is a Spectrum2D, and to see if the relevant parameters are equal. It does not enforce equality of acquisitionTime because it may be desirable to compare two data sets acquired at different times.

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 MatrixType

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 Spectrum2D. They are equal if the argument is a Spectrum2D 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