def convertImagesToSeries(self, datapath, outputdirpath, dims=None, inputformat='stack',
dtype='int16', blocksize="150M", startidx=None, stopidx=None,
shuffle=False, overwrite=False):
"""
Write out Images data as Series data, saved in a flat binary format.
The resulting Series data files may subsequently be read in using the loadSeries() method. The Series data
object that results will be equivalent to that which would be generated by loadImagesAsSeries(). It is expected
that loading Series data directly from the series flat binary format, using loadSeries(), will be faster than
converting image data to a Series object through loadImagesAsSeries().
Parameters
----------
datapath: string
Path to data files or directory, specified as either a local filesystem path or in a URI-like format,
including scheme. A datapath argument may include a single '*' wildcard character in the filename. Examples
of valid datapaths include 'a/local/relative/directory/*.stack", "s3n:///my-s3-bucket/data/mydatafile.tif",
"/mnt/my/absolute/data/directory/", or "file:///mnt/another/data/directory/".
outputdirpath: string
Path to a directory into which to write Series file output. An outputdir argument may be either a path
on the local file system or a URI-like format, as in datapath. Examples of valid outputdirpaths include
"a/relative/directory/", "s3n:///my-s3-bucket/data/myoutput/", or "file:///mnt/a/new/directory/". If the
directory specified by outputdirpath already exists and the 'overwrite' parameter is False, this method
will throw a ValueError. If the directory exists and 'overwrite' is True, the existing directory and all
its contents will be deleted and overwritten.
dims: tuple of positive int, optional (but required if inputformat is 'stack')
Dimensions of input image data, for instance (1024, 1024, 48). Binary stack data will be interpreted as
coming from a multidimensional array of the specified dimensions.
The first dimension of the passed dims tuple should be the one that is changing most rapidly
on disk. So for instance given dims of (x, y, z), the coordinates of the data in a binary stack file
should be ordered as [(x0, y0, z0), (x1, y0, z0), ..., (xN, y0, z0), (x0, y1, z0), (x1, y1, z0), ...,
(xN, yM, z0), (x0, y0, z1), ..., (xN, yM, zP)]. This is the opposite convention from that used by numpy,
which by default has the fastest-changing dimension listed last (column-major convention). Thus, if loading
a numpy array `ary`, where `ary.shape == (z, y, x)`, written to disk by `ary.tofile("myarray.stack")`, the
corresponding dims parameter should be (x, y, z).
If inputformat is 'tif-stack', the dims parameter (if any) will be ignored; data dimensions will instead
be read out from the tif file headers.
inputformat: {'stack', 'tif-stack'}. optional, default 'stack'
Expected format of the input data. 'stack' indicates flat files of raw binary data, while 'tif-stack'
indicates a sequence of multipage tif files, with each page of the tif corresponding to a separate z-plane.
For both stacks and tif stacks, separate files are interpreted as distinct time points, with ordering
given by lexicographic sorting of file names.
This method assumes that stack data consists of signed 16-bit integers in native byte order. The lower-level
API method SeriesLoader.saveFromStack() allows alternative data types to be read in.
dtype: string or numpy dtype. optional, default 'int16'
Data type of the image files to be loaded, specified as a numpy "dtype" string. If inputformat is
'tif-stack', the dtype parameter (if any) will be ignored; data type will instead be read out from the
tif headers.
blocksize: string formatted as e.g. "64M", "512k", "2G", or positive int. optional, default "150M"
Requested size of individual output files in bytes (or kilobytes, megabytes, gigabytes). This parameter
also indirectly controls the number of Spark partitions to be used, with one partition used per block
created.
startidx: nonnegative int, optional
startidx and stopidx are convenience parameters to allow only a subset of input files to be read in. These
parameters give the starting index (inclusive) and final index (exclusive) of the data files to be used
after lexicographically sorting all input data files matching the datapath argument. For example,
startidx=None (the default) and stopidx=10 will cause only the first 10 data files in datapath to be read
in; startidx=2 and stopidx=3 will cause only the third file (zero-based index of 2) to be read in. startidx
and stopidx use the python slice indexing convention (zero-based indexing with an exclusive final position).
stopidx: nonnegative int, optional
See startidx.
shuffle: boolean, optional, default False
Controls whether the conversion from Images to Series formats will make use of a Spark shuffle-based method.
The default at present is not to use a shuffle. The shuffle-based method may lead to higher performance in
some cases, but the default method appears to be more stable with larger data set sizes. This default may
change in future releases.
overwrite: boolean, optional, default False
If true, the directory specified by outputdirpath will first be deleted, along with all its contents, if it
already exists. (Use with caution.) If false, a ValueError will be thrown if outputdirpath is found to
already exist.
"""
checkparams(inputformat, ['stack', 'tif-stack'])
if inputformat.lower() == 'stack' and not dims:
raise ValueError("Dimensions ('dims' parameter) must be specified if loading from binary image stack" +
" ('stack' value for 'inputformat' parameter)")
if shuffle:
from thunder.rdds.fileio.imagesloader import ImagesLoader
loader = ImagesLoader(self._sc)
if inputformat.lower() == 'stack':
loader.fromStack(datapath, dims, dtype=dtype, startidx=startidx, stopidx=stopidx)\
.saveAsBinarySeries(outputdirpath, blockSize=blocksize, overwrite=overwrite)
else:
loader.fromMultipageTif(datapath, startidx=startidx, stopidx=stopidx)\
.saveAsBinarySeries(outputdirpath, blockSize=blocksize, overwrite=overwrite)
else:
from thunder.rdds.fileio.seriesloader import SeriesLoader
loader = SeriesLoader(self._sc)
if inputformat.lower() == 'stack':
loader.saveFromStack(datapath, outputdirpath, dims, datatype=dtype,
blockSize=blocksize, overwrite=overwrite, startidx=startidx, stopidx=stopidx)
else:
loader.saveFromMultipageTif(datapath, outputdirpath, blockSize=blocksize,
startidx=startidx, stopidx=stopidx, overwrite=overwrite)
def convertImagesToSeries(self,
datapath,
outputdirpath,
dims=None,
inputformat='stack',
dtype='int16',
blocksize="150M",
startidx=None,
stopidx=None,
shuffle=False,
overwrite=False):
"""
Write out Images data as Series data, saved in a flat binary format.
The resulting Series data files may subsequently be read in using the loadSeries() method. The Series data
object that results will be equivalent to that which would be generated by loadImagesAsSeries(). It is expected
that loading Series data directly from the series flat binary format, using loadSeries(), will be faster than
converting image data to a Series object through loadImagesAsSeries().
Parameters
----------
datapath: string
Path to data files or directory, specified as either a local filesystem path or in a URI-like format,
including scheme. A datapath argument may include a single '*' wildcard character in the filename. Examples
of valid datapaths include 'a/local/relative/directory/*.stack", "s3n:///my-s3-bucket/data/mydatafile.tif",
"/mnt/my/absolute/data/directory/", or "file:///mnt/another/data/directory/".
outputdirpath: string
Path to a directory into which to write Series file output. An outputdir argument may be either a path
on the local file system or a URI-like format, as in datapath. Examples of valid outputdirpaths include
"a/relative/directory/", "s3n:///my-s3-bucket/data/myoutput/", or "file:///mnt/a/new/directory/". If the
directory specified by outputdirpath already exists and the 'overwrite' parameter is False, this method
will throw a ValueError. If the directory exists and 'overwrite' is True, the existing directory and all
its contents will be deleted and overwritten.
dims: tuple of positive int, optional (but required if inputformat is 'stack')
Dimensions of input image data, for instance (1024, 1024, 48). Binary stack data will be interpreted as
coming from a multidimensional array of the specified dimensions.
The first dimension of the passed dims tuple should be the one that is changing most rapidly
on disk. So for instance given dims of (x, y, z), the coordinates of the data in a binary stack file
should be ordered as [(x0, y0, z0), (x1, y0, z0), ..., (xN, y0, z0), (x0, y1, z0), (x1, y1, z0), ...,
(xN, yM, z0), (x0, y0, z1), ..., (xN, yM, zP)]. This is the opposite convention from that used by numpy,
which by default has the fastest-changing dimension listed last (column-major convention). Thus, if loading
a numpy array `ary`, where `ary.shape == (z, y, x)`, written to disk by `ary.tofile("myarray.stack")`, the
corresponding dims parameter should be (x, y, z).
If inputformat is 'tif-stack', the dims parameter (if any) will be ignored; data dimensions will instead
be read out from the tif file headers.
inputformat: {'stack', 'tif-stack'}. optional, default 'stack'
Expected format of the input data. 'stack' indicates flat files of raw binary data, while 'tif-stack'
indicates a sequence of multipage tif files, with each page of the tif corresponding to a separate z-plane.
For both stacks and tif stacks, separate files are interpreted as distinct time points, with ordering
given by lexicographic sorting of file names.
This method assumes that stack data consists of signed 16-bit integers in native byte order. The lower-level
API method SeriesLoader.saveFromStack() allows alternative data types to be read in.
dtype: string or numpy dtype. optional, default 'int16'
Data type of the image files to be loaded, specified as a numpy "dtype" string. If inputformat is
'tif-stack', the dtype parameter (if any) will be ignored; data type will instead be read out from the
tif headers.
blocksize: string formatted as e.g. "64M", "512k", "2G", or positive int. optional, default "150M"
Requested size of individual output files in bytes (or kilobytes, megabytes, gigabytes). This parameter
also indirectly controls the number of Spark partitions to be used, with one partition used per block
created.
startidx: nonnegative int, optional
startidx and stopidx are convenience parameters to allow only a subset of input files to be read in. These
parameters give the starting index (inclusive) and final index (exclusive) of the data files to be used
after lexicographically sorting all input data files matching the datapath argument. For example,
startidx=None (the default) and stopidx=10 will cause only the first 10 data files in datapath to be read
in; startidx=2 and stopidx=3 will cause only the third file (zero-based index of 2) to be read in. startidx
and stopidx use the python slice indexing convention (zero-based indexing with an exclusive final position).
stopidx: nonnegative int, optional
See startidx.
shuffle: boolean, optional, default False
Controls whether the conversion from Images to Series formats will make use of a Spark shuffle-based method.
The default at present is not to use a shuffle. The shuffle-based method may lead to higher performance in
some cases, but the default method appears to be more stable with larger data set sizes. This default may
change in future releases.
overwrite: boolean, optional, default False
If true, the directory specified by outputdirpath will first be deleted, along with all its contents, if it
already exists. (Use with caution.) If false, a ValueError will be thrown if outputdirpath is found to
already exist.
"""
checkparams(inputformat, ['stack', 'tif-stack'])
if inputformat.lower() == 'stack' and not dims:
raise ValueError(
"Dimensions ('dims' parameter) must be specified if loading from binary image stack"
+ " ('stack' value for 'inputformat' parameter)")
if shuffle:
from thunder.rdds.fileio.imagesloader import ImagesLoader
loader = ImagesLoader(self._sc)
if inputformat.lower() == 'stack':
loader.fromStack(datapath, dims, dtype=dtype, startidx=startidx, stopidx=stopidx)\
.saveAsBinarySeries(outputdirpath, blockSize=blocksize, overwrite=overwrite)
else:
loader.fromMultipageTif(datapath, startidx=startidx, stopidx=stopidx)\
.saveAsBinarySeries(outputdirpath, blockSize=blocksize, overwrite=overwrite)
else:
from thunder.rdds.fileio.seriesloader import SeriesLoader
loader = SeriesLoader(self._sc)
if inputformat.lower() == 'stack':
loader.saveFromStack(datapath,
outputdirpath,
dims,
datatype=dtype,
blockSize=blocksize,
overwrite=overwrite,
startidx=startidx,
stopidx=stopidx)
else:
loader.saveFromMultipageTif(datapath,
outputdirpath,
blockSize=blocksize,
startidx=startidx,
stopidx=stopidx,
overwrite=overwrite)
