acia.analysis#

Functionality for single-cell analysis

class acia.analysis.PropertyExtractor[source]#

Bases: object

Base class for single-cell property extractor

__init__(name, input_unit, output_unit=None)[source]#
Parameters:

  • name (str)

  • input_unit (UnitLike | None)

  • output_unit (UnitLike | None)

extract(overlay, images, df)[source]#

Extract the desired properties for a single contour

Parameters:

  • contour (Contour) – contour for the qunatity

  • overlay (Overlay) – overlay containing all contours

  • df (pd.DataFrame) – DataFrame of properties so far

  • images (ImageSequenceSource)

Raises:

NotImplementedError – Please implement this method

convert(input)[source]#

Converts input to the specified output unit

Parameters:

input (float | Quantity) – Input value

Returns:

float – the magnitude in the output unit

Return type:

float

convert_array(values)[source]#

Vectorised convert() over an array of magnitudes.

Produces bit-identical results to calling convert() per value (verified in tests/test_property_equivalence.py), because the conversion really is a single multiply and this performs the same one.

Return type:

ndarray

class acia.analysis.ExtractorExecutor[source]#

Bases: object

Executor to extract a list of single-cell properties from segmentation and images

__init__()[source]#
Return type:

None

execute(overlay, images, extractors=None, units='none')[source]#

Extract single-cell properties into a DataFrame.

Parameters:

  • overlay (Overlay) – the contours to extract properties from.

  • images (ImageSequenceSource) – the image source (needed e.g. for fluorescence).

  • extractors (list[PropertyExtractor] | None) – the property extractors to run.

  • units (str) –

    representation of physical units in the returned table:

    • "none" (default) – plain numeric columns; the unit map is carried in df.attrs["units"]. Not unit-safe.

    • "header" – plain values with the unit as a column-index level (export/readable form). Not unit-safe.

    • "pint" – pint[...] columns; the only representation with unit-safe arithmetic (propagation + dimensional checks).

    The forms are convertible afterwards via acia.analysis.attach_units() / strip_units / units_in_header.

class acia.analysis.AreaEx[source]#

Bases: PropertyExtractor

Extract area for every contour

__init__(input_unit=None, output_unit=None)[source]#
Parameters:

  • input_unit (UnitLike | None)

  • output_unit (UnitLike | None)

extract(overlay, images, df)[source]#

Extract the desired properties for a single contour

Parameters:

  • contour (Contour) – contour for the qunatity

  • overlay (Overlay) – overlay containing all contours

  • df (pd.DataFrame) – DataFrame of properties so far

  • images (ImageSequenceSource)

Raises:

NotImplementedError – Please implement this method

class acia.analysis.PerimeterEx[source]#

Bases: PropertyExtractor

Extract area for every contour

__init__(input_unit=None, output_unit=None)[source]#
Parameters:

  • input_unit (UnitLike | None)

  • output_unit (UnitLike | None)

extract(overlay, images, df)[source]#

Extract the desired properties for a single contour

Parameters:

  • contour (Contour) – contour for the qunatity

  • overlay (Overlay) – overlay containing all contours

  • df (pd.DataFrame) – DataFrame of properties so far

  • images (ImageSequenceSource)

Raises:

NotImplementedError – Please implement this method

class acia.analysis.CircularityEx[source]#

Bases: PropertyExtractor

Extract area for every contour

__init__(input_unit='1', output_unit='1')[source]#
Parameters:

  • input_unit (UnitLike | None)

  • output_unit (UnitLike | None)

extract(overlay, images, df)[source]#

Extract the desired properties for a single contour

Parameters:

  • contour (Contour) – contour for the qunatity

  • overlay (Overlay) – overlay containing all contours

  • df (pd.DataFrame) – DataFrame of properties so far

  • images (ImageSequenceSource)

Raises:

NotImplementedError – Please implement this method

class acia.analysis.BoundaryClosenessEx[source]#

Bases: PropertyExtractor

Distance from each cell’s bounding box to the nearest image border.

The backing property for BoundaryClosenessFilter, which filters on how close a cell sits to the edge of the field of view (a cell that is partly outside it has unreliable size and shape). Extracting it as a column means the filter reads it like every other filter reads its own property, and it becomes plottable next to them in plot_property_histograms().

The frame extent comes from the source (size_w / size_h), so a cell whose bounding box touches a border measures 0.

__init__(input_unit=None, output_unit=None)[source]#
Parameters:

  • input_unit (UnitLike | None)

  • output_unit (UnitLike | None)

extract(overlay, images, df)[source]#

Extract the desired properties for a single contour

Parameters:

  • contour (Contour) – contour for the qunatity

  • overlay (Overlay) – overlay containing all contours

  • df (pd.DataFrame) – DataFrame of properties so far

  • images (ImageSequenceSource)

Raises:

NotImplementedError – Please implement this method

class acia.analysis.LengthEx[source]#

Bases: PropertyExtractor

Extracts width of cells based on the shorter edge of a minimum rotated bbox approximation

__init__(input_unit=None, output_unit=None)[source]#
Parameters:

  • input_unit (UnitLike | None)

  • output_unit (UnitLike | None)

extract(overlay, images, df)[source]#

Extract the desired properties for a single contour

Parameters:

  • contour (Contour) – contour for the qunatity

  • overlay (Overlay) – overlay containing all contours

  • df (pd.DataFrame) – DataFrame of properties so far

  • images (ImageSequenceSource)

Raises:

NotImplementedError – Please implement this method

class acia.analysis.WidthEx[source]#

Bases: PropertyExtractor

Extracts width of cells based on the shorter edge of a minimum rotated bbox approximation

__init__(input_unit=None, output_unit=None)[source]#
Parameters:

  • input_unit (UnitLike | None)

  • output_unit (UnitLike | None)

extract(overlay, images, df)[source]#

Extract width information for all contours

Parameters:
class acia.analysis.LengthWidthEx[source]#

Bases: PropertyExtractor

Extracts length and width of cells based on the shorter edge of a minimum rotated bbox approximation

__init__(prefix='', input_unit=None, output_unit=None)[source]#
Parameters:

  • input_unit (UnitLike | None)

  • output_unit (UnitLike | None)

extract(overlay, images, df)[source]#

Extract length and width information for all contours

Parameters:
class acia.analysis.FrameEx[source]#

Bases: PropertyExtractor

Extract the frame information for every contour

__init__()[source]#
extract(overlay, images, df)[source]#

Extract the desired properties for a single contour

Parameters:

  • contour (Contour) – contour for the qunatity

  • overlay (Overlay) – overlay containing all contours

  • df (pd.DataFrame) – DataFrame of properties so far

  • images (ImageSequenceSource)

Raises:

NotImplementedError – Please implement this method

class acia.analysis.IdEx[source]#

Bases: PropertyExtractor

Extract single-cell id for every contour

__init__()[source]#
extract(overlay, images, df)[source]#

Extract the desired properties for a single contour

Parameters:

  • contour (Contour) – contour for the qunatity

  • overlay (Overlay) – overlay containing all contours

  • df (pd.DataFrame) – DataFrame of properties so far

  • images (ImageSequenceSource)

Raises:

NotImplementedError – Please implement this method

class acia.analysis.LabelEx[source]#

Bases: PropertyExtractor

Extract single-cell label (from tracking) for every contour

__init__()[source]#
extract(overlay, images, df)[source]#

Extract the desired properties for a single contour

Parameters:

  • contour (Contour) – contour for the qunatity

  • overlay (Overlay) – overlay containing all contours

  • df (pd.DataFrame) – DataFrame of properties so far

  • images (ImageSequenceSource)

Raises:

NotImplementedError – Please implement this method

class acia.analysis.TimeEx[source]#

Bases: PropertyExtractor

Extract time information for every contour.

If no input_unit is given, the per-frame timepoints are taken from the image source (or the overlay) calibration – so a source loaded with a frame_interval (or sliced) yields correct, automatically-updated times. Passing input_unit keeps the legacy frame * interval behavior.

__init__(input_unit=None, output_unit='hour')[source]#
Parameters:

  • input_unit (UnitLike | None)

  • output_unit (UnitLike | None)

extract(overlay, images, df)[source]#

Extract the desired properties for a single contour

Parameters:

  • contour (Contour) – contour for the qunatity

  • overlay (Overlay) – overlay containing all contours

  • df (pd.DataFrame) – DataFrame of properties so far

  • images (ImageSequenceSource)

Raises:

NotImplementedError – Please implement this method

class acia.analysis.DynamicTimeEx[source]#

Bases: PropertyExtractor

Extract time information for every contour when timepoints are not equi-distant

__init__(timepoints, relative=True, input_unit='second', output_unit='hour')[source]#
Parameters:

  • timepoints (list)

  • input_unit (UnitLike)

  • output_unit (UnitLike | None)

extract(overlay, images, df)[source]#

Extract the desired properties for a single contour

Parameters:

  • contour (Contour) – contour for the qunatity

  • overlay (Overlay) – overlay containing all contours

  • df (pd.DataFrame) – DataFrame of properties so far

  • images (ImageSequenceSource)

Raises:

NotImplementedError – Please implement this method

class acia.analysis.PositionEx[source]#

Bases: PropertyExtractor

Extract cell center information from image RoI detections

__init__(input_unit=None, output_unit='micrometer')[source]#
Parameters:

  • input_unit (UnitLike | None)

  • output_unit (UnitLike | None)

extract(overlay, images, df)[source]#

Extract the desired properties for a single contour

Parameters:

  • contour (Contour) – contour for the qunatity

  • overlay (Overlay) – overlay containing all contours

  • df (pd.DataFrame) – DataFrame of properties so far

  • images (ImageSequenceSource)

Raises:

NotImplementedError – Please implement this method

class acia.analysis.FluorescenceEx[source]#

Bases: PropertyExtractor

Extracting fluorescence properties from image sequence and RoI detections

__init__(channels, channel_names, summarize_operator=<function median>, input_unit='1', output_unit='', parallel=6)[source]#
Parameters:

  • input_unit (UnitLike)

  • output_unit (UnitLike | None)

static extract_fluorescence(overlay, image, channels, channel_names, summarize_operator)[source]#

Extract fluorescence information based on an overlay(segmentation) and corresponding image.

Parameters:

  • overlay (Overlay) – Ovleray providing the image segmentation information

  • image (BaseImage) – the image itself

  • channels (List[int]) – list of channels (image channels) we want to investigate

  • channel_names (List[str]) – list of names for the channel results

  • summarize_operator (_type_) – summarizing operator, e.g. np.media, to compress all fluorescence values to a single one

Returns:

pd.DataFrame – pandas data frame containing columns of channel_names and the rows represent the extracted fluorescence

extract(overlay, images, df)[source]#

Extract the desired properties for a single contour

Parameters:

  • contour (Contour) – contour for the qunatity

  • overlay (Overlay) – overlay containing all contours

  • df (pd.DataFrame) – DataFrame of properties so far

  • images (ImageSequenceSource)

Raises:

NotImplementedError – Please implement this method

acia.analysis.default_execution_naming(source)[source]#

Source-aware default folder name for one scaled execution.

  • int (e.g. an OMERO image id) -> "execution_<id>"

  • str (a file path or fsspec URL) -> the file stem, i.e. the file name without directory and extension (smb://host/share/pos1.tif -> pos1)

For other item types (e.g. a parameter dict) the name cannot be inferred; pass an explicit execution_naming to scale() in that case.

Return type:

str

acia.analysis.scale(output_path, analysis_script, image_ids, additional_parameters=None, exist_ok=False, execution_naming=None, exist_skip=False, kernel_name=None, parameter_name='image_id', max_workers=1, storage_parameter_name='storage_folder', stage_progress='keep')[source]#

Scale an analysis notebook to several image sources.

Each entry in image_ids identifies one image source and triggers one notebook execution. An entry may be:

  • an int – e.g. an OMERO image id (default folder execution_<id>),

  • a str – a local path or fsspec URL such as smb://host/share/x.tif (default folder name is the file stem, e.g. x),

  • a dict – arbitrary parameters merged into the notebook; provide an explicit execution_naming for these.

The identifier is injected into the notebook under parameter_name (default "image_id"), so existing notebooks keep working. The notebook is responsible for turning it into a concrete source (e.g. OmeroSequenceSource(image_id) or SambaSequenceSource.from_url(image_id)).

Hint: the analysis script should only use absolute paths as the file is copied and executed in another folder.

Parameters:

  • output_path (Path) – the general output path to the storage

  • analysis_script (Path) – the template script

  • image_ids (list[int | str | dict]) – image sources to scale over (ids, paths/URLs, or parameter dicts).

  • additional_parameters (dict) – Parameters to be inserted into the jupyter script

  • exist_ok (Bool) – True when it is okay that the directory exists, False will throw an error when the directory exists.

  • execution_naming (Callable) – maps an entry to its output folder name. By default default_execution_naming() is used, which dispatches on the entry type (id -> execution_<id>, path -> file stem).

  • exist_skip (Bool) – If true existing executions are skipped.

  • kernel_name (str) – specifies the notebook kernel to be used. None is the default kernel.

  • parameter_name (str) – name of the notebook parameter the identifier is injected as (ignored for dict entries, which are merged as-is).

  • storage_parameter_name (str | None) – the notebook parameter the per-run output/execution folder (absolute) is injected under. Defaults to "storage_folder". Set it to match the notebook’s own output parameter, or to None to not inject it at all (avoids papermill’s “Passed unknown parameter” warning for notebooks that derive their output location some other way).

  • max_workers (int) – how many notebooks to execute concurrently. 1 (default) runs them sequentially, exactly as before. Values > 1 run that many notebooks in parallel using a process pool started with the "spawn" method (not threads: papermill sets the working directory with a process-global os.chdir that threads would race on; and not fork: spawning fresh processes avoids duplicating a CUDA-initialised parent kernel – the classic Jupyter crash). Each execution is still its own kernel subprocess, so a worker whose kernel dies only fails its own image. On a single GPU keep this small (2-3): every concurrent run loads its own model, so throughput is bounded by GPU memory, not CPU cores.

  • stage_progress (str) – how the per-notebook cell progress is shown – "keep" (default) leaves the finished bars on screen as a per-stage timing log, "collapse" removes each bar once its stage is done, and "off" shows only the source bar. See below for what the two levels look like.

Progress output. There are always two levels: one bar counting sources, and per-notebook bars counting cells. Running sequentially, the source bar is labelled with what is running right now and papermill’s own bars sit underneath it:

01_Segment.ipynb | pos001_roi001.tiff:  33%|███| 1/3 [04:41<09:23, 281.63s/source]
  ↳ 01_Segment.ipynb | pos001_roi001.tiff: 100%|███| 21/21 [01:21<00:00, 3.88s/cell]

With max_workers > 1 there is no single “current” source, so the source bar reports the one that just finished and each worker gets its own bar instead:

Sources:  33%|███| 1/3 [04:41<09:23, 281.63s/source]
  [w1] pos001_roi001.tiff | 02_Track.ipynb:   57%|███| 12/21 [00:32<00:35, 3.91s/cell]
  [w2] pos002_roi001.tiff | 01_Segment.ipynb: 19%|█  |  4/21 [00:00<00:03, 4.88cell/s]

Those worker bars are drawn by this process from progress the workers report over a queue – children never write bars themselves, because they share one stderr with no shared cursor and would overwrite each other.

acia.analysis.extract_growth(overlay, images, *, time_unit='hour', agg='sum')[source]#

Single-cell table + log-linear growth-rate fit in one call.

Convenience wrapper combining single-cell extraction and the growth-rate fit (the last two steps of a typical time-lapse pipeline). Builds a per-cell table with frame + physical time (in time_unit) + physical area columns via ExtractorExecutor, then fits area ~ exp(growth_rate * time) aggregated per timepoint by agg with estimate_growth_rate().

Parameters:

  • overlay (Overlay) – the (already filtered) contours to measure.

  • images (ImageSequenceSource) – the calibrated image source (provides pixel_size for area and timepoints for time).

  • time_unit (str) – output unit for the time column and growth rate.

  • agg (AggMode) – per-timepoint aggregation of the value column (e.g. "sum" for total area, "count" for cell number).

Returns:

(table, result, figure) – the single-cell DataFrame, the GrowthRateResult, and the fit matplotlib figure.

Return type:

tuple[pd.DataFrame, GrowthRateResult, Figure]