vocalpy.example

vocalpy.example(name: str, return_path: bool = False) → ExampleType

Get an example from vocalpy.examples.

To see all available example data, call vocalpy.examples.show().

Parameters:

namestr

Name of the example. To see names of examples and the associated metadata, call vocalpy.examples.show().

return_pathbool

If True, return the path to the example data. Default is False.

Returns:

examplepathlib.Path, vocalpy.Annotation, vocalpy.Sound, vocalpy.Spectrogram, list

By default, the path or a list of paths to the example data is returned. If return_type is specified, then an instance or list of instances of the corresponding VocalPy data type will be returned, e.g., a vocalpy.Sound instance with the example data read into it.

See also

vocalpy.examples.show

Notes

By default, local files will be cached in the directory given by vocalpy.example.get_cache_dir(). You can override this by setting an environment variable VOCALPY_DATA_DIR prior to importing VocalPy:

>>> import os
>>> os.environ['VOCALPY_DATA_DIR'] = '/path/to/store/data'
>>> import vocalpy as voc

Examples

>>> sound = voc.example('bells.wav')
>>> spect = voc.spectrogram(sound)
>>> voc.plot.spect(spect)

If you want the path(s) to where the data is on your local machine, set return_path to True. This is useful to demonstrate vocalpy functionality that loads files, or to work with the data in the files in some other way.

>>> sound_path = voc.example('bells.wav', return_path=True)
>>> sound = voc.Sound.read(sound_path)