topostats.processing#

Functions for processing data.

Attributes#

LOGGER

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.

Module Contents#

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[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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][source]#

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[source]#

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[source]#

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.