render

Functions for rendering elements of the schema in the specification text.

bidsschematools.render.define_allowed_top_directories(schema, src_path=None) → str

Create a list of allowed top-level directories with their descriptions.

Parameters:

schema (dict) – The BIDS schema.
src_path (str or None) – The file where this macro is called, which may be explicitly provided by the “page.file.src_path” variable.

Returns:

string – Unordered list describing top level directories.

Return type:

str

bidsschematools.render.define_common_principles(schema, src_path=None)

Enumerate the common principles defined in the schema.

Parameters:

schema (dict) – The BIDS schema.
src_path (str or None) – The file where this macro is called, which may be explicitly provided by the “page.file.src_path” variable.

Returns:

string – The definitions of the common principles in a multiline string.

Return type:

str

bidsschematools.render.make_columns_table(schema: Namespace, table_name: str, src_path: str | None = None, tablefmt: str = 'github')

Produce columns table (markdown) based on requested fields.

Parameters:

schema (Namespace) – The BIDS schema.
table_name (str) – Qualified name in schema.rules.tabular_data. Only one table may be provided in this function.
src_path (str or None) – The file where this macro is called, which may be explicitly provided by the “page.file.src_path” variable.
tablefmt (string, optional) – The target table format. The default is “github” (GitHub format).

Returns:

table_str – The tabulated table as a Markdown string.

Return type:

str

bidsschematools.render.make_entity_definitions(schema, src_path=None)

Generate definitions and other relevant information for entities in the specification.

Each entity gets its own heading.

Parameters:: schema (dict) – The schema object, which is a dictionary with nested dictionaries and lists stored within it.
Returns:: text – A string containing descriptions and some formatting information about the entities in the schema.
Return type:: str

bidsschematools.render.make_entity_table(schema, tablefmt='github', src_path=None, **kwargs)

Produce entity table (markdown) based on schema.

Parameters:

schema_path (str) – Directory containing schema, which is stored in yaml files.
tablefmt (string, optional) – The target table format. The default is “github” (GitHub format).
src_path (str or None) – The file where this macro is called, which may be explicitly provided by the “page.file.src_path” variable.

Returns:

table_str – Markdown string containing the table.

Return type:

str

bidsschematools.render.make_filename_template(dstype, schema=None, src_path=None, n_dupes_to_combine=6, pdf_format=False, **kwargs)

Create codeblocks containing example filename patterns for a given datatype.

By default, this function uses HTML, instead of direct Markdown codeblocks, so that it can embed hyperlinks within the filenames.

Parameters:

dstype ("raw" or "deriv") – The type of files being rendered; determines if rules are found in rules.files.raw or rules.files.deriv
schema (dict) – The schema object, which is a dictionary with nested dictionaries and lists stored within it.
src_path (str or None) – The file where this macro is called, which may be explicitly provided by the “page.file.src_path” variable.
n_dupes_to_combine (int) – The minimum number of suffixes/extensions to combine in the template as <suffix>/<extension>.
pdf_format (bool, optional) – If True, the filename template will be compiled as a standard markdown code block, without any hyperlinks, so that the specification’s PDF build will look right. If False, the filename template will use HTML and include hyperlinks. This works on the website. Default is False.
**kwargs (dict) – Keyword arguments used to filter the schema. Example kwargs that may be used include: “suffixes”, “datatypes”, “extensions”.

Returns:

codeblock – A multiline string containing the filename templates for file types in the schema, after filtering.

Return type:

str

Notes

This function links to HTML files, rather than markdown files.

bidsschematools.render.make_glossary(schema, src_path=None)

Generate glossary.

Parameters:

schema (dict) – The schema object, which is a dictionary with nested dictionaries and lists stored within it.
src_path (str or None) – The file where this macro is called, which may be explicitly provided by the “page.file.src_path” variable.

Returns:

text – A string containing descriptions and some formatting information about the entities in the schema.

Return type:

str

bidsschematools.render.make_metadata_table(schema, field_info, src_path=None, tablefmt='github')

Produce metadata table (markdown) based on requested fields.

Parameters:

schema (Namespace) – The BIDS schema.
field_info (dict of strings or tuples) – A dictionary mapping metadata keys to requirement levels in the rendered metadata table. The dictionary values may be strings, in which case the string is the requirement level information, or two-item tuples of strings, in which case the first string is the requirement level information and the second string is additional table-specific information about the metadata field that will be appended to the field’s base definition from the schema.
src_path (str or None) – The file where this macro is called, which may be explicitly provided by the “page.file.src_path” variable.
tablefmt (string, optional) – The target table format. The default is “github” (GitHub format).

Returns:

table_str – The tabulated table as a Markdown string.

Return type:

str

bidsschematools.render.make_sidecar_table(schema: Namespace, table_name: str | List[str], src_path: str | None = None, tablefmt: str = 'github')

Produce metadata table (markdown) based on requested fields.

Parameters:

schema (Namespace) – The BIDS schema.
table_name (str or list of str) – Qualified name(s) in schema.rules.sidecars
src_path (str or None) – The file where this macro is called, which may be explicitly provided by the “page.file.src_path” variable.
tablefmt (string, optional) – The target table format. The default is “github” (GitHub format).

Returns:

table_str – The tabulated table as a Markdown string.

Return type:

str

bidsschematools.render.make_subobject_table(schema: Namespace, object_name: str, src_path: str | None = None, tablefmt: str = 'github')

Create a metadata table (markdown) based on the properties of an object

Parameters:

schema (Namespace) – The BIDS schema.
object_name (str) – Qualified name in schema.objects
src_path (str or None) – The file where this macro is called, which may be explicitly provided by the “page.file.src_path” variable.
tablefmt (string, optional) – The target table format. The default is “github” (GitHub format).

Returns:

table_str – The tabulated table as a Markdown string.

Return type:

str

bidsschematools.render.make_suffix_table(schema, suffixes, src_path=None, tablefmt='github')

Produce suffix table (markdown) based on requested suffixes.

Parameters:

schema (dict) –
suffixes (list of str) –
src_path (str or None) – The file where this macro is called, which may be explicitly provided by the “page.file.src_path” variable.
tablefmt (str) –

Returns:

table_str – Tabulated table as a string.

Return type:

str

schema

Schema loading- and processing-related functions.

exception bidsschematools.schema.BIDSSchemaError

Bases: Exception

Errors indicating invalid values in the schema itself

bidsschematools.schema.dereference(namespace, inplace=True)

Replace references in namespace with the contents of the referred object

Parameters:

namespace (Namespace) – Namespace for which to dereference
inplace (bool, optional) – Whether to modify the namespace in place or create a copy, by default True

Returns:

namespace – Deferred namespace

Return type:

Namespace

bidsschematools.schema.export_schema(schema)

Export the schema to JSON format.

Parameters:: schema (dict) – The schema object, in dictionary form.
Returns:: json – The schema serialized as a JSON string.
Return type:: str

bidsschematools.schema.filter_schema(schema, **kwargs)

Filter the schema based on a set of keyword arguments.

Parameters:

schema (dict) – The schema object, which is a dictionary with nested dictionaries and lists stored within it.
**kwargs (dict) – Keyword arguments used to filter the schema. Example kwargs that may be used include: “suffixes”, “datatypes”, “extensions”.

Returns:

new_schema – The filtered version of the schema.

Return type:

dict

Notes

This function calls itself recursively, in order to apply filters at arbitrary depth.

Warning

This function employs a very simple filter. It is very limited.

bidsschematools.schema.flatten_enums(namespace, inplace=True)

Replace enum collections with a single enum, merging enums contents.

The function helps reducing the complexity of the schema by assuming that the values in the conditions (anyOf) are mutually exclusive.

Parameters:

schema (dict) – Schema in dictionary form to be flattened.

Returns:

schema (dict) – Schema with flattened enums.
>>> struct = {
… “anyOf” ([)
… {“type” (“string”, “enum”: [“A”, “B”, “C”]},)
… {“type” (“string”, “enum”: [“D”, “E”, “F”]},)
… ]
… }
>>> flatten_enums(struct)
{‘type’ (‘string’, ‘enum’: [‘A’, ‘B’, ‘C’, ‘D’, ‘E’, ‘F’]})

bidsschematools.schema.load_schema(schema_path=None)

Load the schema into a dictionary.

This function allows the schema, like BIDS itself, to be specified in a hierarchy of directories and files. Filenames (minus extensions) and directory names become keys in the associative array (dict) of entries composed from content of files and entire directories.

Parameters:: schema_path (str, optional) – Directory containing yaml files or yaml file. If None, use the default schema packaged with bidsschematools.
Returns:: Schema in dictionary form.
Return type:: dict

Notes

This function is cached, so it will only be called once per schema path.

utils

Utility functions for the bids-specification schema.

bidsschematools.utils.get_bundled_schema_path()

Get the path to the schema directory.

Returns:: Absolute path to the directory containing schema-related files.
Return type:: str

bidsschematools.utils.get_logger(name=None)

Return a logger to use.

Parameters:: name (None or str, optional) – Name of the logger. Defaults to None.
Returns:: logger object.
Return type:: logging.Logger

bidsschematools.utils.set_logger_level(lgr, level)

Set the logger level.

Parameters:

lgr (logging.Logger) – logger object for which to change the level.
level (int or str) – The desired level for the logger.

validator

bidsschematools.validator.log_errors(validation_result)

Raise errors for validation result.

Parameters:: validation_result (dict) – A dictionary as returned by validate_all() with keys including “schema_tracking”, “path_tracking”, “path_listing”, and, optionally “itemwise”. The “itemwise” value, if present, should be a list of dictionaries, with keys including “path”, “regex”, and “match”.

bidsschematools.validator.select_schema_path(bids_version=None, bids_root=None, bids_reference_root=None)

Select schema directory, according to a priority logic whereby the schema path is either:

a concatenation of bids_reference_root and bids_version, if the latter is specified, and the BIDS version schema is compatible with the validator,

a concatenation of bids_reference_root the detected version specification inside the BIDS root directory, if such a directory is provided and the BIDS version schema is compatible with the validator.

None, expanded to the bundled schema supplied with the validator by bst.utils.get_bundled_schema_path.

Parameters:

bids_root (str or None, optional) – The path to the BIDS root for the paths to be validated.
bids_reference_root (str, optional) – Path where schema versions are stored, and which contains directories named exactly according to the respective schema version, e.g. “1.7.0”.
bids_version (str or None, optional) – BIDS version desired for validation. If empty, the dataset_description.json fie will be queried for the dataset schema version.

Returns:

A string which is a path to the selected schema directory.

Return type:

str

Notes

This is a purely aspirational function, and is pre-empted by logic inside
bst.validator.validate_bids(), and further contingent on better schema stability and ongoing work in: https://github.com/bids-standard/bids-schema
The default bids_reference_root value is based on the FHS and ideally should be enforced.
Alternatively this could be handled by an environment variable, though that also requires enforcement on the package distribution side.

bidsschematools.validator.validate_all(paths_list, regex_schema)

Validate bids_paths based on a regex_schema dictionary list, including regexes.

Parameters:

bids_paths (list or str) – A string pointing to a BIDS directory for which paths should be validated, or a list of strings pointing to individual files or subdirectories which all reside within one and only one BIDS directory root (i.e. nested datasets should be validated separately).
regex_schema (list of dict) – A list of dictionaries as generated by regexify_all().

Returns:

results – A dictionary reporting the target files for validation, the unmatched files and unmatched regexes, and optionally the itemwise comparison results. Keys include “schema_tracking”, “path_tracking”, “path_listing”, “match_listing”, and optionally “itemwise”

Return type:

dict

Notes

Multi-source validation could be accomplished by distributing the resulting tracking_schema
dictionary and further eroding it.
Currently only entities are captured in named groups, edit load_top_level() to name other
groups as well.

bidsschematools.validator.validate_bids(in_paths, dummy_paths=False, bids_reference_root=None, schema_path=None, bids_version=None, report_path=False, suppress_errors=False, accept_non_bids_dir=False, exclude_files=[])

Validate paths according to BIDS schema.

Parameters:

in_paths (str or list of str) – Paths which to validate, may be individual files or directories.
dummy_paths (bool, optional) – Whether to accept path strings which do not correspond to either files or directories.
bids_reference_root (str, optional) – Path where schema versions are stored, and which contains directories named exactly according to the respective schema version, e.g. “1.7.0”. Currently this is untested.
bids_version (str or None, optional) – Version of BIDS schema, or path to schema. This supersedes the specification detected in dataset_description.json and is itself superseded if schema_path is specified.
schema_path (str or None, optional) – If a path is given, this will be expanded and used directly, ignoring all other BIDS version specification logic. This is not relative to bids_reference_root.
report_path (bool or str, optional) – If True a log will be written using the standard output path of .write_report(). If string, the string will be used as the output path. If the variable evaluates as False, no log will be written.
accept_non_bids_dir (bool, optional) –
exclude_files (str, optional) – Files which will not be indexed for validation, use this if your data is in an archive standard which requires the presence of archive-specific files (e.g. DANDI requiring dandiset.yaml). Dot files (.*) do not need to be explicitly listed, as these are excluded by default.

Returns:

results – A dictionary reporting the target files for validation, the unmatched files and unmatched regexes, and optionally the itemwise comparison results. Keys include “schema_tracking”, “path_tracking”, “path_listing”, “match_listing”, and optionally “itemwise”

Return type:

dict

Examples

from bidsschematools import validator
bids_paths = '~/.data2/datalad/000026/rawdata'
validator.validate_bids(bids_paths)

Notes

Needs to account for inheritance principle, probably somewhere deeper in the logic, might be
as simple as pattern parsing and multiplying patterns to which inheritance applies. https://github.com/bids-standard/bids-specification/pull/969#issuecomment-1132119492

bidsschematools.validator.write_report(validation_result, report_path='~/.cache/bidsschematools/validator-report_{datetime}-{pid}.log', datetime_format='%Y%m%d%H%M%SZ')

Write a human-readable report based on the validation result.

Parameters:

validation_result (dict) – A dictionary as returned by validate_all() with keys including “schema_tracking”, “path_tracking”, “path_listing”, and, optionally “itemwise”. The “itemwise” value, if present, should be a list of dictionaries, with keys including “path”, “regex”, and “match”.
report_path (str, optional) – A path under which the report is to be saved, datetime, and pid are available as variables for string formatting, and will be expanded to the current datetime (as per the datetime_format parameter) and process ID, respectively.
datetime_format (str, optional) – A datetime format, optionally used for the report path.

Notes

Not using f-strings in order to prevent arbitrary code execution.

render

schema

utils

validator

types