Datacard

class audbcards.Datacard(dataset, *, path='datasets', example=True, sphinx_build_dir=None, sphinx_src_dir=None, template_dir=None, cache_root=None)

Datacard of a dataset.

The datacard object writes a RST file for a given dataset, which can then be used to generate an HTML datacard page using sphinx.

Parameters:

• dataset (Dataset) – dataset object

• path (str) – path to folder that store datacard files

• example (bool) – if True, include an audio or video example in the data card showing the waveform of the audio and an interactive player

• sphinx_build_dir (Optional[str]) – build dir of sphinx. If not None and example is True, a call to audbcards.Datacard.player() will store an example audio file under <sphinx_build_dir>/<path>/<dataset-name>/

• sphinx_src_dir (Optional[str]) – source dir of sphinx. If not None and example is True, a call to audbcards.Datacard.player() will store a waveform plot of the example audio file under <sphinx_src_dir>/<path>/<dataset-name>/

• template_dir (Optional[str]) – folder containing user defined template files. The following templates will overwrite default ones: datacard_description.j2, datacard_example.j2, datacard_header.j2, datacard.j2, datacard_schemes.j2, datacard_tables.j2, datasets.j2

• cache_root (Optional[str]) – cache folder. If None, the environmental variable AUDBCARDS_CACHE_ROOT, or audbcards.config.CACHE_ROOT is used

cache_root

Datacard.cache_root

Cache root folder.

content

Datacard.content

Property Accessor for rendered jinja2 content.

dataset

Datacard.dataset

Dataset object.

example

Datacard.example

If an audio example should be included.

file_duration_distribution

Datacard.file_duration_distribution

Minimum and maximum of files durations, and plotted distribution.

This generates a single line containing the mininimum and maximum values of files durations.

If audbcards.Datacard.sphinx_src_dir is not None (e.g. when used in the sphinx extension), and the dataset contains audio or video files, an image is stored in the file <dataset-name>-<dataset-version>-file-duration-distribution.png, which is cached in <cache-root>/<dataset-name>/<dataset-version>/ and copied to the sphinx source folder into <sphinx-src-dir>/<path><dataset-name>/. The image is displayed inline between the minimum and maximum values. If all duration values are the same, no distribution plot is created.

json()

Datacard.json()

Show content of a json file.

Return type:

str

Returns:

String containing RST code to include the json content as code

path

Datacard.path

Folder to store datacard.

player()

Datacard.player()

Create an audio/video player showing the waveform.

If audbcards.Datacard.sphinx_build_dir or audbcards.Datacard.sphinx_src_dir is not None, an example media file is cached in the folder <dataset-name>-<dataset-version>-player-media/ inside <cache-root>/<dataset-name>/<dataset-version>/, using the same sub-folder structure as the media file has inside its dataset. If audbcards.Datacard.sphinx_build_dir is not None, the media sub-folder structure is also copied to the sphinx build dir into <sphinx-build-dir>/<path>/<dataset-name>/, and an audio element referencing this file is added to the returned RST string.

If audbcards.Datacard.sphinx_src_dir is not None, a plot of the waveform of the media file is cached under <dataset-name>-<dataset-version>-player-waveform.png inside <cache-root>/<dataset-name>/<dataset-version>/. It is also copied to the sphinx source folder into <sphinx-src-dir>/<path>/<dataset-name>/, and referenced at the beginning of the returned RST string.

If audbcards.Datacard.sphinx_build_dir and audbcards.Datacard.sphinx_src_dir are None, an empty string is returned.

Return type:

str

Returns:

String containing RST code to include the player

rst_preamble

Datacard.rst_preamble

RST code added at top of data card.

save()

Datacard.save(file=None)

Save content of rendered template to rst.

Parameters:

file (Optional[str]) – name of output RST file. If None and audbcards.Datacard.sphinx_src_dir is not None, the RST file will be stored as <sphinx_src_dir>/<path>/<dataset>.rst

segment_duration_distribution

Datacard.segment_duration_distribution

Minimum and maximum of segment durations, and plotted distribution.

This generates a single line containing the mininimum and maximum values of segment durations.

If audbcards.Datacard.sphinx_src_dir is not None (e.g. when used in the sphinx extension), and the dataset contains segments, an image is stored in the file <dataset-name>-<dataset-version>-segment-duration-distribution.png, which is cached in <cache-root>/<dataset-name>/<dataset-version>/ and copied to the sphinx source folder into <sphinx-src-dir>/<path><dataset-name>/. The image is displayed inline between the minimum and maximum values. If all duration values are the same, no distribution plot is created.

sphinx_build_dir

Datacard.sphinx_build_dir

Sphinx build dir.

sphinx_src_dir

Datacard.sphinx_src_dir

Sphinx source dir.

template_dir

Datacard.template_dir

User defined template dir.