bidsschematools.render.utils

Utility functions for specification rendering tools.

Functions

bidsschematools.render.utils.combine_extensions(lst, html_path=None, heading_lst=None, pdf_format=True)

Combine extensions with their compressed versions in a list.

Valid combinations are hardcoded in the function, since some extensions look like compressed versions of one another, but are not.

Parameters:

• lst (list of str) – Raw list of extensions.

• html_path (None or str) – Path to the HTML file that each extension should link to. Only used if pdf_format is False. Default is None.

• heading_lst (None or list of str) – List of headings in the HTML page to link to. Should be one heading for each extension in lst. Only used if pdf_format is False. Default is None.

• pdf_format (bool, optional) – If True, the extensions will be compiled as markdown strings, without any hyperlinks, so that the specification’s PDF build will look right. If False, the extensions will use HTML and include hyperlinks to the their associated glossary entries. This works on the website. Default is True.

Returns:

new_lst – List of extensions, with compressed and uncompressed versions of the same extension combined.

Return type:

list of str

bidsschematools.render.utils.describe_valid_values(definition)

Build a sentence describing valid values for an object from its definition.

This only covers booleans, enums, integers, and numbers. Currently uncovered are anyOfs, arrays, and objects.

Parameters:

definition (dict) – An object definition, following the BIDS schema object rules.

Returns:

str

Return type:

A sentence describing valid values for the object.

bidsschematools.render.utils.drop_unused_entities(df)

Remove columns from a dataframe where all values in the column are NaNs.

For entity tables, this limits each table to only entities that are used within the modality.

Parameters:

df (pandas.DataFrame) – DataFrame containing entities and datatypes/suffixes. Rows are datatype/suffix combinations and columns are entities.

Returns:

df – DataFrame with columns associated with unused entities removed.

Return type:

pandas.DataFrame

bidsschematools.render.utils.flatten_multiindexed_columns(df)

Remove multi-indexing of multi-indexed column headers.

The first layer is the “DataType”, while the second layer is the “Format”. This second layer will become a new row.

Parameters:

df (pandas.DataFrame) – DataFrame with two header levels: “Datatype” and “Format”.

Returns:

df – DataFrame with the second header level (“Format”) converted to a normal row.

Return type:

pandas.DataFrame

bidsschematools.render.utils.get_link(string)

Return a hyperlink to the JSON specification for a given JSON type.

Parameters:

string (str) – The JSON type to link to.

Returns:

url – The hyperlink to the JSON specification for the given JSON type.

Return type:

str

bidsschematools.render.utils.get_relpath(src_path)

Retrieve relative path to the source root from the perspective of a Markdown file.

As a convenience, None is interpreted as the empty string, and a value of '.' is returned.

Examples

>>> get_relpath("02-common-principles.md")
'.'
>>> get_relpath("04-modality-specific-files/01-magnetic-resonance-imaging-data.md")
'..'
>>> get_relpath("we/lack/third_levels.md")
'../..'
>>> get_relpath(None)
'.'

bidsschematools.render.utils.normalize_breaks(text)

Normalize line breaks in a string, for new lines, escaped new lines and double new lines.

Parameters:

text (str)

Returns:

text

Return type:

str

bidsschematools.render.utils.normalize_requirements(text)

Normalize requirements wording in a string.

Parameters:

text (str)

Returns:

text

Return type:

str

bidsschematools.render.utils.num2words(integer, to='ordinal')

Convert integers to words.

This is a very simplistic mapping of numbers to words, to avoid adding num2words to our requirements. It only works with the first few numbers.

Parameters:

• integer (int)

• to ({"ordinal", "cardinal"}, optional)

Returns:

word

Return type:

str

bidsschematools.render.utils.resolve_metadata_type(definition)

Generate string of metadata type from dictionary.

Parameters:

definition (dict) – A schema object definition for a metadata term.

Returns:

string – A string describing the valid value types for the metadata term.

Return type:

str