net.talvi.puffinplot.data
Class Datum

java.lang.Object
  extended by net.talvi.puffinplot.data.Datum

public class Datum
extends java.lang.Object

Datum is the fundamental data class of PuffinPlot. It represents the state of a sample at a particular point during the stepwise demagnetization process. The essential item of data is the demagnetization vector representing a particular magnetometer measurement. A large number of other fields give additional data about demagnetization procedures, other measurements, and sample characteristics. Some of these fields (such as the sample orientation) are in fact sample-level data rather than demagnetization-step-level data, and may be moved to Sample in a later version of PuffinPlot.

Datum is a mutable container class which is intended to be instantiated with no or very little data. Most of the fields can be set after instantiation using setter methods.

In terms of PuffinPlot's user interface, a Datum often defines the position and appearance of a point on one or more of the plots.

See Also:
DatumField

Nested Class Summary
static class Datum.Reader
          This class allows datum objects to be created from string representations of a specified format.
 
Constructor Summary
Datum()
          Creates a datum with no data.
Datum(double x, double y, double z)
          Creates a datum with a specified magnetization vector.
Datum(Vec3 vector)
          Creates a datum with a supplied magnetization vector.
 
Method Summary
 java.lang.String exportFieldValues(java.util.Collection<DatumField> fields, java.lang.String delimiter)
          Produces a string containing string representations of the contents of selected data fields.
 double getAfX()
          For AF or ARM treatment, returns the AF field strength in the x axis.
 double getAfY()
          For AF or ARM treatment, returns the AF field strength in the y axis.
 double getAfZ()
          For AF or ARM treatment, returns the AF field strength in the z axis.
 double getArea()
          For continuous measurements, returns the cross-sectional area of the core.
 ArmAxis getArmAxis()
          For ARM treatment, returns the axis of the ARM field.
 double getArmField()
          For ARM treatment, returns the ARM bias field strength.
 java.lang.String getDepth()
          For continuous measurements, returns the depth of this measurement within the core.
 java.lang.String getDiscreteId()
          For discrete samples, returns the sample identifier (name).
 double getFormAz()
          Returns the formation dip azimuth.
 double getFormDip()
          Returns the formation dip angle.
 double getFormStrike()
          Returns the formation strike for this datum.
 java.lang.String getIdOrDepth()
          Returns sample identifier or measurement depth.
 double getIntensity()
          Returns the magnitude of the magnetic dipole moment per unit volume in A/m.
 double getIrmField()
          For IRM treatment, returns the IRM field strength.
 Line getLine()
          Returns the measurement's data-file line.
 double getMagDev()
          Returns the local geomagnetic field declination for the sampling site.
 double getMagSus()
          Returns the magnetic susceptibility of the sample at this stage of treatment
 MeasType getMeasType()
          Returns the type of this measurement (discrete or continuous).
 Vec3 getMoment()
          Strictly speaking, the name is not quite accurate: we do not deal with magnetic moment (which would be in Am2) but in magnetic dipole moment per unit volume (in A/m).
 Vec3 getMoment(Correction correction)
          Returns the measured magnetic dipole moment per unit volume, as modified by the supplied correction.
 int getRunNumber()
          Returns the number of the machine run during which this measurement was made.
 double getSampAz()
          Returns the sample's dip azimuth.
 double getSampDip()
          Returns the sample's dip angle.
 double getSampHade()
          Returns the sample hade for this datum.
 Sample getSample()
          Returns the sample of which this measurement was made.
 int getSlotNumber()
          Returns the number of the measurement tray slot in which the sample was measured.
 Suite getSuite()
          Returns the data suite containing this measurement.
 double getTemp()
          For thermal treatment, returns the temperature in degrees Celsius.
 java.lang.String getTimestamp()
          Returns the timestamp of this measurement.
 double getTreatmentLevel()
          Returns a numerical representation of the intensity of the treatment which was applied immediately before this measurement.
 TreatType getTreatType()
          Returns the treatment applied before this measurement (AF, thermal, etc.).
 java.lang.String getValue(DatumField field)
          Returns a String representation of a value from a specified data field.
 double getVolume()
          For discrete measurements, returns the volume of the sample.
 double getXDrift()
          Returns the x drift correction value.
 double getYDrift()
          Returns the y drift correction value.
 double getZDrift()
          Returns the z drift correction value.
 boolean hasMagMoment()
          Reports whether the datum contains a magnetic moment measurement.
 boolean hasMagSus()
          Reports whether this datum has any magnetic susceptibility data.
 boolean ignoreOnLoading()
          Returns true if this datum should be ignored (thrown away) when loading a data file.
 boolean isHidden()
          Reports whether this datum should be hidden on plots.
 boolean isInPca()
          Reports whether this measurement is used for a PCA fit.
 boolean isMagSusOnly()
          Reports whether this datum has magnetic susceptibility but not magnetic moment data.
 boolean isOnCircle()
          Reports whether this measurement is used for a great-circle fit.
 boolean isPcaAnchored()
          Reports whether PCA fits for this point should be anchored.
 boolean isSelected()
          Reports whether this datum is selected.
static double maxIntensity(java.util.List<Datum> data)
          Returns the maximum magnitude of magnetic dipole moment per unit volume within the supplied group of datum objects.
static double maxMagSus(java.util.List<Datum> data)
          Returns the maximum magnetic susceptibility within the supplied group of datum objects.
static double maxTreatmentLevel(java.util.List<Datum> data)
          Returns the maximum treatment level within the supplied group of datum objects.
 void rot180(MeasurementAxis axis)
          Rotates magnetic moment data 180 degrees about the specified axis.
 void setAfX(double v)
          For AF or ARM treatment, sets the AF field strength in the x axis.
 void setAfY(double v)
          For AF or ARM treatment, sets the AF field strength in the y axis.
 void setAfZ(double v)
          For AF or ARM treatment, sets the AF field strength in the z axis.
 void setArea(double v)
          For continuous measurements, sets the cross-sectional area of the core.
 void setArmAxis(ArmAxis v)
          For ARM treatment, sets the axis of the ARM field.
 void setArmField(double v)
          For ARM treatment, sets the ARM bias field strength.
 void setDepth(java.lang.String v)
          For continuous measurements, sets the depth of this measurement within the core.
 void setDiscreteId(java.lang.String v)
          For discrete samples, sets the sample identifier (name).
 void setFormAz(double v)
          Sets the formation dip azimuth.
 void setFormDip(double v)
          Sets the formation dip angle.
 void setFormStrike(double strikeDeg)
          Sets the formation strike for this datum.
 void setHidden(boolean v)
          Sets whether this datum should be hidden on plots.
 void setInPca(boolean v)
          Sets whether this measurement is to be used for a PCA fit.
 void setIrmField(double v)
          For IRM treatment, sets the IRM field strength.
 void setLine(Line v)
          Sets the measurement's data-file line.
 void setMagDev(double v)
          Sets the local geomagnetic field declination for the sampling site.
 void setMagSus(double v)
          Sets the magnetic susceptibility of the sample at this stage of treatment.
 void setMeasType(MeasType v)
          Sets the type of this measurement (discrete or continuous).
 void setMoment(Vec3 v)
          Sets the sample's magnetic dipole moment per unit volume in A/m.
 void setOnCircle(boolean v)
          Sets whether this measurement is to be used for a great-circle fit.
 void setPcaAnchored(boolean v)
          Sets whether PCA fits for this point should be anchored.
 void setRunNumber(int v)
          Sets the number of the machine run during which this measurement was made.
 void setSampAz(double v)
          Sets the sample's dip azimuth.
 void setSampDip(double v)
          Sets the sample's dip angle.
 void setSampHade(double hadeDeg)
          Sets the sample hade for this datum.
 void setSample(Sample v)
          Sets the sampe on which this measurement was made.
 void setSelected(boolean v)
          Sets the selection state of this datum.
 void setSlotNumber(int v)
          Sets the number of the measurement tray slot in which the sample was measured.
 void setSuite(Suite v)
          Sets the data suite containing this measurement.
 void setTemp(double v)
          For thermal treatment, sets the temperature in degrees Celsius.
 void setTimestamp(java.lang.String v)
          Sets the timestamp of this measurement.
 void setTreatType(TreatType v)
          Sets the treatment applied before this measurement (AF, thermal, etc.).
 void setValue(DatumField field, java.lang.String value)
          Sets the value of a specified data field using a string.
 void setVolume(double v)
          For discrete measurements, sets the volume of the sample.
 void setXDrift(double v)
          Sets the x drift correction value.
 void setYDrift(double v)
          Sets the y drift correction value.
 void setZDrift(double v)
          Sets the z drift correction value.
 void toggleSel()
          Toggles the datum's selection state.
 java.util.List<java.lang.String> toStrings()
          Produces a list of strings representing the data values within this datum object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Datum

public Datum(double x,
             double y,
             double z)
Creates a datum with a specified magnetization vector.

Parameters:
x - x component of the magnetization vector
y - y component of the magnetization vector
z - z component of the magnetization vector

Datum

public Datum(Vec3 vector)
Creates a datum with a supplied magnetization vector.

Parameters:
vector - the magnetization vector

Datum

public Datum()
Creates a datum with no data. The moment is set to zero.

Method Detail

isSelected

public boolean isSelected()
Reports whether this datum is selected.

Returns:
true if this datum is selected

setSelected

public void setSelected(boolean v)
Sets the selection state of this datum.

Parameters:
v - true to select this datum, false to deselect

getSampAz

public double getSampAz()
Returns the sample's dip azimuth.

Returns:
the sample's dip azimuth in degrees

setSampAz

public void setSampAz(double v)
Sets the sample's dip azimuth.

Parameters:
v - the sample dip azimuth to set, in degrees

getSampDip

public double getSampDip()
Returns the sample's dip angle.

Returns:
the sample's dip angle, in degrees

setSampDip

public void setSampDip(double v)
Sets the sample's dip angle.

Parameters:
v - the sample dip angle to set, in degrees

getFormAz

public double getFormAz()
Returns the formation dip azimuth.

Returns:
the formation dip azimuth in degrees

setFormAz

public void setFormAz(double v)
Sets the formation dip azimuth.

Parameters:
v - the formation dip azimuth to set, in degrees

getFormDip

public double getFormDip()
Returns the formation dip angle.

Returns:
the formation dip angle, in degrees

setFormDip

public void setFormDip(double v)
Sets the formation dip angle.

Parameters:
v - the formation dip angle to set, in degrees

getMagDev

public double getMagDev()
Returns the local geomagnetic field declination for the sampling site.

Returns:
the local geomagnetic field declination, in degrees

setMagDev

public void setMagDev(double v)
Sets the local geomagnetic field declination for the sampling site.

Parameters:
v - the local geomagnetic field declination to set, in degrees

isPcaAnchored

public boolean isPcaAnchored()
Reports whether PCA fits for this point should be anchored.

Returns:
true if PCA fits to this point should be anchored

setPcaAnchored

public void setPcaAnchored(boolean v)
Sets whether PCA fits for this point should be anchored.

Parameters:
v - true to set PCA fits for this point to be anchored

getLine

public Line getLine()
Returns the measurement's data-file line. Not currently used.

Returns:
the data-file line for this measurement; not currently used

setLine

public void setLine(Line v)
Sets the measurement's data-file line. Not currently used.

Parameters:
v - the data-file line to set for this measurement; not currently used

getSample

public Sample getSample()
Returns the sample of which this measurement was made.

Returns:
the sample on which this measurement was made

setSample

public void setSample(Sample v)
Sets the sampe on which this measurement was made.

Parameters:
v - the sample on which this measurement was made

isHidden

public boolean isHidden()
Reports whether this datum should be hidden on plots.

Returns:
true if this datum should not be displayed on plots

setHidden

public void setHidden(boolean v)
Sets whether this datum should be hidden on plots.

Parameters:
v - true if this datum should not be displayed on plots

getDepth

public java.lang.String getDepth()
For continuous measurements, returns the depth of this measurement within the core.

Returns:
for continuous measurements, the depth of this measurement within the core

setDepth

public void setDepth(java.lang.String v)
For continuous measurements, sets the depth of this measurement within the core.

Parameters:
v - for continuous measurements, the depth of this measurement within the core

getMagSus

public double getMagSus()
Returns the magnetic susceptibility of the sample at this stage of treatment

Returns:
the magnetic susceptibility of the sample at this stage of treatment

setMagSus

public void setMagSus(double v)
Sets the magnetic susceptibility of the sample at this stage of treatment.

Parameters:
v - the magnetic susceptibility of the sample at this stage of treatment

getMeasType

public MeasType getMeasType()
Returns the type of this measurement (discrete or continuous).

Returns:
the type of this measurement (discrete or continuous)

setMeasType

public void setMeasType(MeasType v)
Sets the type of this measurement (discrete or continuous).

Parameters:
v - the type of this measurement (discrete or continuous)

getDiscreteId

public java.lang.String getDiscreteId()
For discrete samples, returns the sample identifier (name).

Returns:
for discrete samples, the identifier (name) of the sample

setDiscreteId

public void setDiscreteId(java.lang.String v)
For discrete samples, sets the sample identifier (name).

Parameters:
v - for discrete samples, the identifier (name) of the sample

getTreatType

public TreatType getTreatType()
Returns the treatment applied before this measurement (AF, thermal, etc.).

Returns:
the treatment applied before this measurement (AF, thermal, etc.)

setTreatType

public void setTreatType(TreatType v)
Sets the treatment applied before this measurement (AF, thermal, etc.).

Parameters:
v - the treatment applied before this measurement (AF, thermal, etc.)

getAfX

public double getAfX()
For AF or ARM treatment, returns the AF field strength in the x axis.

Returns:
for AF or ARM treatment, the AF field strength in the x axis

setAfX

public void setAfX(double v)
For AF or ARM treatment, sets the AF field strength in the x axis.

Parameters:
v - for AF or ARM treatment, the AF field strength in the x axis

getAfY

public double getAfY()
For AF or ARM treatment, returns the AF field strength in the y axis.

Returns:
for AF or ARM treatment, the AF field strength in the y axis

setAfY

public void setAfY(double v)
For AF or ARM treatment, sets the AF field strength in the y axis.

Parameters:
v - for AF or ARM treatment, the AF field strength in the y axis

getAfZ

public double getAfZ()
For AF or ARM treatment, returns the AF field strength in the z axis.

Returns:
for AF or ARM treatment, the AF field strength in the z axis

setAfZ

public void setAfZ(double v)
For AF or ARM treatment, sets the AF field strength in the z axis.

Parameters:
v - for AF or ARM treatment, the AF field strength in the z axis

getIrmField

public double getIrmField()
For IRM treatment, returns the IRM field strength.

Returns:
for IRM treatment, the IRM field strength

setIrmField

public void setIrmField(double v)
For IRM treatment, sets the IRM field strength.

Parameters:
v - for IRM treatment, the IRM field strength

getArmField

public double getArmField()
For ARM treatment, returns the ARM bias field strength.

Returns:
for ARM treatment, the ARM bias field strength

setArmField

public void setArmField(double v)
For ARM treatment, sets the ARM bias field strength.

Parameters:
v - for ARM treatment, the ARM bias field strength

getArmAxis

public ArmAxis getArmAxis()
For ARM treatment, returns the axis of the ARM field.

Returns:
for ARM treatment, the axis of the ARM field

setArmAxis

public void setArmAxis(ArmAxis v)
For ARM treatment, sets the axis of the ARM field.

Parameters:
v - for ARM treatment, the axis of the ARM field

getTemp

public double getTemp()
For thermal treatment, returns the temperature in degrees Celsius.

Returns:
for thermal treatment, the temperature in degrees Celsius

setTemp

public void setTemp(double v)
For thermal treatment, sets the temperature in degrees Celsius.

Parameters:
v - for thermal treatment, the temperature in degrees Celsius

getArea

public double getArea()
For continuous measurements, returns the cross-sectional area of the core.

Returns:
the cross-sectional area of the core

setArea

public void setArea(double v)
For continuous measurements, sets the cross-sectional area of the core.

Parameters:
v - the cross-sectional area of the core

getVolume

public double getVolume()
For discrete measurements, returns the volume of the sample.

Returns:
for discrete measurements, the volume of the sample

setVolume

public void setVolume(double v)
For discrete measurements, sets the volume of the sample.

Parameters:
v - for discrete measurements, the volume of the sample

getRunNumber

public int getRunNumber()
Returns the number of the machine run during which this measurement was made.

Returns:
the number of the machine run during which this measurement was made

setRunNumber

public void setRunNumber(int v)
Sets the number of the machine run during which this measurement was made.

Parameters:
v - the number of the machine run during which this measurement was made

getTimestamp

public java.lang.String getTimestamp()
Returns the timestamp of this measurement.

Returns:
the timestamp of this measurement

setTimestamp

public void setTimestamp(java.lang.String v)
Sets the timestamp of this measurement.

Parameters:
v - the timestamp of this measurement

getXDrift

public double getXDrift()
Returns the x drift correction value.

Returns:
the x drift correction value

setXDrift

public void setXDrift(double v)
Sets the x drift correction value.

Parameters:
v - the x drift correction value

getYDrift

public double getYDrift()
Returns the y drift correction value.

Returns:
the y drift correction value

setYDrift

public void setYDrift(double v)
Sets the y drift correction value.

Parameters:
v - the y drift correction value

getZDrift

public double getZDrift()
Returns the z drift correction value.

Returns:
the z drift correction value

setZDrift

public void setZDrift(double v)
Sets the z drift correction value.

Parameters:
v - the z drift correction value

getSlotNumber

public int getSlotNumber()
Returns the number of the measurement tray slot in which the sample was measured.

Returns:
the number of the measurement tray slot in which the sample was measured

setSlotNumber

public void setSlotNumber(int v)
Sets the number of the measurement tray slot in which the sample was measured.

Parameters:
v - the number of the measurement tray slot in which the sample was measured

getSuite

public Suite getSuite()
Returns the data suite containing this measurement.

Returns:
the data suite containing this measurement

setSuite

public void setSuite(Suite v)
Sets the data suite containing this measurement.

Parameters:
v - the data suite containing this measurement

isOnCircle

public boolean isOnCircle()
Reports whether this measurement is used for a great-circle fit.

Returns:
true if this measurement is used for a great-circle fit

setOnCircle

public void setOnCircle(boolean v)
Sets whether this measurement is to be used for a great-circle fit.

Parameters:
v - true to use this measurement for a great-circle fit

isInPca

public boolean isInPca()
Reports whether this measurement is used for a PCA fit.

Returns:
true if this measurement is used for a PCA fit

setInPca

public void setInPca(boolean v)
Sets whether this measurement is to be used for a PCA fit.

Parameters:
v - true to use this measurement for a PCA fit

getSampHade

public double getSampHade()
Returns the sample hade for this datum.

Returns:
the sample's hade, in degrees

setSampHade

public void setSampHade(double hadeDeg)
Sets the sample hade for this datum. Since the hade is the complement of the dip, this will of course change the sample's dip.

Parameters:
hadeDeg - the hade to set, in degrees

getFormStrike

public double getFormStrike()
Returns the formation strike for this datum.

Returns:
the formation strike, in degrees

setFormStrike

public void setFormStrike(double strikeDeg)
Sets the formation strike for this datum. This will of course also set the formation dip azimuth.

Parameters:
strikeDeg - the formation strike, in degrees

getIdOrDepth

public java.lang.String getIdOrDepth()
Returns sample identifier or measurement depth. If the measurement is discrete, returns the sample identifier; if the measurement is continuous, returns a string representation of the measurement's depth within the core.

Returns:
sample identifier or depth within core, as appropriate

hasMagSus

public boolean hasMagSus()
Reports whether this datum has any magnetic susceptibility data.

Returns:
true if there is magnetic susceptibility data in this datum

isMagSusOnly

public boolean isMagSusOnly()
Reports whether this datum has magnetic susceptibility but not magnetic moment data.

Returns:
true if this datum contains magnetic susceptibility data and does not contain magnetic moment data

getMoment

public Vec3 getMoment()

Strictly speaking, the name is not quite accurate: we do not deal with magnetic moment (which would be in Am2) but in magnetic dipole moment per unit volume (in A/m). But getMagneticDipoleMomentPerUnitVolumeInAm would be an inconveniently long method name.

Returns:
the magnetic dipole moment per unit volume in A/m

setMoment

public void setMoment(Vec3 v)
Sets the sample's magnetic dipole moment per unit volume in A/m.

Parameters:
v - the magnetic dipole moment per unit volume in A/m

getMoment

public Vec3 getMoment(Correction correction)
Returns the measured magnetic dipole moment per unit volume, as modified by the supplied correction. The correction may specify that the moment should be rotated to correct for sample and/or formation orientation. It also allows the specification of tray and empty-slot corrections, but these are not presently implemented here. (Tray corrections are applied when loading a file, and empty-slot corrections are unimplemented.)

Parameters:
correction - the corrections to apply to the magnetic moment measurement
Returns:
the corrected magnetic dipole moment per unit volume in A/m

rot180

public void rot180(MeasurementAxis axis)
Rotates magnetic moment data 180 degrees about the specified axis.

Parameters:
axis - the axis about which to perform the rotation

toggleSel

public void toggleSel()
Toggles the datum's selection state. datum.toggleSel() is functionally equivalent to datum.setSelected(!datum.isSelected().


getTreatmentLevel

public double getTreatmentLevel()

Returns a numerical representation of the intensity of the treatment which was applied immediately before this measurement. The interpretation of the number depends on the treatment type. For thermal treatment, it is a temperature in degrees Celsius. For magnetic treatments (AF demagnetization, ARM, IRM) it returns the magnetic field. As is conventional, the magnetic field is returned as the equivalent magnetic induction in units of Tesla.

For ARM treatment, this method returns the strength of the alternating field rather than the DC bias field.

Returns:
the treatment level

maxTreatmentLevel

public static double maxTreatmentLevel(java.util.List<Datum> data)
Returns the maximum treatment level within the supplied group of datum objects.

Parameters:
data - a list of datum objects
Returns:
the highest treatment level for any of the supplied datum objects

maxIntensity

public static double maxIntensity(java.util.List<Datum> data)
Returns the maximum magnitude of magnetic dipole moment per unit volume within the supplied group of datum objects.

Parameters:
data - a list of datum objects
Returns:
the highest magnitude of magnetic dipole moment per unit volume for any of the supplied datum objects

maxMagSus

public static double maxMagSus(java.util.List<Datum> data)
Returns the maximum magnetic susceptibility within the supplied group of datum objects.

Parameters:
data - a list of datum objects
Returns:
the highest magnetic susceptibility for any of the supplied datum objects

getIntensity

public double getIntensity()
Returns the magnitude of the magnetic dipole moment per unit volume in A/m.

Returns:
magnitude of magnetic dipole moment per unit volume in A/m

ignoreOnLoading

public boolean ignoreOnLoading()
Returns true if this datum should be ignored (thrown away) when loading a data file. Currently, this method returns true if the measurement type is NONE &endash; that is, there is no data within the object.

Returns:
true if this datum should be ignored when loading a file

hasMagMoment

public boolean hasMagMoment()
Reports whether the datum contains a magnetic moment measurement.

Returns:
true if the datum contains a magnetic moment measurement

getValue

public java.lang.String getValue(DatumField field)
Returns a String representation of a value from a specified data field.

Parameters:
field - the field to read
Returns:
a string representation of the value contained in the field

setValue

public void setValue(DatumField field,
                     java.lang.String value)
Sets the value of a specified data field using a string.

Parameters:
field - the field to set the value of
value - a string representation of the value to set the field to
Throws:
java.lang.NumberFormatException - if the format of the string is not compatible with the format of the field to be set

toStrings

public java.util.List<java.lang.String> toStrings()
Produces a list of strings representing the data values within this datum object. The order of the strings corresponds to the order of the fields in DatumField.realFields.

Returns:
a list of strings representing the data values within this datum

exportFieldValues

public java.lang.String exportFieldValues(java.util.Collection<DatumField> fields,
                                          java.lang.String delimiter)
Produces a string containing string representations of the contents of selected data fields. The values are separated by a specified delimiter.

Parameters:
fields - the fields for which values should be produced
delimiter - the string which should separate the values
Returns:
a string representation of the requested values