Python Usage

Introduction

The image processing workflow can also be controlled via Python API.

To do so, first define the parameters:

from lls_core import LatticeData

params = LatticeData(
  input_image="/path/to/some/file.tiff",
  save_dir="/path/to/output"
)

Then save the result to disk:

params.save()

Or work with the images in memory:

for slice in params.process():
    pass

Other more advanced options are listed below.

Cropping

Cropping functionality can be enabled by setting the crop parameter:

from lls_core import LatticeData, CropParams 

params = LatticeData(
  input_image="/path/to/some/file.tiff",
  save_dir="/path/to/output",
  crop=CropParams(
    roi_list=["/path/to/roi.zip"]
  )
)

Other more advanced options are listed below.

Type Checking

Because of Pydantic idiosyncrasies, the LatticeData constructor can accept more data types than the type system realises. For example, input_image="/some/path" like we used above is not considered correct, because ultimately the input image has to become an xarray (aka DataArray). You can solve this in three ways.

The first is to use the types precisely as defined. In this case, we might define the parameters "correctly" (if verbosely) like this:

from lls_core import LatticeData
from aicsimageio import AICSImage
from pathlib import Path

params = LatticeData(
  input_image=AICSImage("/path/to/some/file.tiff").xarray_dask_data(),
  save_dir=Path("/path/to/output")
)

The second is to use LatticeData.parse_obj, which takes a dictionary of options and allows incorrect types:

params = LatticeData.parse_obj({
  "input_image": "/path/to/some/file.tiff",
  "save_dir": "/path/to/output"
})

Finally, if you're using MyPy, you can install the pydantic plugin, which solves this problem via the init_typed = False option.

API Docs

lls_core.LatticeData

Parameters for the entire deskewing process, including outputs and optional steps such as deconvolution. This is the recommended entry point for Python users: construct an instance of this class, and then perform the processing using methods.

Note that none of this class's methods have any parameters: all parameters are class fields for validation purposes.

Parameters:

Name	Type	Description	Default
`input_image`	`DataArray`	A 3-5D array containing the image data. Can be anything convertible to an Xarray, including a `dask.array` or `numpy.ndarray`. Can also be provided as a `str`, in which case it must indicate the path to an image to load from disk.	`None`
`skew`	`DeskewDirection`	Axis along which to deskew the image. Choices: `{"X", "Y"}`. These can be provided as `str`.	`<DeskewDirection.Y: 2>`
`angle`	`float`	Angle of deskewing, in degrees, as a float.	`30.0`
`physical_pixel_sizes`	`DefinedPixelSizes`	Pixel size of the microscope, in microns. This can alternatively be provided as a `tuple[float]` of `(Z, Y, X)`	`None`
`derived`	`DerivedDeskewFields`	Refer to the `DerivedDeskewFields` docstring	`None`
`save_dir`	`DirectoryPath`	The directory where the output data will be saved. This can be specified as a `str` or `Path`.	`None`
`save_suffix`	`str`	The filename suffix that will be used for output files. This will be added as a suffix to the input file name if the input image was specified using a file name. If the input image was provided as an in-memory object, the `save_name` field should instead be specified.	`'_deskewed'`
`save_name`	`str`	The filename that will be used for output files. This should not contain a leading directory or file extension. The final output files will have additional elements added to the end of this prefix to indicate the region of interest, channel, timepoint, file extension etc.	`None`
`save_type`	`SaveFileType`	The data type to save the result as. This will also be used to determine the file extension of the output files. Choices: `{"h5", "tiff"}`. Choices can alternatively be specifed as `str`, for example `'tiff'`.	`<SaveFileType.h5: 'h5'>`
`time_range`	`range`	The range of times to process. This defaults to all time points in the image array.	`None`
`channel_range`	`range`	The range of channels to process. This defaults to all time points in the image array.	`None`
`deconvolution`	`DeconvolutionParams \| None`	Parameters associated with the deconvolution. If this is None, then deconvolution is disabled	`None`
`crop`	`CropParams \| None`	Cropping parameters. If this is None, then cropping is disabled	`None`
`workflow`	`Workflow \| None`	If defined, this is a workflow to add lightsheet processing onto	`None`
`progress_bar`	`bool`	If true, show progress bars	`True`

process

process() -> ImageSlices

Execute the processing and return the result. This will not execute the attached workflow.

process_workflow

process_workflow() -> WorkflowSlices

Runs the workflow on each slice and returns the workflow results

save

save() -> None

Apply the processing, and saves the results to disk. Results can be found in save_dir.

lls_core.DeconvolutionParams

Parameters for the optional deconvolution step

Parameters:

Name	Type	Description	Default
`decon_processing`	`DeconvolutionChoice`	Hardware to use to perform the deconvolution. Choices: `{"cuda_gpu", "opencl_gpu", "cpu"}`. Can be provided as `str`.	`<DeconvolutionChoice.cpu: 'cpu'>`
`psf`	`List[DataArray]`	List of Point Spread Functions to use for deconvolution. Each of which should be a 3D array. Each PSF can also be provided as a `str` path, in which case they will be loaded from disk as images.	`[]`
`decon_num_iter`	`NonNegativeInt`	Number of iterations to perform in deconvolution	`10`
`background`	`float \| Literal[str, str]`	Background value to subtract for deconvolution. Only used when `decon_processing` is set to `GPU`. This can either be a literal number, "auto" which uses the median of the last slice, or "second_last" which uses the median of the last slice.	`0`

lls_core.CropParams

Parameters for the optional cropping step. Note that cropping is performed in the space of the deskewed shape. This is to support the workflow of performing a preview deskew and using that to calculate the cropping coordinates.

Parameters:

Name	Type	Description	Default
`roi_list`	`List[Roi]`	List of regions of interest, each of which must be an `N × D` array, where N is the number of vertices and D the coordinates of each vertex. This can alternatively be provided as a `str` or `Path`, or a list of those, in which case each they are interpreted as paths to ImageJ ROI zip files that are read from disk.	`[]`
`roi_subset`	`List[int]`	A subset of all the ROIs to process. Each list item should be an index into the ROI list indicating an ROI to include. This allows you to process only a subset of the regions from a ROI file specified using the `roi_list` parameter. If `None`, it is assumed that you want to process all ROIs.	`None`
`z_range`	`Tuple[NonNegativeInt, NonNegativeInt]`	The range of Z slices to take as a tuple of the form `(first, last)`. All Z slices before the first index or after the last index will be cropped out.	`None`

lls_core.models.results.ImageSlices

A collection of image slices, which is the main output from deskewing. This holds an iterable of output image slices before they are saved to disk, and provides a save_image() method for this purpose.

Parameters:

Name	Type	Description	Default
`slices`	`Iterable[ProcessedSlice[Union[Array, ndarray[Any, dtype[+ScalarType]], Array, DataArray]]]`	Iterable of result slices. For a given slice, you can access the image data through the `slice.data` property, which is a numpy-like array.	`None`
`lattice_data`	`ForwardRef('LatticeData')`	The "parent" LatticeData that was used to create this result	required

roi_previews

roi_previews() -> Iterable[ArrayLike]

Extracts a single 3D image for each ROI

save_image

save_image()

Saves result slices to disk

lls_core.models.results.WorkflowSlices

The counterpart of ImageSlices, but for workflow outputs. This is needed because workflows have vastly different outputs that may include regular Python types rather than only image slices.

Parameters:

Name	Type	Description	Default
`slices`	`Iterable[ProcessedSlice[Union[Tuple[Union[Array, ndarray[Any, dtype[+ScalarType]], Array, DataArray, dict, list]], Array, ndarray[Any, dtype[+ScalarType]], Array, DataArray, dict, list]]]`	Iterable of raw workflow results, the exact nature of which is determined by the author of the workflow. Not typically useful directly, and using he result of `.process()` is recommended instead.	`None`
`lattice_data`	`ForwardRef('LatticeData')`	The "parent" LatticeData that was used to create this result	required

process

process() -> Iterable[ProcessedWorkflowOutput]

Incrementally processes the workflow outputs, and returns both image paths and data frames of the outputs, for image slices and dict/list outputs respectively

roi_previews

roi_previews() -> Iterable[NDArray]

Extracts a single 3D image for each ROI

save

save() -> Iterable[Path]

Processes all workflow outputs and saves them to disk. Images are saved in the format specified in the LatticeData, while other data types are saved as a CSV. Remember to call list() on this to exhaust the generator and run the computation.

lls_core.models.results.ProcessedWorkflowOutput

Result class for one single workflow output, after it has been processed.

Parameters:

Name	Type	Default
`index`	`int`	`None`
`roi_index`	`int \| None`	`None`
`data`	`Path \| DataFrame`	`None`
`lattice_data`	`ForwardRef('LatticeData')`	required

save

save() -> Path

Puts this artifact on disk by saving any DataFrame to CSV, and returning the path to the image or CSV

lls_core.models.deskew.DefinedPixelSizes

Like PhysicalPixelSizes, but it's a dataclass, and none of its fields are None

Parameters:

Name	Type	Description	Default
`X`	`NonNegativeFloat`	Size of the X dimension of the microscope pixels, in microns.	`0.1499219272808386`
`Y`	`NonNegativeFloat`	Size of the Y dimension of the microscope pixels, in microns.	`0.1499219272808386`
`Z`	`NonNegativeFloat`	Size of the Z dimension of the microscope pixels, in microns.	`0.3`

lls_core.models.deskew.DerivedDeskewFields

Fields that are automatically calculated based on other fields in DeskewParams. Grouping these together into one model makes validation simpler.

Parameters:

Name	Type	Description	Default
`deskew_vol_shape`	`Tuple[int, ...]`	Dimensions of the deskewed output. This is set automatically based on other input parameters, and doesn't need to be provided by the user.	`None`
`deskew_affine_transform`	`AffineTransform3D`	Deskewing transformation function. This is set automatically based on other input parameters, and doesn't need to be provided by the user.	`None`

lls_core.models.output.SaveFileType

Choice of File extension to save