magmap.io.cli module

Command line parser and and environment setup for MagellanMapper.

This module can be run either as a script to work in headless mode or loaded and initialized by calling main().

Note on dimensions order: User-defined dimension variables are generally given in (x, y, z) order as per normal convention, but otherwise dimensions are generally in (z, y, x) for consistency with microscopy order and ease of processing stacks by z.

Examples

Launch in headless mode with the given file at a particular size and offset:

$ python -m magmap.cli --img /path/to/file.czi --offset 30,50,205 \
    --size 150,150,10

For a table of command-line arguments and their usage, see: https://github.com/sanderslab/magellanmapper/blob/master/docs/cli.md

magmap.io.cli.args_to_dict(args, keys, args_dict=None, sep_args='=', sep_vals=',', default=None)

Parse positional and keyword-based arguments to an enum-keyed dictionary.

Parameters:

• args (List[str]) – List of arguments with positional values followed by sep_args-delimited values. Positional values will be entered in the existing order of keys based on member values, while keyword-based values will be entered if a member corresponding to the keyword exists. Entries can also be sep_vals-delimited to specify lists.

• keys (Union[Type[Enum], Type[TypeVar(DataClass, bound= DataClassProtocol)]]) – Enum class or data class instance whose fields will be used as keys for dictionary. Enum values are assumed to range from 1 to number of members as output by the default Enum functional API.

• args_dict (Optional[Dict[Enum, Any]], default: None) – Dictionary to be filled or updated with keys from keys_enum. Defaults to None, which will assign an empty dict. Ignored if keys_class is a data class instance, which will be updated instead.

• sep_args (str, default: '=') – Separator between arguments and values; defaults to “=”.

• sep_vals (str, default: ',') – Separator within values; defaults to “,”.

• default (Optional[Any], default: None) – Default value for each argument. Effectively turns off positional argument assignments since all args become <keyword>=<default>. Defaults to None. If a str, will undergo splitting by sep_vals.

Return type:

Union[Dict[Enum, Any], Type[TypeVar(DataClass, bound= DataClassProtocol)]]

Returns:

Dictionary or data class corresponding to keys, filled with arguments. Values that contain commas will be split into comma-delimited lists. All values will be converted to ints if possible.

magmap.io.cli.args_with_dict(args)

Parse arguments list with optional arguments given as dictionary-like elements.

Parameters:

args (List[str]) – List of arguments, which can be single values or “=” delimited values. Single values will be stored in the same order, while delimited entries will be entered sequentially into a dictionary. Entries can also be comma-delimited to specify lists.

Return type:

List[Union[Dict[str, Any], str, int]]

Returns:

List of arguments ordered first with single-value entries in the same order in which they were entered, followed by a dictionary with all equals-delimited entries, also in the same order as entered. Entries that contain commas will be split into comma-delimited lists. All values will be converted to ints if possible.

magmap.io.cli.main(process_args_only=False, skip_dbs=False)

Starts the visualization GUI.

Processes command-line arguments.

Parameters:

• process_args_only (bool, default: False) – Processes command-line arguments and returns; defaults to False.

• skip_dbs (bool, default: False) – True to skip loading databases; defaults to False.

magmap.io.cli.process_cli_args()

Parse command-line arguments.

Typically stores values as magmap.settings.config attributes.

magmap.io.cli.process_file(path, proc_type, proc_val=None, series=None, subimg_offset=None, subimg_size=None, roi_offset=None, roi_size=None)

Processes a single image file non-interactively.

Assumes that the image has already been set up.

Parameters:

• path (str) – Path to image from which MagellanMapper-style paths will be generated.

• proc_type (Enum) – Processing type, which should be a one of config.ProcessTypes.

• proc_val (Optional[Any], default: None) – Processing value associated with proc_type; defaults to None.

• series (Optional[int], default: None) – Image series number; defaults to None.

• subimg_offset (Optional[List[int]], default: None) – Sub-image offset as (z,y,x) to load; defaults to None.

• subimg_size (Optional[List[int]], default: None) – Sub-image size as (z,y,x) to load; defaults to None.

• roi_offset (Optional[List[int]], default: None) – Region of interest offset as (x, y, z) to process; defaults to None.

• roi_size (Optional[List[int]], default: None) – Region of interest size of region to process, given as (x, y, z); defaults to None.

Return type:

Tuple[Optional[Any], Optional[str]]

Returns:

Tuple of stats from processing, or None if no stats, and text feedback from the processing, or None if no feedback.

magmap.io.cli.process_proc_tasks(path=None, series_list=None)

Apply processing tasks.

Parameters:

• path (Optional[str], default: None) – Base path to main image file; defaults to None, in which case config.filename will be used.

• series_list (Optional[Sequence[int]], default: None) – Sequence of images series, such as tiles; defaults to None.

Return type:

Optional[Dict[ProcessTypes, Any]]

Returns:

Dictionary of set processing types.

magmap.io.cli.process_tasks()

Process command-line tasks.

Perform tasks set by the --proc parameter or any other entry point, such as --register tasks. Only the first identified task will be performed.

magmap.io.cli.setup_atlas_profiles(atlas_profiles_names, reset=True)

Set up atlas profiles.

If a profile is None, only a default set of profile settings will be generated. Any previously set up profile will be replaced.

Parameters:

• atlas_profiles_names (str) – Atlas profiles names.

• reset (bool, default: True) – True to reset profiles before setting profiles from atlas_profile_names; defaults to True.

magmap.io.cli.setup_dbs()

Set up databases for the given image file.

Only sets up each database if it has not been set up already.

magmap.io.cli.setup_grid_search_profiles(grid_search_profiles_names)

Setup grid search profiles.

If a profile is None, only a default set of profile settings will be generated. Any previously set up profile will be replaced.

Parameters:

grid_search_profiles_names (str) – Grid search profiles names.

magmap.io.cli.setup_image(path, series=None, proc_tasks=None)

Set up the main image from CLI args and process any tasks.

Parameters:

• path (str) – Image path.

• series (Optional[int], default: None) – Image series, such as a tile; defaults to None.

• proc_tasks (Optional[Dict[ProcessTypes, Any]], default: None) – Dictionary of processing tasks; defaults to None.

magmap.io.cli.setup_labels(labels_arg)

Set up atlas labels.

Parameters:

labels_arg (List[str]) – Path to labels reference file, such as a labels ontology file.

magmap.io.cli.setup_roi_profiles(roi_profiles_names)

Set up ROI profiles.

If a profile is None, only a default set of profile settings will be generated. Also sets up colormaps based on ROI profiles. Any previously set up profile will be replaced.

Parameters:

roi_profiles_names (List[str]) – Sequence of ROI and atlas profiles names to use for the corresponding channel.

magmap.io.cli.shutdown()

Clean up and shutdown MagellanMapper.

Stops any running Java virtual machine and closes any main database.

magmap.io.cli.update_profiles()

Update profiles if any profile file has been modified since it was last loaded.

Profiles in both config.process_settings_list and config.register_settings_list will be checked to update.