playnano.cli.utils module

Utility functions for the playNano CLI.

playnano.cli.utils.ask_for_analysis_params(module_name: str) → dict[str, Any]

Introspect a module’s run() or parameter spec and ask for values.

playnano.cli.utils.ask_for_processing_params(step_name: str) → dict[str, Any]

Introspect a processing callable’s parameters and ask interactively.

Skips the first positional arguments (data, mask).

playnano.cli.utils.get_processing_step_type(step_name: str) → str

Return the type of a processing step.

playnano.cli.utils.is_valid_analysis_step(name: str) → bool

Return True if name is a built-in analysis, plugin or the ‘clear’ step.

playnano.cli.utils.is_valid_step(name: str) → bool

Return True if name is a built-in filter, mask, plugin or the ‘clear’ step.

playnano.cli.utils.parse_analysis_file(path: str) → list[tuple[str, dict[str, object]]]

Parse a YAML or JSON analysis file into a list of (name, parameters) tuples.

This reads a saved analysis pipeline definition, validates its structure, and normalizes any complex types (e.g., tuples) into YAML/JSON-safe forms.

Parameters:

path (str) – Path to the YAML or JSON file containing the analysis definition.

Returns:

A list where each element is (analysis_step_name, kwargs_dict). The kwargs_dict contains parameters for that analysis step.

Return type:

list of tuple

Raises:

• FileNotFoundError – If the file does not exist.

• ValueError – If the file cannot be parsed as YAML or JSON, or if the top-level key analysis is missing.

Examples

Example YAML format:

analysis:
  - name: count_nonzero
  - name: feature_detection
    mask_fn: mask_threshold
    min_size: 10
    remove_edge: true
  - name: particle_tracking
    coord_columns: [centroid_x, centroid_y]
    coord_key: features_per_frame
    detection_module: feature_detection
    max_distance: 5.0

This would be parsed as:

[
    ("count_nonzero", {}),
    ("feature_detection", {
        "mask_fn": "mask_threshold",
        "min_size": 10,
        "remove_edge": True
    }),
    ("particle_tracking", {
        "coord_columns": ["centroid_x", "centroid_y"],
        "coord_key": "features_per_frame",
        "detection_module": "feature_detection",
        "max_distance": 5.0
    })
]

playnano.cli.utils.parse_analysis_string(analysis_str: str) → list[tuple[str, dict[str, object]]]

Parse ; delimited analysis strings into a list (analysis_step_name, kwargs) tuples.

Each segment in analysis_str is of the form:

analysis_module_name analysis_module_name:param=value analysis_module_name:param1=value1,param2=value2

Example

“log_blob_detection:min_sigma=1.0,max_sigma=5.0;x_means_clustering:time_weight=0.2”

Returns a list in the order encountered, e.g.:

[(“log_blob_detection”, {“min_sigma”:1.0,”max_sigma”:5.0}),

(“x_means_clustering”, {“time_weight”: 0.2})]

playnano.cli.utils.parse_processing_file(path: str) → list[tuple[str, dict[str, object]]]

Parse a YAML (or JSON) processing file into a list of (step_name, kwargs) tuples.

Expected YAML schema:

filters:

• name: remove_plane

• name: gaussian_filter sigma: 2.0

• name: threshold_mask threshold: 2

• name: polynomial_flatten order: 2

Returns a list in the order listed under filters.

playnano.cli.utils.parse_processing_string(processing_str: str) → list[tuple[str, dict[str, object]]]

Parse a semicolon-delimited string of processing steps into a structured list.

Each step in the string can optionally include parameters, separated by commas. Parameters are specified as key=value pairs.

Parameters:

processing_str (str) – Semicolon-delimited string specifying processing steps. Each step may have optional parameters (seperated by commas) after a colon, e.g., “remove_plane; gaussian_filter:sigma=2.0; threshold_mask:threshold=2”

Returns:

List of tuples, each containing: - step_name (str): the name of the processing step - kwargs (dict of str → object): dictionary of parameters for the step

Return type:

list of tuple

Examples

>>> parse_processing_string("remove_plane")
[('remove_plane', {})]

>>> parse_processing_string("gaussian_filter:sigma=2.0,truncate=4.0")
[('gaussian_filter', {'sigma': 2.0, 'truncate': 4.0})]

>>> parse_processing_string(
...     "remove_plane; gaussian_filter:sigma=2.0; threshold_mask:threshold=2"
... )
[
    ('remove_plane', {}),
    ('gaussian_filter', {'sigma': 2.0}),
    ('threshold_mask', {'threshold': 2})
]