net.talvi.puffinplot.data
Class Suite

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

public final class Suite
extends java.lang.Object

A suite of data, containing a number of samples. This will usually correspond to a section (for discrete studies) or core (for continuous studies).


Nested Class Summary
static class Suite.AmsCalcType
          The type of a statistical calculation on AMS tensors.
static interface Suite.SiteNamer
          A SiteNamer turns a sample name into a site name.
 
Constructor Summary
Suite(java.util.List<java.io.File> files)
          Creates a new suite from the specified files.
Suite(java.util.List<java.io.File> files, SensorLengths sensorLengths, TwoGeeLoader.Protocol protocol, boolean usePolarMoment, FileFormat format)
          Creates a new suite from the specified files.
 
Method Summary
 void calculateAmsStatistics(java.util.List<Sample> samples, Suite.AmsCalcType calcType, java.lang.String scriptPath)
          Calculates and stores AMS statistics using an external script.
static SuiteCalcs calculateMultiSuiteMeans(java.util.List<Suite> suites)
          Calculates and returns Fisher statistics on all the calculated PCA directions for samples within supplied suite.
 void calculateSiteFishers(Correction correction)
          For each site in this suite, calculates Fisher statistics on the sample PCA directions.
 void calculateSuiteMeans()
          Calculates Fisher statistics on all the calculated PCA directions for samples within the suite.
 void clearAmsCalculations()
          Clears any AMS calculations on this suite
 boolean containsSample(java.lang.String id)
          Determine whether this suite contain a same with a specified identifier (name).
 void doAllCalculations(Correction correction)
          Performs all possible sample and site calculations.
static java.util.List<FisherValues> doReversalTest(java.util.List<Suite> suites)
          Performs a reversal test on a list of suites.
 void doSampleCalculations(Correction correction)
          Performs calculations for each sample in this suite.
 void doSiteCalculations(Correction correction)
          Calculate mean directions for all suitable sites in the suite.
 void exportToFiles(java.io.File directory, java.util.List<DatumField> fields)
          Exports a subset of this suite's data to multiple files, one file per sample.
 void fromString(java.lang.String string)
          Sets suite data from a string.
 java.util.List<KentParams> getAmsBootstrapParams()
          Returns the parameters of the last AMS bootstrap statistics (if any) calculated on this suite's data.
 java.util.List<KentParams> getAmsHextParams()
          Returns the parameters of the last AMS Hext statistics (if any) calculated on this suite's data.
 Sample getCurrentSample()
          Returns the current sample
 int getCurrentSampleIndex()
          Returns the index defining the current sample.
 CustomFields<java.lang.String> getCustomFlagNames()
          Returns the names (titles) of the custom flags for this suite.
 CustomFields<java.lang.String> getCustomNoteNames()
          Returns the names (titles) of the custom notes for this suite.
 java.util.List<Datum> getData()
          Returns all the data points in this suite.
 int getIndexBySample(Sample sample)
          Returns the index of a specified sample within this suite.
 java.util.List<java.lang.String> getLoadWarnings()
          Get the list of warnings produced when data was being loaded from one or more files.
 double getMaxDepth()
          For a continuous suite, returns the maximum depth of a sample within the suite.
 MeasType getMeasType()
          Returns the measurement type of this suite (discrete or continuous)
 double getMinDepth()
          For a continuous suite, returns the minimum depth of a sample within the suite.
 java.lang.String getName()
          Returns the name of this suite.
 int getNumSamples()
          Returns the number of samples in this suite.
 java.io.File getPuffinFile()
          Returns the name of the PuffinPlot file associated with this suite, if any.
 Sample getSampleByIndex(int i)
          Returns the sample with the specified index.
 Sample getSampleByName(java.lang.String name)
          Returns a sample from this suite with the specified name, or null if no such sample exists.
 java.util.List<Sample> getSamples()
          Returns all the samples in this suite.
 Site getSiteByName(java.lang.String siteName)
          Returns a site with the given name, or null if this suite contains no such site.
 java.util.List<FisherValues> getSiteFishers()
          Returns the results of the per-site Fisher statistics calculated by calculateSiteFishers(net.talvi.puffinplot.data.Correction).
 java.util.List<Site> getSites()
          Returns the sites within this suite.
 SuiteCalcs getSuiteMeans()
          Returns the Fisher parameters calculated on the entire suite.
 Datum getTrayCorrection(Datum d)
          Returns the tray correction for the specified data point.
 void importAmsFromAsc(java.util.List<java.io.File> files, boolean magneticNorth)
          Imports AMS data from ASC files in the format produced by Agico's SAFYR program.
 void importAmsFromDelimitedFile(java.util.List<java.io.File> files, boolean directions)
          Imports AMS data from a whitespace-delimited file.
 boolean isFilenameSet()
          Reports whether a default PuffinPlot file is set for this suite.
 void rescaleMagSus(double factor)
          Multiplies all magnetic susceptibility measurements in this suite by the specified factor.
 void save()
          If a default PuffinPlot file is set for this suite, saves the suite data to that file.
 void saveAs(java.io.File file)
          Saves the data in this suite to a specified file.
 void saveCalcsSample(java.io.File file)
          Exports sample calculations to a specified file in CSV format.
 void saveCalcsSite(java.io.File file)
          Exports site calculations to a specified file in CSV format.
 void saveCalcsSuite(java.io.File file)
          Saves the Fisher mean direction for the whole suite to a file in CSV format
 void setCurrentSampleIndex(int value)
          Sets the index defining the current sample.
 void setNamedSiteForSamples(java.util.Collection<Sample> samples, java.lang.String siteName)
          Explicitly sets a site for the specified samples.
 void setSiteNamesByDepth(java.util.Collection<Sample> samples, double thickness)
          Sets site names for a continuous suite according to the depth of the samples.
 void setSiteNamesBySubstring(java.util.Collection<Sample> samples, java.util.BitSet charMask)
          Sets site names for samples according to chosen characters from the sample names.
 void setSitesForSamples(java.util.Collection<Sample> samples, Suite.SiteNamer siteNamer)
          Sets sites for supplied samples according to a supplied site namer.
 java.lang.String toString()
          Returns the name of this suite.
 java.util.List<java.lang.String> toStrings()
          Returns strings representing data about this suite.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Suite

public Suite(java.util.List<java.io.File> files)
      throws java.io.IOException

Creates a new suite from the specified files. The is a convenience method for Suite(List, SensorLengths, TwoGeeLoader.Protocol) using the default sensor lengths (1, 1, 1), protocol (NORMAL), and Cartesian (X/Y/Z) magnetic moment fields.

Parameters:
files - the files from which to load the data
Throws:
java.io.IOException - if an I/O error occurred while reading the files

Suite

public Suite(java.util.List<java.io.File> files,
             SensorLengths sensorLengths,
             TwoGeeLoader.Protocol protocol,
             boolean usePolarMoment,
             FileFormat format)
      throws java.io.IOException

Creates a new suite from the specified files.

Note that this may return an empty suite, in which case it is the caller's responsibility to notice this and deal with it. We can't just throw an exception if the suite's empty, because then we lose the load warnings (which will probably explain to the user why the suite's empty and are thus quite important).

Parameters:
files - the files from which to load the data
sensorLengths - for 2G long core files only: the effective lengths of the magnetometer's SQUID sensors, used to correct Cartesian magnetic moment data
protocol - for 2G files only: the measurement protocol used
usePolarMoment - for 2G files only: use polar (dec/inc/int) data fields instead of Cartesian ones (X/Y/Z) to determine magnetic moment
format - explicitly specified file format (null to automatically guess between 2G, PuffinPlot, and Zplot).
Throws:
java.io.IOException - if an I/O error occurred while reading the files
Method Detail

getLoadWarnings

public java.util.List<java.lang.String> getLoadWarnings()
Get the list of warnings produced when data was being loaded from one or more files.

Returns:
the list of warnings produced when data was being loaded from one or more files

calculateSuiteMeans

public void calculateSuiteMeans()
Calculates Fisher statistics on all the calculated PCA directions for samples within the suite. The Fisher parameters are stored in the suite and can be retrieved with getSuiteMeans().


calculateMultiSuiteMeans

public static SuiteCalcs calculateMultiSuiteMeans(java.util.List<Suite> suites)
Calculates and returns Fisher statistics on all the calculated PCA directions for samples within supplied suite. The Fisher parameters are stored in the suite and can be retrieved with getSuiteMeans().

Parameters:
suites - the suites on which to calculate statistics
Returns:
the results of the calculation

doReversalTest

public static java.util.List<FisherValues> doReversalTest(java.util.List<Suite> suites)
Performs a reversal test on a list of suites.

Parameters:
suites - the suites on which to perform the test.
Returns:
a two-item list containing Fisher statistics for the normal and reversed modes of the data in the suites, in that order

getSuiteMeans

public SuiteCalcs getSuiteMeans()
Returns the Fisher parameters calculated on the entire suite.

Returns:
the Fisher parameters calculated on the entire suite

calculateSiteFishers

public void calculateSiteFishers(Correction correction)
For each site in this suite, calculates Fisher statistics on the sample PCA directions.

Parameters:
correction - the correction to apply to the magnetic moment measurements when performing the PCA calculations
See Also:
getSiteFishers(), Site.doFisher(net.talvi.puffinplot.data.Correction)

getSiteFishers

public java.util.List<FisherValues> getSiteFishers()
Returns the results of the per-site Fisher statistics calculated by calculateSiteFishers(net.talvi.puffinplot.data.Correction).

Returns:
the results of previously calculated per-site Fisher statistics

isFilenameSet

public boolean isFilenameSet()
Reports whether a default PuffinPlot file is set for this suite.

Returns:
true if a default PuffinPlot file is set for this suite

save

public void save()
          throws PuffinUserException
If a default PuffinPlot file is set for this suite, saves the suite data to that file. If not, does nothing.

Throws:
PuffinUserException - if an error occurred while saving the data

saveAs

public void saveAs(java.io.File file)
            throws PuffinUserException
Saves the data in this suite to a specified file. The specified file is also set as the default PuffinPlot file for this suite.

Parameters:
file - the file to which to save the suite's data
Throws:
PuffinUserException - if an error occurred while saving data

doSampleCalculations

public void doSampleCalculations(Correction correction)
Performs calculations for each sample in this suite. For each sample, PCA and a great-circle fit are done, provided in each case that the sample contains data points which are flagged to be used for the calculation in question. The magnetic susceptibility jump temperature is also calculated.

Parameters:
correction - the correction to apply to the magnetic moment data when performing the calculations

doSiteCalculations

public void doSiteCalculations(Correction correction)
Calculate mean directions for all suitable sites in the suite. For each site, a Fisher mean and a great-circle mean may be calculated. The Fisher mean is only calculated for sites with a sufficient number of PCA directions for samples. The great-circle mean is only calculated for sites with a sufficient number of great circles fitted to samples.

Parameters:
correction - the correction to apply to the magnetic moment data when performing the calculations

doAllCalculations

public void doAllCalculations(Correction correction)
Performs all possible sample and site calculations. Intended to be called after instantiating a new Suite from a file.

Parameters:
correction - the correction to apply to the magnetic moment data when performing the calculations

saveCalcsSample

public void saveCalcsSample(java.io.File file)
                     throws PuffinUserException
Exports sample calculations to a specified file in CSV format.

Parameters:
file - the file to which to write the sample calculations
Throws:
PuffinUserException - if an error occurred while writing the file

saveCalcsSite

public void saveCalcsSite(java.io.File file)
                   throws PuffinUserException
Exports site calculations to a specified file in CSV format.

Parameters:
file - the file to which to write the site calculations
Throws:
PuffinUserException - if an error occurred while writing the file

saveCalcsSuite

public void saveCalcsSuite(java.io.File file)
                    throws PuffinUserException
Saves the Fisher mean direction for the whole suite to a file in CSV format

Parameters:
file - the file to which to write the mean direction
Throws:
PuffinUserException - if an error occurred while writing the file

getSampleByName

public Sample getSampleByName(java.lang.String name)
Returns a sample from this suite with the specified name, or null if no such sample exists.

Parameters:
name - a sample name
Returns:
a sample from this suite with the specified name, or null if no such sample exists

getCurrentSampleIndex

public int getCurrentSampleIndex()
Returns the index defining the current sample.

Returns:
the index defining the current sample

setCurrentSampleIndex

public void setCurrentSampleIndex(int value)
Sets the index defining the current sample.

Parameters:
value - the index defining the current sample

getCurrentSample

public Sample getCurrentSample()
Returns the current sample

Returns:
the current sample

getSamples

public java.util.List<Sample> getSamples()
Returns all the samples in this suite.

Returns:
all the samples in this suite

getData

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

Returns:
all the data points in this suite

getMeasType

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

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

getName

public java.lang.String getName()
Returns the name of this suite.

Returns:
the name of this suite

getNumSamples

public int getNumSamples()
Returns the number of samples in this suite.

Returns:
the number of samples in this suite

getSampleByIndex

public Sample getSampleByIndex(int i)
Returns the sample with the specified index.

Parameters:
i - an index number for a sample
Returns:
the sample with the specified index

getIndexBySample

public int getIndexBySample(Sample sample)
Returns the index of a specified sample within this suite.

Parameters:
sample - a sample in the suite
Returns:
the index of the sample, or -1 if not in this suite

getTrayCorrection

public Datum getTrayCorrection(Datum d)
Returns the tray correction for the specified data point. Not currently used.

Parameters:
d - a data point representing a magnetic measurement
Returns:
a data point containing the magnetic moment of the section of the tray on which the measurement was made

toString

public java.lang.String toString()
Returns the name of this suite.

Overrides:
toString in class java.lang.Object
Returns:
the name of this suite

toStrings

public java.util.List<java.lang.String> toStrings()
Returns strings representing data about this suite. Note that this does not include data at the level of sites, samples, or treatment steps.

Returns:
strings representing data about this suite

fromString

public void fromString(java.lang.String string)
Sets suite data from a string. The string must be in the format of one of the strings produced by the toStrings() method.

Parameters:
string - a string from which to read suite data

importAmsFromDelimitedFile

public void importAmsFromDelimitedFile(java.util.List<java.io.File> files,
                                       boolean directions)
                                throws java.io.IOException

Imports AMS data from a whitespace-delimited file. If directions==false, line format is k11 k22 k33 k12 k23 k13 (tensor components) otherwise it's inc1 dec1 inc2 dec2 inc3 dec3 (axis directions, decreasing magnitude). If there's no sample in the suite from which to take the sample and formation corrections, importAmsWithDialog will try to read them as fields appended to the end of the line.

Not currently used in PuffinPlot.

Parameters:
files - the files from which to read the data
directions - true to read axis directions, false to read tensor components
Throws:
java.io.IOException - if there was an I/O error reading the files

importAmsFromAsc

public void importAmsFromAsc(java.util.List<java.io.File> files,
                             boolean magneticNorth)
                      throws java.io.IOException
Imports AMS data from ASC files in the format produced by Agico's SAFYR program.

Parameters:
files - the ASC files to read
magneticNorth - true if the sample dip azimuths in the file are relative to magnetic north; false if they are relative to geographic north
Throws:
java.io.IOException - if an I/O error occurred while reading the file

exportToFiles

public void exportToFiles(java.io.File directory,
                          java.util.List<DatumField> fields)
Exports a subset of this suite's data to multiple files, one file per sample. The files are in a tab-delimited text format.

Parameters:
directory - the directory in which to create the files
fields - the fields to export

getCustomFlagNames

public CustomFields<java.lang.String> getCustomFlagNames()
Returns the names (titles) of the custom flags for this suite.

Returns:
the names (titles) of the custom flags for this suite

getCustomNoteNames

public CustomFields<java.lang.String> getCustomNoteNames()
Returns the names (titles) of the custom notes for this suite.

Returns:
the names (titles) of the custom notes for this suite

getAmsBootstrapParams

public java.util.List<KentParams> getAmsBootstrapParams()
Returns the parameters of the last AMS bootstrap statistics (if any) calculated on this suite's data.

Returns:
the parameters of the last AMS bootstrap statistics (if any) calculated on this suite's data

getAmsHextParams

public java.util.List<KentParams> getAmsHextParams()
Returns the parameters of the last AMS Hext statistics (if any) calculated on this suite's data.

Returns:
the parameters of the last AMS Hext statistics (if any) calculated on this suite's data

clearAmsCalculations

public void clearAmsCalculations()
Clears any AMS calculations on this suite


getSites

public java.util.List<Site> getSites()
Returns the sites within this suite.

Returns:
the sites within this suite

getSiteByName

public Site getSiteByName(java.lang.String siteName)
Returns a site with the given name, or null if this suite contains no such site.

Parameters:
siteName - a site name
Returns:
a site with the given name, or null if this suite contains no such site

getPuffinFile

public java.io.File getPuffinFile()
Returns the name of the PuffinPlot file associated with this suite, if any.

Returns:
the name of the PuffinPlot file associated with this suite, if any

calculateAmsStatistics

public void calculateAmsStatistics(java.util.List<Sample> samples,
                                   Suite.AmsCalcType calcType,
                                   java.lang.String scriptPath)
                            throws java.io.IOException,
                                   java.lang.IllegalArgumentException
Calculates and stores AMS statistics using an external script.

Parameters:
samples - the samples on which to calculate statistics
calcType - the type of AMS calculation to perform
scriptPath - the filesystem path of the script which will perform the calculation
Throws:
java.io.IOException - if there was an error running the script or reading its output
java.lang.IllegalArgumentException - if the samples contain insufficient AMS data

getMinDepth

public double getMinDepth()
For a continuous suite, returns the minimum depth of a sample within the suite.

Returns:
the minimum depth of a sample within the suite

getMaxDepth

public double getMaxDepth()
For a continuous suite, returns the maximum depth of a sample within the suite.

Returns:
the maximum depth of a sample within the suite

setSitesForSamples

public void setSitesForSamples(java.util.Collection<Sample> samples,
                               Suite.SiteNamer siteNamer)
Sets sites for supplied samples according to a supplied site namer. Where a site with the required name exists, it will be used; otherwise a new site with the required name will be created.

Parameters:
samples - the samples for which to set sites
siteNamer - the site namer which will produce the site names

setNamedSiteForSamples

public void setNamedSiteForSamples(java.util.Collection<Sample> samples,
                                   java.lang.String siteName)
Explicitly sets a site for the specified samples. If a site with the requested name exists, it will be used; otherwise a new site with that name will be created.

Parameters:
samples - the samples for which to set the site
siteName - the name of the site into which to put the samples

setSiteNamesBySubstring

public void setSiteNamesBySubstring(java.util.Collection<Sample> samples,
                                    java.util.BitSet charMask)
Sets site names for samples according to chosen characters from the sample names. The caller supplies a bit-set; for each sample name, the site name is determined by taking the characters of the sample name for which the corresponding bit is set.

Parameters:
samples - the samples for which to set sites
charMask - the mask determining which characters to use for the site name

setSiteNamesByDepth

public void setSiteNamesByDepth(java.util.Collection<Sample> samples,
                                double thickness)
Sets site names for a continuous suite according to the depth of the samples. A thickness is specified to the method, and the suite is divided into sites of that thickness. Each site is named for the shallowest depth within it.

Parameters:
samples - the samples for which to set site names
thickness - the thickness of each site

containsSample

public boolean containsSample(java.lang.String id)
Determine whether this suite contain a same with a specified identifier (name).

Parameters:
id - a sample identifier
Returns:
true if this suite contains a sample with the specified identifier

rescaleMagSus

public void rescaleMagSus(double factor)
Multiplies all magnetic susceptibility measurements in this suite by the specified factor.

Parameters:
factor - a factor by which to multiply all the magnetic susceptibility measurements in this suite