sarcasm.export

Attributes

`logger`
`_METADATA_KEYS`

Classes

`MultiStructureAnalysis`	Class for multi-tif-file comparison of structure.
`MultiLOIAnalysis`	Class for multi-LOI comparison.
`Export`	A class used to export structure and motion data from SarcAsM and Motion objects.

Module Contents

sarcasm.export.logger

sarcasm.export._METADATA_KEYS

class sarcasm.export.MultiStructureAnalysis(list_files: List, folder: str, experiment: str = None, load_data: bool = False, **conditions)[source]

Class for multi-tif-file comparison of structure.

Parameters:

list_files (list) – List of tif files.
folder (str) – Path to a folder to store data and results.
experiment (str, optional) – Name of the experiment (default is None).
load_data (bool, optional) – Whether to load the dataframe from previous analysis from the data folder (default is False).
**conditions (dict) – Keyword arguments with regex functions to extract information from the filename.

folder

Path to the folder with data and results.

Type:: str

experiment

Name of the experiment.

Type:: str

files

List of tif files.

Type:: list

conditions

Keyword arguments with regex functions to extract information from the filename.

Type:: dict

data

DataFrame to store the structure data.

Type:: pandas.DataFrame

folder

experiment = None

files

conditions

data

get_data(structure_keys=None)[source]

Iterate files and get structure data.

Parameters:: structure_keys (list, optional) – List of keys to extract structure data (default is None).
Return type:: None

save_data()[source]

Save the DataFrame to the data folder.

Return type:: None

load_data()[source]

Load the DataFrame from the data folder.

Return type:: None
Raises:: FileExistsError – If the data file does not exist in the specified folder.

export_data(file_path, format='.xlsx')[source]

Export the DataFrame to .xlsx or .csv format.

Parameters:

file_path (str) – Path to the output file.
format (str, optional) – Format of the output file (‘.xlsx’ or ‘.csv’) (default is ‘.xlsx’).

Return type:

None

class sarcasm.export.MultiLOIAnalysis(list_lois, folder, load_data=False, **conditions)[source]

Class for multi-LOI comparison.

Parameters:

list_lois (list) – List of tuples containing tif file paths and LOI names.
folder (str) – Path to a folder to store data and results.
load_data (bool, optional) – Whether to load the dataframe from previous analysis from the folder (default is False).
**conditions (dict) – Keyword arguments with regex functions to extract information from the filename.

folder

Path to the folder with data and results.

Type:: str

lois

List of tuples containing tif file paths and LOI names.

Type:: list

conditions

Keyword arguments with regex functions to extract information from the filename.

Type:: dict

data

DataFrame to store the motion data.

Type:: pandas.DataFrame

folder

lois

conditions

data

get_data(loi_keys=None)[source]

Iterate files and get motion data.

Parameters:: loi_keys (list, optional) – List of keys to extract motion data (default is None).
Return type:: None

save_data()[source]

Save the DataFrame to the data folder as a pandas DataFrame.

Return type:: None

load_data(path: str | None = None) → pandas.DataFrame[source]

Load the DataFrame from the data folder.

Parameters:: path (str, optional) – Path of pickle file with motion data. If None, fallback to data_motion.pd in self.folder.
Return type:: None
Raises:: FileExistsError – If the data file does not exist in the specified folder.

export_data(file_path, format='.xlsx')[source]

Export the DataFrame to .xlsx or .csv format.

Parameters:

file_path (str) – Path to the output file.
format (str, optional) – Format of the output file (‘.xlsx’ or ‘.csv’) (default is ‘.xlsx’).

Return type:

None

class sarcasm.export.Export[source]

A class used to export structure and motion data from SarcAsM and Motion objects.

structure_keys_default

Default structure keys.

Type:: list

motion_keys_default

Default motion keys.

Type:: list

structure_keys_default = ['cell_mask_area', 'cell_mask_area_ratio', 'cell_mask_intensity', 'domain_area_mean',...

motion_keys_default = ['beating_rate', 'beating_rate_variability', 'contr_max', 'contr_max_avg', 'elong_max',...

static get_structure_dict(sarc_obj, structure_keys=None, **conditions)[source]

Create a dictionary of structure and metadata features from a SarcAsM object.

Parameters:

sarc_obj (SarcAsM) – Object of SarcAsM class or Motion class.
structure_keys (list, optional) – List of structure keys (default is None).
conditions (kwargs) – Keyword arguments to add information to the dictionary (e.g., “cell_line”= “wt”, “info_xyz”=42).

Returns:

Dictionary containing selected metadata and structure features.

Return type:

dict

static export_structure_data(file_path, sarc_obj: sarcasm.structure.Structure | sarcasm.motion.Motion, structure_keys=None, fileformat='.xlsx', raw: bool = False)[source]

Export structure data to a file.

Summary mode (raw=False, default) writes one value per metric per frame: multi-frame analyses become a single table with one column per frame (frame_0, frame_1, …), single-frame analyses collapse to a single value column. Full mode (raw=True) preserves per-object distributions and requires fileformat='.json'. See Export.write_dict() for the full layout.

Parameters:

file_path (str) – Path to the output file.
sarc_obj (SarcAsM) – Object of SarcAsM class.
structure_keys (list, optional) – List of structure keys (default is None).
fileformat (str, optional) – Format of the output file: '.xlsx', '.csv', or '.json' (default is '.xlsx').
raw (bool, optional) – If True, export raw per-object distributions (JSON only). Default False.

static flatten_single(x)[source]: Return the lone element if x is a 1-element list/ndarray; otherwise x.

static get_motion_dict(motion_obj, loi_keys=None, concat=False, **conditions)[source]

Create a dictionary of motion features and metadata from a Motion object.

Parameters:

motion_obj (Motion) – Object of Motion class for LOI analysis.
loi_keys (list, optional) – List of LOI keys (default is None).
concat (bool, optional) – If True, all 2D arrays will be concatenated to 1D arrays (default is False).
conditions (kwargs) – Keyword arguments to add to the dictionary, can be any information, e.g., drug=’ABC’.

Returns:

Dictionary containing selected metadata and motion features.

Return type:

dict

static to_json_friendly(d: dict) → dict[source]: Recursively convert numpy / sparse types to JSON-serializable values.

static _infer_n_frames(d: dict) → int | None[source]: Infer the number of frames / z-sections from a features dict.

static _classify_for_framewise(d: dict, n_frames: int | None)[source]

Split dict into (scalars, per_frame, ragged, other) for tabular export.

scalars: plain scalar / str / None, or ndarrays with only one entry.
per_frame: 1D ndarray with length == n_frames (frame-indexed scalars).
ragged: lists of length n_frames whose elements are arrays or None (ragged per-object distributions per frame).
other: multi-dim arrays, mismatched-length arrays, etc.

static write_dict(file_path: str, d: dict, fileformat: str, raw: bool = False) → None[source]

Write a features dict to disk.

fileformat is one of 'csv', 'xlsx', 'json' (leading dot optional).

Two modes:

raw=False (default, Summary): one value per metric per frame. For xlsx/csv, rows are metric names and columns are frame_0, frame_1, ..., frame_{N-1}; single-frame analyses collapse to a single value column. Scalar metadata values are broadcast across every frame column. Ragged per-object distributions are collapsed to a per-frame nanmean. JSON writes the same content as scalars / per-frame lists (ragged collapsed).
raw=True (Full): full nested structure including per-object distributions. JSON only — per-object arrays can contain thousands of values per frame and do not fit a single table; xlsx and csv raise ValueError.

static export_motion_data(mot_obj: sarcasm.motion.Motion, file_path, motion_keys=None, fileformat='.xlsx', raw: bool = False)[source]

Export motion data to a file.

Summary mode (raw=False, default) writes one value per metric per frame as a single table with one column per frame (frame_0, frame_1, …). Full mode (raw=True) preserves per-object distributions and requires fileformat='.json'. See Export.write_dict() for the full layout.

Parameters:

mot_obj (Motion) – Object of Motion class.
file_path (str) – Path to the output file.
motion_keys (list, optional) – List of motion keys (default is None).
fileformat (str, optional) – Format of the output file: '.xlsx', '.csv', or '.json' (default is '.xlsx').
raw (bool, optional) – If True, export raw per-object distributions (JSON only). Default False.