net.talvi.puffinplot.data
Class Sample

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

public class Sample
extends java.lang.Object

This class represents a sample on which measurements have been made. It may correspond either to a discrete, physical specimen, or to a particular point on a continuous long core or u-channel sample.


Constructor Summary
Sample(java.lang.String name, Suite suite)
          Creates a new sample.
 
Method Summary
 void addDatum(Datum datum)
          Adds a data point to this sample.
 void calculateMagSusJump()
          Calculates the position of the first jump in magnetic susceptibility in the sample's demagnetization data.
 void calculateMdf()
          Calculates the median destructive field using the visible data points of this sample and stores the results within this sample.
 void clearCalculations()
          Clears all calculations for this sample (PCA, MDF, and great-circle fit) and deselects all data points.
 void doPca(Correction correction)
          Performs principal component analysis on a subset of the magnetic moment data of this sample.
 java.util.List<java.lang.String> exportFields(java.util.List<DatumField> fields)
          Returns a specified subset of demagnetization data as strings.
 void fitGreatCircle(Correction correction)
          Fits a great circle to a subset of the magnetic moment vectors in this sample.
 void flip(MeasurementAxis axis)
          Rotates all magnetic moment data 180 degrees about the sepcified axis.
 void fromString(java.lang.String string)
          Sets some of sample's fields based on a supplied string.
 Tensor getAms()
          Returns this sample's AMS tensor.
 java.util.List<Vec3> getCirclePoints(Correction correction)
          Returns the magnetic moment vectors used for the current great-circle fit.
 CustomFields<java.lang.Boolean> getCustomFlags()
          Returns this sample's custom flags.
 CustomFields<java.lang.String> getCustomNotes()
          Returns this sample's custom notes.
 java.util.List<Datum> getData()
          Returns all the data points within this sample.
 Datum getDatum(int i)
          Returns a specified data point from this sample
 Datum getDatumByRunNumber(int maxRunNumber)
          Returns the datum with the highest run number which is less than the supplied run number.
 double getDepth()
          Returns the depth of a this sample within a continuous long core, where applicable.
 double getFirstGcStep()
          Returns the treatment level for the first point used in the great-circle fit.
 int getFirstRunNumber()
          Returns the run number for the first data point in this sample.
 double getFormAz()
          Returns this sample's formation dip azimuth in degrees.
 double getFormDip()
          Returns this sample's formation dip angle in degrees.
 double getFormStrike()
          Returns this sample's formation strike in degrees.
 GreatCircle getGreatCircle()
          Returns the current great-circle fit for this sample, if any.
 double getLastGcStep()
          Returns the treatment level for the last point used in the great-circle fit.
 int getLastRunNumber()
          Returns the run number for the last data point in this sample.
 double getMagDev()
          Returns the geomagnetic field declination at the sampling site.
 double getMagSusJump()
          Returns the results of the magnetic susceptibility jump calculation, if it has been performed.
 MedianDestructiveField getMdf()
          Returns the results of the MDF calculation if it has been performed, or null if not.
 MeasType getMeasType()
          Returns the measurement type of this sample (discrete or continuous).
 java.lang.String getNameOrDepth()
          Returns the sample identifier or depth.
 double getNrm()
          Returns the intensity of the sample's natural remanent magnetization (NRM).
 int getNumData()
          Returns the number of data points within this sample.
 PcaAnnotated getPcaAnnotated()
          Returns the annotated results of the last PCA calculation.
 PcaValues getPcaValues()
          Returns the results of the last PCA calculation.
 double getSampAz()
          Returns this sample's dip azimuth in degrees.
 double getSampDip()
          Returns this sample's dip angle in degrees.
 double getSampHade()
          Returns this sample's hade in degrees.
 java.util.List<Datum> getSelectedData()
          Returns all the selected data points within this sample.
 java.util.BitSet getSelectionBitSet()
          Returns the selected data point indices as a bit set.
 Site getSite()
          Returns the site for this sample.
 int getSlotNumber()
          Returns the tray slot number for discrete samples.
 Suite getSuite()
          Returns the suite containing this sample.
 java.util.List<Datum> getVisibleData()
          Returns all the visible (non-hidden) data points within this sample.
 boolean hasData()
          Reports whether this sample contains any data.
 boolean hasMsData()
          Reports whether this sample has any magnetic susceptibility data.
 void hideSelectedPoints()
          Sets all the selected data points within this sample to be hidden, so they will not be shown on plots.
 boolean isEmptySlot()
          Reports whether this sample is an empty slot on the measurement tray.
 boolean isPcaAnchored()
          Reports whether principal component analysis should be anchored for this sample
 boolean isSelectionContiguous()
          Returns true if the selected points are contiguous.
 void selectAll()
          Selects all the data points within this sample.
 void selectNone()
          De-selects all the data points within this sample.
 void selectVisible()
          Selects all the visible (non-hidden) data points within this sample.
 void setAmsDirections(double i1, double d1, double i2, double d2, double i3, double d3)
          Sets the AMS data for the sample using the supplied principal directions.
 void setAmsFromTensor(double k11, double k22, double k33, double k12, double k23, double k13)
          Sets the AMS data for this sample using the supplied tensor.
 void setCorrections(double sampleAz, double sampleDip, double formAz, double formDip, double magDev)
          Sets the orientation corrections for this sample's magnetic moment data.
 void setEmptySlot(boolean isEmptySlot)
          Sets whether this sample is an empty slot on the measurement tray.
 void setPcaAnchored(boolean pcaAnchored)
          Sets whether principal component analysis should be anchored for this sample
 void setSelectionBitSet(java.util.BitSet selection)
          Sets the selection state of the sample's data points from a supplied bit set.
 void setSite(Site site)
          Sets the site for this sample.
 void setValue(DatumField field, java.lang.String value)
          Sets the value of a specified field for each data point in the sample.
 java.util.List<java.lang.String> toStrings()
          Returns a list of Strings representing data pertaining to this sample.
 void unhideAllPoints()
          Unhides all data points within this sample.
 void useSelectionForCircleFit()
          Flags the selected data points for use in the next great-circle fit.
 void useSelectionForPca()
          Flags all selected data points for inclusion in principal component analysis
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Sample

public Sample(java.lang.String name,
              Suite suite)
Creates a new sample. For discrete samples, the supplied name can take any form; for long core samples, it should be a string representation of a number giving the depth.

Parameters:
name - sample identifier or numerical depth
suite - the data suite of which this sample is a part
Method Detail

clearCalculations

public void clearCalculations()
Clears all calculations for this sample (PCA, MDF, and great-circle fit) and deselects all data points.


getSuite

public Suite getSuite()
Returns the suite containing this sample.

Returns:
the suite containing this sample

calculateMdf

public void calculateMdf()
Calculates the median destructive field using the visible data points of this sample and stores the results within this sample.

See Also:
getMdf()

getMdf

public MedianDestructiveField getMdf()
Returns the results of the MDF calculation if it has been performed, or null if not.

Returns:
the results of the MDF calculation if it has been performed, or null if not
See Also:
calculateMdf()

getDepth

public double getDepth()
Returns the depth of a this sample within a continuous long core, where applicable. For a discrete sample, an arbitrary value may be returned.

Returns:
the depth of a measurement on a continuous long core

getNrm

public double getNrm()
Returns the intensity of the sample's natural remanent magnetization (NRM). The value returned is a magnetic dipole moment per unit volume in units of A/m.

Returns:
the intensity of the sample's natural remanent magnetization

calculateMagSusJump

public void calculateMagSusJump()
Calculates the position of the first jump in magnetic susceptibility in the sample's demagnetization data. The result is stored within this sample. A jump is defined as an increase of at least 2.5 times in a single treatment step. If the is no magnetic susceptibility data, or if no jump occurs, a value of 0 will be used.

See Also:
getMagSusJump()

getMagSusJump

public double getMagSusJump()
Returns the results of the magnetic susceptibility jump calculation, if it has been performed. If not, an arbitrary value may be returned.

Returns:
the results of the magnetic susceptibility jump calculation
See Also:
calculateMagSusJump()

flip

public void flip(MeasurementAxis axis)
Rotates all magnetic moment data 180 degrees about the sepcified axis.

Parameters:
axis - the axis about which to rotate the data

hideSelectedPoints

public void hideSelectedPoints()
Sets all the selected data points within this sample to be hidden, so they will not be shown on plots.

See Also:
Datum.isHidden()

selectAll

public void selectAll()
Selects all the data points within this sample.

See Also:
Datum.setSelected(boolean)

selectVisible

public void selectVisible()
Selects all the visible (non-hidden) data points within this sample.

See Also:
Datum.setSelected(boolean), Datum.isHidden()

selectNone

public void selectNone()
De-selects all the data points within this sample.


hasData

public boolean hasData()
Reports whether this sample contains any data.

Returns:
true if this sample contains any data

getData

public java.util.List<Datum> getData()
Returns all the data points within this sample.

Returns:
all the data points within this sample

getVisibleData

public java.util.List<Datum> getVisibleData()
Returns all the visible (non-hidden) data points within this sample.

Returns:
all the visible (non-hidden) data points within this sample

getSelectedData

public java.util.List<Datum> getSelectedData()
Returns all the selected data points within this sample.

Returns:
all the selected data points within this sample

isSelectionContiguous

public boolean isSelectionContiguous()
Returns true if the selected points are contiguous. This is the case if there are no unselected points between the first selected point and the last selected point.

Returns:
true if the selected points are contiguous

getNumData

public int getNumData()
Returns the number of data points within this sample.

Returns:
the number of data points within this sample

getDatum

public Datum getDatum(int i)
Returns a specified data point from this sample

Parameters:
i - the index of the requested data point
Returns:
the data point with the selected index, if it exists
Throws:
java.lang.IndexOutOfBoundsException - if no data point with the selected index exists

addDatum

public void addDatum(Datum datum)
Adds a data point to this sample.

Parameters:
datum - a data point to add to this sample

setCorrections

public void setCorrections(double sampleAz,
                           double sampleDip,
                           double formAz,
                           double formDip,
                           double magDev)
Sets the orientation corrections for this sample's magnetic moment data.

Parameters:
sampleAz - the sample dip azimuth
sampleDip - the sample dip angle
formAz - the formation dip azimuth
formDip - the formation dip angle
magDev - the geomagnetic field declination at the sampling site

hasMsData

public boolean hasMsData()
Reports whether this sample has any magnetic susceptibility data.

Returns:
true if this sample has any magnetic susceptibility data

useSelectionForPca

public void useSelectionForPca()
Flags all selected data points for inclusion in principal component analysis


isPcaAnchored

public boolean isPcaAnchored()
Reports whether principal component analysis should be anchored for this sample

Returns:
true if principal component analysis should be anchored for this sample

setPcaAnchored

public void setPcaAnchored(boolean pcaAnchored)
Sets whether principal component analysis should be anchored for this sample

Parameters:
pcaAnchored - true to anchor principal component analysis for this sample

doPca

public void doPca(Correction correction)
Performs principal component analysis on a subset of the magnetic moment data of this sample. The data points to use are determined by the result of Datum.isInPca(). The results are stored within the sample and may be retrieved with getPcaAnnotated().

Parameters:
correction - the correction to apply to the magnetic moment data

getPcaAnnotated

public PcaAnnotated getPcaAnnotated()
Returns the annotated results of the last PCA calculation.

Returns:
the annotated results of the last PCA calculation

getPcaValues

public PcaValues getPcaValues()
Returns the results of the last PCA calculation.

Returns:
the results of the last PCA calculation

useSelectionForCircleFit

public void useSelectionForCircleFit()
Flags the selected data points for use in the next great-circle fit.


getGreatCircle

public GreatCircle getGreatCircle()
Returns the current great-circle fit for this sample, if any.

Returns:
the current great-circle fit for this sample, if any

getCirclePoints

public java.util.List<Vec3> getCirclePoints(Correction correction)
Returns the magnetic moment vectors used for the current great-circle fit.

Parameters:
correction - the correction to apply to the magnetic moment vectors
Returns:
the magnetic moment vectors used for the current great-circle fit

fitGreatCircle

public void fitGreatCircle(Correction correction)
Fits a great circle to a subset of the magnetic moment vectors in this sample. A data point is used for the fit if Datum.isOnCircle() is true for it.

Parameters:
correction - the correction to apply to the magnetic moment data

getFirstGcStep

public double getFirstGcStep()
Returns the treatment level for the first point used in the great-circle fit.

Returns:
the treatment level for the first point used in the great-circle fit

getLastGcStep

public double getLastGcStep()
Returns the treatment level for the last point used in the great-circle fit.

Returns:
the treatment level for the last point used in the great-circle fit

getMeasType

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

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

getNameOrDepth

public java.lang.String getNameOrDepth()
Returns the sample identifier or depth. For a discrete sample this will return the name (identifier) of the sample. For a continuous sample it will return a string representation of the depth.

Returns:
the sample identifier or depth

getSlotNumber

public int getSlotNumber()
Returns the tray slot number for discrete samples. Not currently used.

Returns:
the tray slot number for discrete samples

getFirstRunNumber

public int getFirstRunNumber()
Returns the run number for the first data point in this sample.

Returns:
the run number for the first data point in this sample

getLastRunNumber

public int getLastRunNumber()
Returns the run number for the last data point in this sample.

Returns:
the run number for the last data point in this sample

getDatumByRunNumber

public Datum getDatumByRunNumber(int maxRunNumber)
Returns the datum with the highest run number which is less than the supplied run number. Intended to be used in applying tray corrections. Not currently used.

Parameters:
maxRunNumber -
Returns:
the Datum in this sample which has the highest run number smaller than the supplied run number, or null if this sample contains no such Datum.

isEmptySlot

public boolean isEmptySlot()
Reports whether this sample is an empty slot on the measurement tray.

Returns:
true if this sample is an empty slot on the measurement tray

setEmptySlot

public void setEmptySlot(boolean isEmptySlot)
Sets whether this sample is an empty slot on the measurement tray.

Parameters:
isEmptySlot - true to declare this sample as an empty slot on the measurement tray

unhideAllPoints

public void unhideAllPoints()
Unhides all data points within this sample.


getSelectionBitSet

public java.util.BitSet getSelectionBitSet()
Returns the selected data point indices as a bit set. The data points within the sample are ordered, and each bit in the bit set is set to the selection state of the corresponding data point. This is useful for copying and pasting selection patterns, allowing corresponding points to be selected in multiple samples.

Returns:
the selected data point indices as a bit set
See Also:
setSelectionBitSet(java.util.BitSet)

setSelectionBitSet

public void setSelectionBitSet(java.util.BitSet selection)
Sets the selection state of the sample's data points from a supplied bit set. For each index in the bit set, the data point with the same index within the sample is selected if the bit has a 1 value.

Parameters:
selection - a template for the selection state of the data points
See Also:
getSelectionBitSet()

getSite

public Site getSite()
Returns the site for this sample.

Returns:
the site for this sample

setSite

public void setSite(Site site)
Sets the site for this sample.

Parameters:
site - the site for this sample

setAmsFromTensor

public void setAmsFromTensor(double k11,
                             double k22,
                             double k33,
                             double k12,
                             double k23,
                             double k13)
Sets the AMS data for this sample using the supplied tensor.

Parameters:
k11 - tensor value (1,1)
k22 - tensor value (2,2)
k33 - tensor value (3,3)
k12 - tensor value (1,2)
k23 - tensor value (2,3)
k13 - tensor value (1,3)

setAmsDirections

public void setAmsDirections(double i1,
                             double d1,
                             double i2,
                             double d2,
                             double i3,
                             double d3)
Sets the AMS data for the sample using the supplied principal directions. All angles are in degrees.

Parameters:
i1 - inclination of principal axis 1
d1 - declination of principal axis 1
i2 - inclination of principal axis 2
d2 - declination of principal axis 2
i3 - inclination of principal axis 3
d3 - declination of principal axis 3

getAms

public Tensor getAms()
Returns this sample's AMS tensor.

Returns:
this sample's AMS tensor, or null if none has been set

exportFields

public java.util.List<java.lang.String> exportFields(java.util.List<DatumField> fields)
Returns a specified subset of demagnetization data as strings. This method takes a list of DatumFields and returns a list of strings. Each string in the list represents one Datum in this sample, and consists of a concatenation of string representations of the requested fields (in the corresponding order), delimited by tab characters.

Parameters:
fields - the fields to export
Returns:
a string representation of the requested fields for each Datum in this sample

toStrings

public java.util.List<java.lang.String> toStrings()
Returns a list of Strings representing data pertaining to this sample. (Note that this only includes sample-level data, not Datum-level data such as magnetic moment measurements.)

Returns:
a list of Strings representing data pertaining to this sample

fromString

public void fromString(java.lang.String string)
Sets some of sample's fields based on a supplied string. Any string produced by toStrings() is a valid input for this method.

Parameters:
string - a string specifying some of the sample's fields

getCustomFlags

public CustomFields<java.lang.Boolean> getCustomFlags()
Returns this sample's custom flags.

Returns:
this sample's custom flags

getCustomNotes

public CustomFields<java.lang.String> getCustomNotes()
Returns this sample's custom notes.

Returns:
this sample's custom notes

getSampAz

public double getSampAz()
Returns this sample's dip azimuth in degrees.

Returns:
this sample's dip azimuth in degrees

getSampDip

public double getSampDip()
Returns this sample's dip angle in degrees.

Returns:
this sample's dip angle in degrees

getSampHade

public double getSampHade()
Returns this sample's hade in degrees.

Returns:
this sample's hade in degrees

getFormAz

public double getFormAz()
Returns this sample's formation dip azimuth in degrees.

Returns:
sampAz this sample's formation dip azimuth in degrees

getFormStrike

public double getFormStrike()
Returns this sample's formation strike in degrees.

Returns:
sampAz this sample's formation strike in degrees

getFormDip

public double getFormDip()
Returns this sample's formation dip angle in degrees.

Returns:
sampAz this sample's formation dip angle in degrees

getMagDev

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

Returns:
the geomagnetic field declination at the sampling site

setValue

public void setValue(DatumField field,
                     java.lang.String value)
Sets the value of a specified field for each data point in the sample.

Parameters:
field - the field to set
value - the value to which to set the specified field