topostats.processing

Functions for processing data.

Module Contents

Functions

run_filters(→ numpy.ndarray | None)	Filter and flatten an image. Optionally plots the results, returning the flattened image.
run_grains(image, pixel_to_nm_scaling, filename, ...)	Identify grains (molecules) and optionally plots the results.
run_grainstats(image, pixel_to_nm_scaling, ...)	Calculate grain statistics for an image and optionally plots the results.
run_dnatracing(image, grain_masks, ...[, results_df])	Trace DNA molecule for the supplied grains adding results to statistics data frames and optionally plot results.
get_out_paths(image_path, base_dir, output_dir, ...)	Determine components of output paths for a given image and plotting config.
process_scan(→ tuple[dict, pandas.DataFrame, dict])	Process a single image, filtering, finding grains and calculating their statistics.
check_run_steps(→ None)	Check options for running steps (Filter, Grain, Grainstats and DNA tracing) are logically consistent.
completion_message(→ None)	Print a completion message summarising images processed.

Attributes

LOGGER

topostats.processing.LOGGER

topostats.processing.run_filters(unprocessed_image: numpy.ndarray, pixel_to_nm_scaling: float, filename: str, filter_out_path: pathlib.Path, core_out_path: pathlib.Path, filter_config: dict, plotting_config: dict) → numpy.ndarray | None

Filter and flatten an image. Optionally plots the results, returning the flattened image.

Parameters:

• unprocessed_image (np.ndarray) – Image to be flattened.

• pixel_to_nm_scaling (float) – Scaling factor for converting pixel length scales to nanometres. ie the number of pixels per nanometre.

• filename (str) – File name for the image.

• filter_out_path (Path) – Output directory for step-by-step flattening plots.

• core_out_path (Path) – General output directory for outputs such as the flattened image.

• filter_config (dict) – Dictionary of configuration for the Filters class to use when initialised.

• plotting_config (dict) – Dictionary of configuration for plotting output images.

Returns:

Either a numpy array of the flattened image, or None if an error occurs or flattening is disabled in the configuration.

Return type:

Union[np.ndarray, None]

topostats.processing.run_grains(image: numpy.ndarray, pixel_to_nm_scaling: float, filename: str, grain_out_path: pathlib.Path, core_out_path: pathlib.Path, plotting_config: dict, grains_config: dict)

Identify grains (molecules) and optionally plots the results.

Parameters:

• image (np.ndarray) – 2d numpy array image to find grains in.

• pixel_to_nm_scaling (float) – Scaling factor for converting pixel length scales to nanometres. I.e. the number of pixels per nanometre.

• filename (str) – Name of file being processed (used in logging).

• grain_out_path (Path) – Output path for step-by-step grain finding plots.

• core_out_path (Path) – General output directory for outputs such as the flattened image with grain masks overlaid.

• plotting_config (dict) – Dictionary of configuration for plotting images.

• grains_config (dict) – Dictionary of configuration for the Grains class to use when initialised.

Returns:

Either None in the case of error or grain finding being disabled or a dictionary with keys of “above” and or “below” containing binary masks depicting where grains have been detected.

Return type:

Union[dict, None]

topostats.processing.run_grainstats(image: numpy.ndarray, pixel_to_nm_scaling: float, grain_masks: dict, filename: str, grainstats_config: dict, plotting_config: dict, grain_out_path: pathlib.Path)

Calculate grain statistics for an image and optionally plots the results.

Parameters:

• image (np.ndarray) – 2D numpy array image for grain statistics calculations.

• pixel_to_nm_scaling (float) – Scaling factor for converting pixel length scales to nanometres. ie the number of pixels per nanometre.

• grain_masks (dict) – Dictionary of grain masks, keys “above” or “below” with values of 2d numpy boolean arrays indicating the pixels that have been masked as grains.

• filename (str) – Name of the image.

• grainstats_config (dict) – Dictionary of configuration for the GrainStats class to be used when initialised.

• plotting_config (dict) – Dictionary of configuration for plotting images.

• grain_out_path (Path) – Directory to save optional grain statistics visual information to.

Returns:

A pandas DataFrame containing the statsistics for each grain. The index is the filename and grain number.

Return type:

pd.DataFrame

topostats.processing.run_dnatracing(image: numpy.ndarray, grain_masks: dict, pixel_to_nm_scaling: float, image_path: pathlib.Path, filename: str, core_out_path: pathlib.Path, grain_out_path: pathlib.Path, dnatracing_config: dict, plotting_config: dict, results_df: pandas.DataFrame = None)

Trace DNA molecule for the supplied grains adding results to statistics data frames and optionally plot results.

Parameters:

• image (np.ndarray) – Image containing the DNA to pass to the dna tracing function.

• grain_masks (dict) – Dictionary of grain masks, keys “above” or “below” with values of 2d numpy boolean arrays indicating the pixels that have been masked as grains.

• pixel_to_nm_scaling (float) – Scaling factor for converting pixel length scales to nanometres. ie the number of pixels per nanometre.

• image_path (Path) – Path to the image file. Used for DataFrame indexing.

• filename (str) – Name of the image.

• core_out_path (Path) – General output directory for outputs such as the grain statistics DataFrame.

• grain_out_path (Path) – Directory to save optional dna tracing visual information to.

• dnatracing_config (dict) – Dictionary configuration for the dna tracing function.

• plotting_config (dict) – Dictionary configuration for plotting images.

• results_df (pd.DataFrame) – Pandas DataFrame containing grain statistics.

Returns:

Pandas DataFrame containing grain statistics and dna tracing statistics. Keys are file path and molecule number.

Return type:

pd.DataFrame

topostats.processing.get_out_paths(image_path: pathlib.Path, base_dir: pathlib.Path, output_dir: pathlib.Path, filename: str, plotting_config: dict)

Determine components of output paths for a given image and plotting config.

Parameters:

• image_path (Path) – Path of the image being processed.

• base_dir (Path) – Path of the data folder.

• output_dir (Path) – Base output directory for output data.

• filename (str) – Name of the image being processed.

• plotting_config (dict) – Dictionary of configuration for plotting images.

Returns:

Core output path for general file outputs, filter output path for flattening related files and grain output path for grain finding related files.

Return type:

tuple

topostats.processing.process_scan(topostats_object: dict, base_dir: str | pathlib.Path, filter_config: dict, grains_config: dict, grainstats_config: dict, dnatracing_config: dict, plotting_config: dict, output_dir: str | pathlib.Path = 'output') → tuple[dict, pandas.DataFrame, dict]

Process a single image, filtering, finding grains and calculating their statistics.

Parameters:

• topostats_object (dict[str, Union[np.ndarray, Path, float]]) – A dictionary with keys ‘image’, ‘img_path’ and ‘px_2_nm’ containing a file or frames’ image, it’s path and it’s pixel to namometre scaling value.

• base_dir (Union[str, Path]) – Directory to recursively search for files, if not specified the current directory is scanned.

• filter_config (dict) – Dictionary of configuration options for running the Filter stage.

• grains_config (dict) – Dictionary of configuration options for running the Grain detection stage.

• grainstats_config (dict) – Dictionary of configuration options for running the Grain Statistics stage.

• dnatracing_config (dict) – Dictionary of configuration options for running the DNA Tracing stage.

• plotting_config (dict) – Dictionary of configuration options for plotting figures.

• output_dir (Union[str, Path]) – Directory to save output to, it will be created if it does not exist. If it already exists then it is possible that output will be over-written.

Returns:

TopoStats dictionary object, DataFrame containing grain statistics and dna tracing statistics, and dictionary containing general image statistics.

Return type:

tuple[dict, pd.DataFrame, dict]

topostats.processing.check_run_steps(filter_run: bool, grains_run: bool, grainstats_run: bool, dnatracing_run: bool) → None

Check options for running steps (Filter, Grain, Grainstats and DNA tracing) are logically consistent.

This checks that earlier steps required are enabled.

Parameters:

• filter_run (bool) – Flag for running Filtering.

• grains_run (bool) – Flag for running Grains.

• grainstats_run (bool) – Flag for running GrainStats.

• dnatracing_run (bool) – Flag for running DNA Tracing.

topostats.processing.completion_message(config: dict, img_files: list, summary_config: dict, images_processed: int) → None

Print a completion message summarising images processed.

Parameters:

• config (dict) – Configuration dictionary.

• img_files (list()) – List of found image paths.

• summary_config (dict() – Configuration for plotting summary statistics.

• images_processed (int) – Pandas DataFrame of results.