API Reference#

This section documents the vak API.

Command Line Interface#

The vak.cli module implements the vak command line interface.

`cli.cli`
`cli.eval`
`cli.learncurve`
`cli.predict`
`cli.prep`	Function called by command-line interface for prep command
`cli.train`

Commands#

These high-level functions correspond to commands in the commmand-line interface. The commands are to prepare datasets, train and evaluate models, and generate predictions from trained models.

Prep#

`prep`
`prep.frame_classification`
`prep.parametric_umap`
`prep.spectrogram_dataset`	Functions for preparing a dataset for neural network models from a dataset of spectrograms.
`prep.unit_dataset`
`prep.audio_dataset`
`prep.constants`	Constants used by `vak.prep`.
`prep.dataset_df_helper`	Helper functions for working with datasets represented as a pandas.DataFrame
`prep.prep_`
`prep.sequence_dataset`	Helper functions for datasets annotated as sequences.

Train-test-validation splits of datasets#

The vak.split module contains functionality for generating train-validation-test splits from datasets. It is called by the vak.prep function when running vak prep through the command line interface.

`prep.split.algorithms.bruteforce`
`prep.split.algorithms.validate`
`prep.split.split`	Functions for creating splits of datasets used with neural network models, such as the standard train-val-test splits used with supervised learning methods.

Train#

`train.train_`	High-level function that trains models.
`train.frame_classification`	Function that trains models in the frame classification family.
`train.parametric_umap`	Function that trains models in the Parametric UMAP family.

Eval#

`eval.eval_`	High-level function that evaluates trained models.
`eval.frame_classification`	Function that evaluates trained models in the frame classification family.
`eval.parametric_umap`	Function that evaluates trained models in the parametric UMAP family.

Predict#

`predict.predict_`	High-level function that generates new inferences from trained models.
`predict.frame_classification`	Function that generates new inferences from trained models in the frame classification family.
`predict.parametric_umap`	Function that generates new inferences from trained models in the frame classification family.

Learning Curve#

`learncurve.curvefit`	"code to fit learning curves adapted from https://github.com/NickleDave/learning-curves/
`learncurve.dirname`	Helper functions that return names of directories generated during a run of a learning curve.
`learncurve.frame_classification`	Function that generates results for a learning curve for frame classification models.
`learncurve.learncurve`	High-level function that generates results for a learning curve for all models.

Configuration files#

The vak.config module contains functions to parse the TOML configuration files used with vak, and dataclasses that represent tables from those files.

`config.config`
`config.eval`	parses [EVAL] section of config
`config.learncurve`	parses [LEARNCURVE] section of config
`config.model`
`config.parse`
`config.predict`	parses [PREDICT] section of config
`config.prep`	parses [PREP] section of config
`config.spect_params`	parses [SPECT_PARAMS] section of config
`config.train`	parses [TRAIN] section of config
`config.validators`	validators used by attrs-based classes and by vak.parse.parse_config

Datasets#

The vak.datasets module contains datasets built into vak.

`datasets.frame_classification`
`datasets.parametric_umap`

Metrics#

The vak.metrics module contains metrics used when evaluating neural network model performance.

`metrics.classification.classification`
`metrics.classification.functional`
`metrics.distance.distance`
`metrics.distance.functional`

Models#

The vak.models module contains models built into vak, and functions for working with models: declaring them via definition, registering them as one of a family of models, getting a model instance for training, predicting, etc.

`models.base`	Base class for a model in `vak`, that other families of models should subclass.
`models.convencoder_umap`	Parametric UMAP model, as described in [1]_, with a convolutional network as the encoder.
`models.decorator`	Decorator that makes a model class, given a definition of the model, and another class that represents a family of models that the new model belongs to.
`models.definition`	Code that handles classes that represent the definition of a neural network model; the abstraction of how models are declared with code in vak.
`models.ed_tcn`
`models.frame_classification_model`	A LightningModule that represents a task where a model predicts a label for each frame in a time series, e.g., each time bin in a window from a spectrogram.
`models.get`(name, config, input_shape[, ...])	Get a model instance, given its name and a configuration as a `dict`.
`models.parametric_umap_model`	Parametric UMAP model, as described in [1]_.
`models.registry`	Registry for models.
`models.tweetynet`	TweetyNet model [1]_.

Nets#

The vak.nets module contains neural network architectures built into vak. All models include a neural network architecture (along with an optimizer, loss function, and metrics).

`nets.conv_encoder`
`nets.ed_tcn`
`nets.tweetynet`	TweetyNet model

Neural Network Layers and Operations#

The vak.nn module contains operations, layers, and other graph components used in neural network architectures.

`nn.loss`
`nn.functional`

Plotting#

Functions for plotting that are built in to vak live in the vak.plot module.

`plot.annot`	functions for plotting annotations for vocalizations
`plot.learncurve`	functions to plot learning curve results
`plot.spect`(s, t, f[, tlim, flim, ax, ...])	plot spectrogram

Transforms#

The vak.transforms module contains transforms that can be applied to input or output of neural networks, i.e., for pre-processing or post-processing.

`transforms.defaults`
`transforms.frame_labels.functional`	Functional forms of transformations related to frame labels, i.e., vectors where each element represents a label for a frame, either a single sample in audio or a single time bin from a spectrogram.
`transforms.frame_labels.transforms`	Class forms of transformations related to frame labels, i.e., vectors where each element represents a label for a frame, either a single sample in audio or a single time bin from a spectrogram.
`transforms.functional`
`transforms.transforms`

Common#

This module contains helper functions used by multiple other modules.

`common.annotation`
`common.constants`	constants used by multiple modules.
`common.converters`
`common.device`
`common.files`
`common.labels`
`common.learncurve`
`common.logging`	utility functions for logging
`common.paths`	functions for working with paths
`common.tensorboard`	Functions dealing with `tensorboard`
`common.timebins`	module for functions that deal with vector of times from a spectrogram, i.e. where elements are the times at bin centers.
`common.timenow`
`common.trainer`
`common.typing`
`common.validators`	Functions for input validation