net.talvi.puffinplot.data

Class Suite

java.lang.Object

net.talvi.puffinplot.data.Suite

All Implemented Interfaces:

SampleGroup

public final class Suite
extends java.lang.Object
implements SampleGroup

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

Nested Classes

Modifier and Type	Class and Description
class	Suite.MissingSampleNameException This exception indicates that a supplied argument did not contain an expected sample name.
static interface	Suite.SavedListener A listener interface for modifications to the Suite's save state.
static interface	Suite.SiteNamer A SiteNamer turns a sample name into a site name.

Constructor Summary

Constructors

Constructor and Description
Suite(java.lang.String creator) Creates a new, empty suite.

Method Summary

Modifier and Type	Method and Description
void	addSavedListener(Suite.SavedListener savedListener) Add a listener for the Suite's save state
void	addTreatmentStep(TreatmentStep step) Adds a datum to the suite.
void	alignSectionDeclinations(int margin, double targetDeclination, CoreSections.TargetDeclinationType targetType) Align the declinations of core sections in this suite.It is assumed that the suite is continuous; the discrete IDs of samples are interpreted as core section identifiers.
boolean	areSectionEndDirectionsDefined(int margin) Report whether samples near the ends of core sections have an associated direction, e.g. a sample direction calculated by PCA.
void	calculateAmsStatistics(java.util.List<Sample> samples, AmsCalculationType 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 suites.
void	calculateSiteFishers(Correction correction) For each site in this suite, calculates Fisher statistics on the sample PCA directions.
void	calculateSuiteMeans(java.util.List<Sample> selSamples, java.util.List<Site> selSites) Calculates Fisher statistics on all the calculated PCA directions for samples within the suite.
void	clearAmsCalculations() Clears any AMS calculations on this suite
void	clearSites(java.util.Collection<Sample> samples) Clears sites for specified samples within this suite.
boolean	containsSample(java.lang.String id) Determine whether this suite contain a same with a specified identifier (name).
void	convertDiscreteToContinuous(java.io.File file) Converts a discrete suite to a continuous suite, using a file to provide the mapping from sample names to depths.
void	convertDiscreteToContinuous(java.util.Map<java.lang.String,java.lang.String> nameToDepth) Converts this suite from a discrete suite to a continuous suite using a supplied mapping from sample names to depths.
void	doAllCalculations(Correction correction, java.lang.String greatCirclesValidityCondition) 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, java.lang.String greatCirclesValidityCondition) Calculates mean directions for all suitable sites in the suite.
void	exportToFiles(java.io.File directory, java.util.List<TreatmentParameter> 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.
java.lang.String	getCreator() Returns a string identifying the program and version which created this suite.
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.
int	getIndexBySample(Sample sample) Returns the index of a specified sample within this suite.
double	getMaxDepth() For a continuous suite, returns the maximum depth of a sample within the suite.
MeasurementType	getMeasurementType() 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.
java.util.List<Sample>	getSamplesByDiscreteId(java.lang.String id) Return the samples with a given discrete ID.
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.
void	importAmsFromAsc(java.util.List<java.io.File> files, boolean magneticNorth, boolean overwriteSampleCorrection, boolean overwriteFormationCorrection) Imports AMS data from ASC files in the format produced by Agico's SAFYR and SUSAR programs.
void	importAmsFromDelimitedFile(java.util.List<java.io.File> files, boolean directions) Imports AMS data from a whitespace-delimited file.
void	importLocations(java.io.File file) Imports site locations from a CSV file.
boolean	isEmpty() Determines whether this suite is empty.
boolean	isFilenameSet() Reports whether a default PuffinPlot file is set for this suite.
boolean	isSaved()
void	mergeDuplicateSamples(java.util.Collection<Sample> samples) Within the supplied collection of samples, any two or more samples which have the same depth or discrete ID will be merged into a single sample.
void	mergeDuplicateTreatmentSteps(java.util.Collection<Sample> samplesToMerge) Within each of the supplied samples, merges any TreatmentStep objects which have the same treatment type and treatment level.
java.util.List<java.lang.String>	readDirectionalData(java.util.Collection<java.io.File> files) Reads sample direction data from text files.Text files should have no header lines.
java.util.List<java.lang.String>	readFiles(java.util.List<java.io.File> files) Convenience method for reading PuffinPlot files.This method is a wrapper for the fully specified method readFiles(List, FileType, Map) which provides defaults for all the arguments except for the list of file names.
java.util.List<java.lang.String>	readFiles(java.util.List<java.io.File> files, FileType fileType, java.util.Map<java.lang.String,java.lang.Object> importOptions) Reads data into this suite from the specified files.
void	removeSamples(java.util.Collection<Sample> samplesToRemove) Removes the specified samples from this suite.
void	removeSamplesByTreatmentType(java.util.Collection<Sample> removableSamples, TreatmentType treatmentType) For every sample in the supplied collection: remove the sample from this suite if any of its treatment steps has the specified treatment type.
void	removeSamplesOutsideDepthRange(double minDepth, double maxDepth) Retains the samples between the specified depths in the suite, and removes all samples outside this range.
void	removeSavedListener(Suite.SavedListener savedListener) Remove a listener for the Suite's save state
void	rescaleMagSus(double factor) Multiplies all magnetic susceptibility measurements in this suite by the specified factor.
void	rotateSamplesByDiscreteId(java.util.Map<java.lang.String,java.lang.Double> rotations) Rotate the declination of magnetic moment data in this suite according to the discrete ID of the sample.
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	setSaved(boolean saved) Sets this suite's "saved" flag, which records whether the suite has been saved since its last modification.
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.
void	sortSamplesByDepth() Sorts this suite's samples in ascending order of depth
java.lang.String	toString() Returns the name of this suite.
java.util.List<java.lang.String>	toStrings() Returns strings representing data about this suite.
void	updateReverseIndex() Update this suit's internal index mapping samples to their indices within the suite.

Methods inherited from class java.lang.Object

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

Constructor Detail

Suite

public Suite(java.lang.String creator)

Creates a new, empty suite.

Parameters:

creator - a string identifying the program and version creating the suite

Method Detail

updateReverseIndex

public void updateReverseIndex()

Update this suit's internal index mapping samples to their indices within the suite. This method is only public to make it usable from testing code when constructing artificial suites; normal users of the Suite API do not need to call it explicitly.

calculateSuiteMeans

public void calculateSuiteMeans(java.util.List<Sample> selSamples,
                                java.util.List<Site> selSites)

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

Parameters:

selSamples - samples for which to calculate means

selSites - sites for which to calculate means

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

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.calculateFisherStats(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

addTreatmentStep

public void addTreatmentStep(TreatmentStep step)

Adds a datum to the suite. If no corresponding sample exists, one is created. The measurement type of the datum must be compatible with that of the suite -- that is, either they must be the same, or the suite's measurement type must be UNSET. In the latter case, the suite's measurement type will be set to that of the supplied datum.

Parameters:

step - the datum to add

Throws:

java.lang.IllegalArgumentException - if d is null, or if the measurement type of is invalid (i.e. it is null, UNSET, or incompatible with this suite's measurement type)

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,
                               java.lang.String greatCirclesValidityCondition)

Calculates 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

greatCirclesValidityCondition - an expression which is evaluated to determine whether a great-circles direction is considered valid (see GreatCircles.instance(java.util.List, java.util.List, java.lang.String)).

readFiles

public java.util.List<java.lang.String> readFiles(java.util.List<java.io.File> files)
                                           throws java.io.IOException

Convenience method for reading PuffinPlot files.This method is a wrapper for the fully specified method readFiles(List, FileType, Map) which provides defaults for all the arguments except for the list of file names.

The filetype is set to PUFFINPLOT_NEW.

Parameters:

files - files to read

Returns:

a (possibly empty) list of messages generated during loading

Throws:

java.io.IOException - if an exception occurs during file reading

readFiles

public java.util.List<java.lang.String> readFiles(java.util.List<java.io.File> files,
                                                  FileType fileType,
                                                  java.util.Map<java.lang.String,java.lang.Object> importOptions)
                                           throws java.io.IOException

Reads data into this suite from the specified files. After readFiles returns, #getLoadWarnings() can be used to return a list of problems that occurred during file reading.

Parameters:

files - the files from which to read the data (non-null, non-empty)

fileType - type of the specified files

importOptions - extra options passed to file importers

Returns:

a (possibly empty) list of messages generated during loading

Throws:

java.io.IOException - if an I/O error occurred while reading the files

isEmpty

public boolean isEmpty()

Determines whether this suite is empty. An empty suite is one that contains no demagnetization data.

Returns:

true iff this suite is empty

readDirectionalData

public java.util.List<java.lang.String> readDirectionalData(java.util.Collection<java.io.File> files)
                                                     throws java.io.IOException

Reads sample direction data from text files.Text files should have no header lines. Columns should be separated by commas, spaces, or tabs. Column 1 is sample name, column 2 is declination in degrees, column 3 is inclination in degrees.

Parameters:

files - files from which to read

Returns:

a (possibly empty) list of messages generated during loading

Throws:

java.io.IOException - if an error occurred while reading the files

doAllCalculations

public void doAllCalculations(Correction correction,
                              java.lang.String greatCirclesValidityCondition)

Performs all possible sample and site calculations. Intended to be called after loading suite data from a file.

Parameters:

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

greatCirclesValidityCondition - an expression which is evaluated to determine whether a great-circles direction is considered valid (see GreatCircles.instance(java.util.List, java.util.List, java.lang.String)).

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.

Specified by:

getSamples in interface SampleGroup

Returns:

all the samples in this suite

getMeasurementType

public MeasurementType getMeasurementType()

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. If the suite contains no samples, or the index is -1, returns null.

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

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

importLocations

public void importLocations(java.io.File file)
                     throws java.io.IOException

Imports site locations from a CSV file. File format: CSV, no header line. Column 1 contains the site name, column 2 the latitude (degrees north from equator, negative for southern hemisphere), and column 3 the longitude (degrees east of Greenwich).

Parameters:

file - the file from which to read site locations

Throws:

java.io.IOException - if an error occurred while reading the file

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 fully tested -- use with caution. Not currently accessible from the PuffinPlot GUI.

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,
                             boolean overwriteSampleCorrection,
                             boolean overwriteFormationCorrection)
                      throws java.io.IOException

Imports AMS data from ASC files in the format produced by Agico's SAFYR and SUSAR programs. Note that the overwriteSampleCorrection and overwriteFormationCorrection arguments only have an effect when importing into an existing sample; if a new sample is created for AMS data, the orientations in the ASC file will always be used.

Parameters:

files - the ASC files to read

magneticNorth - true if the sample and formation dip azimuths in the file are relative to magnetic north; false if they are relative to geographic north

overwriteSampleCorrection - If importing to an existing sample, overwrite the sample's sample correction with the values specified in the ASC file. Otherwise, retain the values already set for the sample.

overwriteFormationCorrection - If importing to an existing sample, overwrite the sample's formation correction with the values specified in the ASC file. Otherwise, retain the values already set for the sample.

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<TreatmentParameter> 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. If there are no sites, the returned list will be empty, but it will never be null.

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

isSaved

public boolean isSaved()

Returns:

true if the suite has not been modified since it was last saved

setSaved

public void setSaved(boolean saved)

Sets this suite's "saved" flag, which records whether the suite has been saved since its last modification. If this flag is false, the suite is "modified", and data would be lost by closing it without saving.

Parameters:

saved - the saved state to set

getCreator

public java.lang.String getCreator()

Returns a string identifying the program and version which created this suite.

Returns:

the creator

getSamplesByDiscreteId

public java.util.List<Sample> getSamplesByDiscreteId(java.lang.String id)

Return the samples with a given discrete ID. For discrete suites, there will usually be at most one sample with a given discrete ID. For continuous suites, an entire core section may be returned.

Parameters:

id - a discrete ID

Returns:

a list of the samples in this Suite with the specified ID

rotateSamplesByDiscreteId

public void rotateSamplesByDiscreteId(java.util.Map<java.lang.String,java.lang.Double> rotations)

Rotate the declination of magnetic moment data in this suite according to the discrete ID of the sample.

Parameters:

rotations - a map from discrete sample IDs to rotation angles (clockwise in degrees)

alignSectionDeclinations

public void alignSectionDeclinations(int margin,
                                     double targetDeclination,
                                     CoreSections.TargetDeclinationType targetType)

Align the declinations of core sections in this suite.It is assumed that the suite is continuous; the discrete IDs of samples are interpreted as core section identifiers.

Parameters:

margin - the number of samples to average at the end of each section to determine the declination

targetDeclination - the declination to which to align the core

targetType - the core declination to align with the target

See Also:

CoreSections.alignSections(int, double, net.talvi.puffinplot.data.CoreSections.TargetDeclinationType)

areSectionEndDirectionsDefined

public boolean areSectionEndDirectionsDefined(int margin)

Report whether samples near the ends of core sections have an associated direction, e.g. a sample direction calculated by PCA.

Parameters:

margin - the number of samples to regard as being "near" the end of a core section

Returns:

true if and only if all samples near the end of a core section have an associated direction

See Also:

CoreSections.areSectionEndDirectionsDefined(int)

mergeDuplicateTreatmentSteps

public void mergeDuplicateTreatmentSteps(java.util.Collection<Sample> samplesToMerge)

Within each of the supplied samples, merges any TreatmentStep objects which have the same treatment type and treatment level.

Parameters:

samplesToMerge - samples containing the TreatmentStep objects to merge (where possible)

mergeDuplicateSamples

public void mergeDuplicateSamples(java.util.Collection<Sample> samples)

Within the supplied collection of samples, any two or more samples which have the same depth or discrete ID will be merged into a single sample. The merged sample will contain all the distinct treatment steps from the union of the duplicate samples. If any of the individual merged samples contains any duplicate treatment steps, the duplicate treatment steps will also be merged. This should seldom be needed in practice since the suite creation and reading code doesn't create new samples with the same names/depths as existing ones. But the PuffinPlot application is forever acquiring new ways to edit suites and samples (and of course scripting the API can result in all sorts of weirdness), so this is a useful way to restore order in the event that a suite does get into a funny state.

Parameters:

samples - the collection of samples within which to merge duplicates

calculateAmsStatistics

public void calculateAmsStatistics(java.util.List<Sample> samples,
                                   AmsCalculationType 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

clearSites

public void clearSites(java.util.Collection<Sample> samples)

Clears sites for specified samples within this suite. The site for each specified sample will be set to null, and any sites with no associated samples will be removed from this suite's list of sites.

Parameters:

samples - samples for which to clear sites

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

sortSamplesByDepth

public void sortSamplesByDepth()

Sorts this suite's samples in ascending order of depth

removeSamplesOutsideDepthRange

public void removeSamplesOutsideDepthRange(double minDepth,
                                           double maxDepth)

Retains the samples between the specified depths in the suite, and removes all samples outside this range.

Parameters:

minDepth - Minimum depth of samples to retain

maxDepth - Maximum depth of samples to retain

removeSamplesByTreatmentType

public void removeSamplesByTreatmentType(java.util.Collection<Sample> removableSamples,
                                         TreatmentType treatmentType)

For every sample in the supplied collection: remove the sample from this suite if any of its treatment steps has the specified treatment type.

Parameters:

removableSamples - samples to consider for removal (must be within this suite)

treatmentType - the treatment type that selects which samples should be removed.

removeSamples

public void removeSamples(java.util.Collection<Sample> samplesToRemove)

Removes the specified samples from this suite.

Parameters:

samplesToRemove - the samples to remove

convertDiscreteToContinuous

public void convertDiscreteToContinuous(java.util.Map<java.lang.String,java.lang.String> nameToDepth)
                                 throws Suite.MissingSampleNameException

Converts this suite from a discrete suite to a continuous suite using a supplied mapping from sample names to depths.

Parameters:

nameToDepth - a map containing a depth string for each sample name

Throws:

Suite.MissingSampleNameException - if the map does not contain all the sample names in this suite as keys

convertDiscreteToContinuous

public void convertDiscreteToContinuous(java.io.File file)
                                 throws java.io.IOException,
                                        Suite.MissingSampleNameException

Converts a discrete suite to a continuous suite, using a file to provide the mapping from sample names to depths.

Parameters:

file - a text file consisting of lines in the format <sample-name>,<sample-depth>

Throws:

java.io.IOException - if there was a problem reading the file

Suite.MissingSampleNameException - if there are samples in this suite which are not listed in the specified file

addSavedListener

public void addSavedListener(Suite.SavedListener savedListener)

Add a listener for the Suite's save state

Parameters:

savedListener - the new listener

removeSavedListener

public void removeSavedListener(Suite.SavedListener savedListener)

Remove a listener for the Suite's save state

Parameters:

savedListener - the listener to remove