acquifer.core

Class Dataset

Object

acquifer.core.Dataset

Direct Known Subclasses:

Dataset, ImageSeries, PlatePlane

public class Dataset
extends Object

A Dataset represent a view of an IM dataset directory. It is a collection of ImagePlane, where each ImagePlane corresponds to an image of the directory.
It is assumed that all ImagePlane of the Dataset have the same width x height dimensions, however these dimensions are not known (requires to read the tiff header).
Dimensions filters can be used to include only some images of the IM directory.If no image matches the dimension filters then an error is thrown (i.e would yield an empty dataset).
The list of images matching the selected dimensions, and the unique values for each dimensions are computed at the creation of the Dataset. These values are stored as attributes and can be accessed via getter methods.
A Dataset instance is not expected to contain any null reference.

The list of images in the dataset can also be sorted following a custom order at the creation of the Dataset.
The list of ImagePlane[] contains in the dataset is available as a public field.
Any modification of this list directly impact the dataset.
For more safety, one can get a copy of the list of images in the dataset, with a custom sorting order using getListOfImagePlanes.

The preferred approach to create a Dataset is to use the corresponding DatasetBuilder.build() method, although new Dataset(datasetBuilder) also works.
The DatasetBuilder acts as an intermediate to carry the Dataset constructor parameters, which include many optional parameters. It thus uses the Builder pattern recommended in "Effective Java" by Joshua Bloch (Item 2), except that the Builder is here not a subclass of Dataset, which is simpler.

Field Summary

Fields

Modifier and Type	Field and Description
ImagePlane[]	listImages List of ImagePlanes, no specific order is assumed, unless a sort order was specified in the dataset constructor.

Constructor Summary

Constructors

Constructor and Description
Dataset(DatasetBuilder builder) Construct a finalised Dataset from a pre-configured DatasetBuilder. This constructor is used by DatasetBuilder.build, which offer more flexibility when defining dimensions filters.
Dataset(ImagePlane[] listImagePlanes, Comparator<ImagePlane> sortOrder) Create a Dataset from a list of ImagePlanes.
Dataset(String path, MetadataParser metadataParser, FilenameFilter filenameFilter) Create a dataset from a directory, taking all images in the directory.

Method Summary

Modifier and Type	Method and Description
File	getDirectory() Return the File object for the directory.
String	getDirectoryName() Return the name of the directory associated to this dataset.
String	getDirectoryPath() Return the path to the Dataset directory as a string.
ImagePlane	getImagePlane(int index) Return the ImagePlane at a given position index (0-based).
ImagePlane[]	getListOfImagePlanes() Return the list of images in this Dataset.
ImagePlane[]	getListOfImagePlanes(Comparator<ImagePlane> sortOrder) Return the list of images in this Dataset.
int	getNumberOfChannels() Return the expected number of channels for each well/subposition of this dataset.
int	getNumberOfExistingImagePlanes() Return the total number of images planes in the dataset.
int	getNumberOfImageSeries() Return the number of ImageSeries (hyperstacks) in this dataset.
int	getNumberOfPlanesPerSeries() Return the expected number of planes per ImageSeries (hyperstack).
int	getNumberOfSubpositions() Return the expected number of subpositions for each well in this dataset.
int	getNumberOfTimepoints() Return the expected number of timepoints for each well/subposition of this dataset.
int	getNumberOfWells() Return the number of unique wells in this dataset.
int	getNumberOfZslices() Return the expected number of Z-slices for each well/subposition of this dataset.
Set<Integer>	getSetChannels() Return the set of channels present in this dataset.
Set<Integer>	getSetPlateColumns() Return the set of plate columns present in this dataset (starting with column 1).
Set<Character>	getSetPlateRows() Return the set of plate rows present in this dataset.
Set<Integer>	getSetSubpositions() Return the set of well-subpositions present in this dataset.
Set<Integer>	getSetTimepoints() Return the set of timepoints present in this dataset.
Set<Well>	getSetWells() Return the set of wells present in this dataset.
Set<Integer>	getSetZ() Return the set of Z-slices present in this dataset.
Comparator<ImagePlane>	getSortOrder()
ImageSeries[]	groupByImageSeries() Group images belonging to the same well and subposition into ImageSeries (ie belonging to the same multi-dimensional image-sequence).
String	toString()

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

listImages

public final ImagePlane[] listImages

List of ImagePlanes, no specific order is assumed, unless a sort order was specified in the dataset constructor.
The list is expected to contain no null reference.
Any modification of this list directly impacts the dataset, a copy of this list can be obtained using getListOfImagePlanes(Comparator)

Constructor Detail

Dataset

public Dataset(String path,
               MetadataParser metadataParser,
               FilenameFilter filenameFilter)
        throws InstantiationException,
               IOException

Create a dataset from a directory, taking all images in the directory.

Throws:

InstantiationException

IOException - if directory does not exist or is not a directory

Dataset

public Dataset(DatasetBuilder builder)
        throws InstantiationException

Construct a finalised Dataset from a pre-configured DatasetBuilder.
This constructor is used by DatasetBuilder.build, which offer more flexibility when defining dimensions filters.

Throws:

IllegalArgumentException - if no images match the selected dimensions.

InstantiationException

Dataset

public Dataset(ImagePlane[] listImagePlanes,
               Comparator<ImagePlane> sortOrder)

Create a Dataset from a list of ImagePlanes.
The image file represented by the ImagePlanes must reside in the same directory.
The constructor computes the available dimensions from the list of images and sort the list of images if sortOrder is not null.

Parameters:

sortOrder - can be null

Throws:

IllegalArgumentException - if an empty or 0-length list is passed to the constructor.

Method Detail

toString

public String toString()

Overrides:

toString in class Object

getDirectoryName

public String getDirectoryName()

Return the name of the directory associated to this dataset.

getDirectory

public File getDirectory()

Return the File object for the directory.

getDirectoryPath

public String getDirectoryPath()

Return the path to the Dataset directory as a string.

getListOfImagePlanes

public ImagePlane[] getListOfImagePlanes()

Return the list of images in this Dataset.
This list is expected to contain no null references.
If some fileFilter were used at the dataset creation, then the list may represent only a fraction of the files present in the directory associated to the Dataset.
The returned array is a deep-copy of the dataset attribute, ie changes to the returned array or to the contained objects do not modify the original array.

getListOfImagePlanes

public ImagePlane[] getListOfImagePlanes(Comparator<ImagePlane> sortOrder)

Return the list of images in this Dataset.
This list is expected to contain no null references.
If some fileFilter were used at the dataset creation, then the list may represent only a fraction of the files present in the directory associated to the Dataset.
The returned array is a copy of the dataset attribute, ie changes to the returned array will not modify the original array.
Changes to the ImagePlane would be reflected, but ImagePlane are immutable so this should not happen.

Parameters:

sortOrder - optional order to sort the list of images. Impact only the returned list of images, not the list stored in the Dataset. Can be null.

getImagePlane

public ImagePlane getImagePlane(int index)

Return the ImagePlane at a given position index (0-based).

getSetWells

public Set<Well> getSetWells()

Return the set of wells present in this dataset.
The set is a copy of the Dataset attribute, ie changes to the returned set are not impacting the original set.

getSetPlateRows

public Set<Character> getSetPlateRows()

Return the set of plate rows present in this dataset.
Plate rows are represented by a character ex: 'A'.
The set is a copy of the Dataset attribute, ie changes to the returned set are not impacting the original set.

getSetPlateColumns

public Set<Integer> getSetPlateColumns()

Return the set of plate columns present in this dataset (starting with column 1).
The set is a copy of the Dataset attribute, ie changes to the returned set are not impacting the original set.

getSetSubpositions

public Set<Integer> getSetSubpositions()

Return the set of well-subpositions present in this dataset.
The set is a copy of the Dataset attribute, ie changes to the returned set are not impacting the original set.

getSetChannels

public Set<Integer> getSetChannels()

Return the set of channels present in this dataset.
The set is a copy of the Dataset attribute, ie changes to the returned set are not impacting the original set.

getSetZ

public Set<Integer> getSetZ()

Return the set of Z-slices present in this dataset.
The set is a copy of the Dataset attribute, ie changes to the returned set are not impacting the original set.

getSetTimepoints

public Set<Integer> getSetTimepoints()

Return the set of timepoints present in this dataset.
The set is a copy of the Dataset attribute, ie changes to the returned set are not impacting the original set.

getSortOrder

public Comparator<ImagePlane> getSortOrder()

getNumberOfExistingImagePlanes

public int getNumberOfExistingImagePlanes()

Return the total number of images planes in the dataset.
This returns the length of the internal list of images, and thus does not count timepoints/z-slices or channel for which an ImagePlane could be missing.
See getNumberOfPlanesPerSeries() to count potentially missing planes and get the number of planes for the resulting hyperstacks.

getNumberOfWells

public int getNumberOfWells()

Return the number of unique wells in this dataset.

getNumberOfSubpositions

public int getNumberOfSubpositions()

Return the expected number of subpositions for each well in this dataset.
Most of the time, all wells of the Dataset have the same number of subpositions but that might not always be the case.

getNumberOfChannels

public int getNumberOfChannels()

Return the expected number of channels for each well/subposition of this dataset.
Most of the time, all wells of the Dataset have the same number of channels but that might not always be the case.

getNumberOfZslices

public int getNumberOfZslices()

Return the expected number of Z-slices for each well/subposition of this dataset. Most of the time, all wells of the Dataset have the same number of Z-slices but that might not always be the case.

getNumberOfTimepoints

public int getNumberOfTimepoints()

Return the expected number of timepoints for each well/subposition of this dataset. Most of the time, all wells of the Dataset have the same number of timepoints but that might not always be the case.

getNumberOfImageSeries

public int getNumberOfImageSeries()

Return the number of ImageSeries (hyperstacks) in this dataset.

getNumberOfPlanesPerSeries

public int getNumberOfPlanesPerSeries()

Return the expected number of planes per ImageSeries (hyperstack).
Theoretical number of planes of the corresponding "complete" hyperstack, computed as nC x nZ x nT.
Potentially missing image files are counted, and just filled in with black planes when visualized as a hyperstack.
This number is expected to be the same for each well/subposition of the dataset but might change if individual image files were deleted.

groupByImageSeries

public ImageSeries[] groupByImageSeries()

Group images belonging to the same well and subposition into ImageSeries (ie belonging to the same multi-dimensional image-sequence).
The images in a series are sorted in the default czt order, suitable for visualisation as a hyperstack in ImageJ/Fiji.
All ImageSeries are expected to have the same number of planes (typically the case for IM dataset).
If there are less planes than expected, the resulting ImageSeries can contain null ImagePlane.