smlmlp.Locs module

class smlmlp.Locs(source=None, config=None, **kwargs)[source]

Bases: LocsReceiver

Store localization dataframes and metadata for one experiment.

Parameters:

  • source (Locs, pandas.DataFrame, path-like, list[pandas.DataFrame], or None, default=None) – Localization source to open. Can be an existing Locs object, a DataFrame, a path to a file or folder, a list of DataFrames, or None.

  • config (Config, path-like, dict, or None, default=None) – Configuration source passed to Config.

  • **kwargs – Additional attributes assigned on the instance.

df_dict

Mapping of dataframe names to dataframe instances.

Type:

dict

config

Configuration attached to this localization set.

Type:

Config

detections

Shortcut to the detections dataframe.

Type:

DetsDataFrame

ndetections

Number of detections in the dataset.

Type:

int

times

Alias for timing storage used by analysis decorators.

Type:

dict

Examples

>>> from smlmlp import Locs
>>> instance = Locs()
>>> # Or from a DataFrame
>>> import pandas as pd
>>> import numpy as np
>>> df = pd.DataFrame({
...     "frame": [1, 1, 2],
...     "x detection [nm]": [10.0, 20.0, 30.0],
...     "y detection [nm]": [15.0, 25.0, 35.0],
... })
>>> locs = Locs(df)
>>> locs.ndetections
3
append(path, file=None)[source]

Append localization dataframes to existing CSV files.

If the destination files are missing, fallback to save().

combine(*locs_list, col_name='ch')[source]

Combine this Locs object with others and label their source.

Parameters:

  • *locs_list (Locs) – Additional Locs objects to combine.

  • col_name (str, optional) – Name of the column to store channel labels. Default is 'ch'.

Returns:

New Locs object with combined detections and channel labels.

Return type:

Locs

property config_kwargs

Return config kwargs.

property config_source
crop(xmin, ymin, xmax, ymax)[source]

Crop detections to an inclusive xy rectangle.

Parameters:

  • xmin (float) – Minimum x coordinate in nm.

  • ymin (float) – Minimum y coordinate in nm.

  • xmax (float) – Maximum x coordinate in nm.

  • ymax (float) – Maximum y coordinate in nm.

Returns:

New Locs object with cropped detections.

Return type:

Locs

property detections

Return detections dataframe.

df_dict = None
filter(*filter_names, mask=None, df_name='detections')[source]

Return a new Locs object containing rows matching all filters.

Parameters:

  • *filter_names (str) – Names of filters to apply.

  • mask (array-like or None, optional) – Additional boolean mask to apply.

  • df_name (str, optional) – Name of the dataframe to filter. Default is 'detections'.

Returns:

New Locs object with filtered data.

Return type:

Locs

property ndetections

Return number of detections.

open(source)[source]

Open localization data from a supported source.

Parameters:

source (pandas.DataFrame, str, Path, list, tuple, or None) – Source to open data from. Supported types: - pandas.DataFrame: directly loaded as detections - str/Path to CSV: loaded as DataFrame - str/Path to JSON: loaded as config - str/Path to directory: loads all CSV/JSON files - list/tuple of DataFrames: multiple dataframes combined - None: does nothing

Raises:

  • SyntaxError – If source type is not recognized.

  • ValueError – If multiple or no detections dataframes are provided in a list.

printer = None
save(path, file=None)[source]

Save localization dataframes and metadata to a folder.

Parameters:

  • path (path-like) – Directory path to save to.

  • file (str or None, optional) – Optional filename within the directory.

split(nlocs=2)[source]

Split localizations by frame modulo nlocs.

Parameters:

nlocs (int, optional) – Number of splits. Default is 2.

Returns:

Tuple of Locs objects, one for each split.

Return type:

tuple of Locs

property time
property times

Alias timing storage used by analysis decorators.

Linked modules