topostats.config
================

.. py:module:: topostats.config

.. autoapi-nested-parse::

   Functions and tools for working with configuration files.

   ..
       !! processed by numpydoc !!


Attributes
----------

.. autoapisummary::

   topostats.config.MutableMappingType
   topostats.config.LOGGER


Functions
---------

.. autoapisummary::

   topostats.config.reconcile_config_args
   topostats.config.update_module
   topostats.config.merge_mappings
   topostats.config.write_config_with_comments
   topostats.config.update_config
   topostats.config.update_plotting_config


Module Contents
---------------

.. py:data:: MutableMappingType

.. py:data:: LOGGER

.. py:function:: reconcile_config_args(args: argparse.Namespace | None) -> dict

   
   Reconcile command line arguments with the default configuration.

   Command line arguments take precedence over the default configuration. If a partial configuration file is specified
   (with '-c' or '--config-file') the defaults are over-ridden by these values (internally the configuration
   dictionary is updated with these values). Any other command line arguments take precedence over both the default
   and those supplied in a configuration file (again the dictionary is updated).

   The final configuration is validated before processing begins.

   :param args: Command line arguments passed into TopoStats.
   :type args: Namespace

   :returns: The configuration dictionary.
   :rtype: dict















   ..
       !! processed by numpydoc !!

.. py:function:: update_module(args: argparse.Namespace, topostats_modules: tuple = ('bruker-rename', 'create-config', 'curvature', 'disordered_tracing', 'filter', 'grains', 'grainstats', 'nodestats', 'ordered_tracing', 'process', 'splining')) -> None

   
   Update the `args.module` argument if processing TopoStats objects.

   This function allows the sub-parser command to map to the pipeline we wish to use. For now TopoStats has sub-parsers
   but it is the intention to introduce sub-sub-parsers for other modules such that eventually we invoke ``topostats```
   with a module argument followed by the step of processing.

   >>> topostats topostats filter
   >>> topostats topostats process
   >>> topostats afmslicer slice
   >>> topostats afmslicer process
   >>> topostats perovstats process

   :param args: Default arguments that need parsing and updating.
   :type args: Namespace
   :param topostats_modules: List of module names that are unique to TopoStats.
   :type topostats_modules: tuple















   ..
       !! processed by numpydoc !!

.. py:function:: merge_mappings(map1: MutableMappingType, map2: MutableMappingType) -> MutableMappingType

   
   Merge two mappings (dictionaries), with priority given to the second mapping.

   Note: Using a Mapping should make this robust to any mapping type, not just dictionaries. MutableMapping was needed
   as Mapping is not a mutable type, and this function needs to be able to change the dictionaries.

   :param map1: First mapping to merge, with secondary priority.
   :type map1: MutableMapping
   :param map2: Second mapping to merge, with primary priority.
   :type map2: MutableMapping

   :returns: Merged dictionary.
   :rtype: dict















   ..
       !! processed by numpydoc !!

.. py:function:: write_config_with_comments(args: argparse.Namespace = None) -> None

   
   Write a sample configuration with in-line comments.

   This function is not designed to be used interactively but can be, just call it without any arguments and it will
   write a configuration to './config.yaml'.

   :param args: A Namespace object parsed from argparse with values for 'filename'.
   :type args: Namespace















   ..
       !! processed by numpydoc !!

.. py:function:: update_config(config: dict, args: dict | argparse.Namespace) -> dict

   
   Update the configuration with any arguments.

   :param config: Dictionary of configuration (typically read from YAML file specified with '-c/--config <filename>').
   :type config: dict
   :param args: Command line arguments.
   :type args: Namespace

   :returns: Dictionary updated with command arguments.
   :rtype: dict















   ..
       !! processed by numpydoc !!

.. py:function:: update_plotting_config(plotting_config: dict) -> dict

   
   Update the plotting config for each of the plots in plot_dict.

   Ensures that each entry has all the plotting configuration values that are needed.

   :param plotting_config: Plotting configuration to be updated.
   :type plotting_config: dict

   :returns: Updated plotting configuration.
   :rtype: dict















   ..
       !! processed by numpydoc !!