Experiment

This module implements the first core class: Experiment, and functions to parse containers, retrieve and build data.

Each experiment consists of multiple containers where data is stored under container folders. A container may correspond to a single field of view, to a subset thereof (e.g. a single channel in microfluidic experiments).

Such containers must meet two requirements:
  1. Cell identifiers are unique within a container;
  2. Lineage reconstruction is defined and performed within a single container.
This module stores classes and functions that allow to:
  • explore data structure (and metadata if provided)
  • keep track of every container where to look for data
  • extract data in a Container instance from text containers
  • build cells filiation, store time-lapse microscopy data, build trees
class tunacell.base.experiment.Experiment(path='.', filetype=None, filter_set=None, count_items=False)

General class that stores experiment details.

Creates an Experiment instance from reading a file, records path, filetype, reads metadata, stores the list of container containers.

Parameters:
  • path (str) – path to experiment root file
  • -- str {None, 'text', 'h5'} (filetype) – leave to None for automatic detection.
abspath

str – absolute path on disk of main directory for text containers

label

str – experiment label

filetype

str {‘text’, ‘simu’} – one of the available file type (‘simu’ is not a filetype per se…)

fset

FilterSet instance – filterset to be applied when parsing data

datatype

Numpy.dtype instance – provides the datatype of raw data stored in each Cell instance .data This attribute is defined only for text filetype, when a descriptor file is associated to the experiment.

metadata

Metadata instance – experiment metadata

containers

list of str – sequence of container filenames for text containers

period

float – time interval between two successive aquisitions (this should be defined in the experiment metadata)

iter_containers(self, read=True, build=True, prefilt=None,
extend_observables=False, report_NaNs=True, size=None, shuffle=False)

browse containers

analysis_path

Get analysis path (with appropriate filterset path)

count_items(independent=True, seed=None, read=True)

Parse data to count items: cells, colonies, lineages, containers

Parameters:
  • independent (bool {True, False}) – lineage decomposition parameter
  • seed (int, or None) – lineage decomposition parameter
  • read (bool {True, False}) – try to read it in analysis folder
fset

Get current FilterSet

get_container(label, read=True, build=True, prefilt=None, extend_observables=False, report_NaNs=True)

Open specified container from this experiment.

Parameters:
  • label (str) – name of the container file to be opened
  • read (bool (default True)) – whether to read data and extract Cell instances list
  • build (bool (default True)) – when read option is active, whether to build Colony instances
  • extend_observables (bool (default False)) – whether to compute secondary observables from raw data
  • report_NaNs (bool (default True)) – whether to report for NaNs found in data
Returns:

container

Return type:

Container instance

Raises:
  • ParsingExperimentError : when no container corresponds in this exp
  • ParsingContainerError: when despite of existing container filename, – parsing of container failed and nothing is loaded
info()

Show informations about experiment

iter_cells(size=None, shuffle=False)

Iterate through valid cells.

Applies all filters defined in fset.

Parameters:
  • size (int (default None)) – limit the number of lineages to size. Works only in mode=’all’
  • shuffle (bool (default False)) – whether to shuffle the ordering of lineages when mode=’all’
Yields:

cell (Cell instance) – filtering removed outlier cells, containers, colonies, and lineages

iter_colonies(filter_for_colonies='from_fset', size=None, shuffle=False)

Iterate through valid colonies.

Parameters:
  • filter_for_colonies (FilterTree instance or str {'from_fset', 'none'}) –
  • size (int (default None)) – limit the number of colonies to size. Works only in mode=’all’
  • shuffle (bool (default False)) – whether to shuffle the ordering of colonies when mode=’all’
Yields:

colony (Colony instance) – filtering removed outlier cells, containers, and colonies

iter_containers(read=True, build=True, filter_for_cells='from_fset', filter_for_containers='from_fset', apply_container_filter=True, extend_observables=False, report_NaNs=True, size=None, shuffle=False)

Iterator over containers.

Parameters:
  • size (int (default None)) – number of containers to be parsed
  • read (bool (default True)) – whether to read data and extract Cell instances
  • build (bool (default True), called only if read is True) – whether to build colonies
  • filter_for_cells (FilterCell instance, or str {'from_fset', 'none'}) – filter applied to cells when data files are parsed
  • filter_for_containers (FilterContainer instance or str {'from_fset', 'none'}) – filter applied to containers when data files are parsed
  • extend_observables (bool (default False)) – whether to construct secondary observables from raw data
  • report_NaNs (bool (default True)) – whether to report for NaNs found in data
  • shuffle (bool (default False)) – when size is set to a number, whether to randomize ordering of upcoming containers
Returns:

Return type:

iterator iver Container instances of current Experiment instance.

iter_lineages(filter_for_lineages='from_fset', size=None, shuffle=False)

Iterate through valid lineages.

Parameters:
  • filter_for_lineages (FilterLineage instance or str {'from_fset', 'none'}) – filter lineages
  • size (int (default None)) – limit the number of lineages to size. Works only in mode=’all’
  • shuffle (bool (default False)) – whether to shuffle the ordering of lineages when mode=’all’
Yields:

lineage (Lineage instance) – filtering removed outlier cells, containers, colonies, and lineages

raw_text_export(path='.', metadata_extension='.yml')

Export raw data as text containers in correct directory structure.

Parameters:
  • path (str) – path to experiment root directory
  • metadata_extension (str (default '.yml')) – type of metadata file (now only yaml file works)
tunacell.base.experiment.count_items(exp, independent_decomposition=True, seed=None)

Parse the experiment, with associated FilterSet, and count items