Niviz provides command-line utilities in order to generate reports and SVGs under the make_svgs.py script. See:

https://python-packaging.readthedocs.io/en/latest/command-line-scripts.html

https://setuptools.pypa.io/en/latest/userguide/entry_point.html

https://medium.com/nerd-for-tech/how-to-build-and-distribute-a-cli-tool-with-python-537ae41d9d78

For references!

This will also be useful for implementing our schema validator - related to #13

This relates to applying the global configuration settings to each FileSpec object. When a key is missing from a FileSpec configuration that is present in the global the intended behaviour is that the key defined in global gets inserted into the FileSpec configuration.

Currently this operation does not insert keys if missing i.e if:

bids_map:
   sub:
     regex: ABC

is defined under globals and the FileSpec bids_map is missing sub, then we should expect that sub gets inserted into a FileSpec's bids_map. But currently this is not the case.

The fix should be implemented in _nested_update in niviz/config.py to add keys when missing. In addition, only keys intended to be used in the FileSpec definition should be used, in which case we may need a FileSpec context (key) under global so we know which keys can be applied to FileSpec items.

pathlib is becoming the preferred way of handling filesystem paths in Python (https://docs.python.org/3/library/pathlib.html) as it provides a more natural API to handling and building system paths.

All niviz modules should switch over to using pathlib instead of os

Niviz uses a YAML configuration file in order to construct arguments for building images and outputting into a BIDS folder.

This YAML is expected to be structured in a certain way (enforced in code) but isn't explicitly encoded anywhere. This gap would be well-served by a YAML schema validator that is run as a first step (and is provided as separate functionality as a CLI tool packaged with Niviz).

https://github.com/23andMe/Yamale

Looks like an option

Currently, Niviz attempts to extract BIDS entities for every input into the filespecs: args.

However, this is inappropriate for plot config options and standard paths (i.e MNI templates) where we do not expect BIDS entities at all.

Currently, extract_bids_entities runs on all inputs and checks if any entities are defined, these are of two types:

1. dynamic entities that are pulled from filepaths
2. static entities that are to be shared (i.e defining a desc for an output SVG)

If neither dynamic or static entities are defined then extract_bids_entities will raise an error. Which is problematic because if no static entities are defined in the YAML, then nonpath items will always fail.

This should be remediated so that BIDS entities aren't checked for non-path args. Note that this may break things down the line, but we'll discover them as we go :)

Where to look

config.py:FileSpec.gen_args

Documentation should be updated with the following:

• docstrings should be updated for all interfaces and functions (see here for styling: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)
• ensure that modules/sub-modules are appearing properly in Github pages when pushes are made to repository
• Some getting started documentation with a simple example (perhaps using data from OSF or OpenNeuro?)