API reference

fastabx.zerospeech_abx(item, root, *, max_size_group, max_x_across=<object object>, speaker='within', context='within', distance='angular', frequency=50, feature_maker=<function load>, extension='.pt', seed=0)

Compute the ABX similarly to the ZeroSpeech 2021 challenge.

On triphone or phoneme, described by an item file. Within or across speaker, and within context or ignoring context.

Parameters:

• item (str | Path) – Path to the item file.

• root (str | Path) – Path to the root directory containing either the features or the audio files.

• max_size_group (int | None) – Maximum number of instances of A, B, or X in each Cell. Passed to the Subsampler of the Task. Set to 10 in the original ZeroSpeech ABX code. Required; disabled if set to None.

• max_x_across (int | None) – In the “across” speaker mode, maximum number of X considered for given values of A and B. Passed to the Subsampler of the Task. Set to 5 in the original ZeroSpeech ABX code. Required when speaker="across" (pass None explicitly to disable it); ignored otherwise.

• speaker (Literal['within', 'across']) – The speaker mode, either “within” or “across”. Defaults to “within”.

• context (Literal['within', 'any']) – The context mode, either “within” or “any”. Always use “within” with representations of triphones. Defaults to “within”.

• distance (DistanceName) – The distance metric, “angular” (same as “cosine”), “euclidean”, “kl_symmetric” or “identical”. Defaults to “angular”.

• frequency (int) – The feature frequency of the features / the output of the feature maker, in Hz. Defaults to 50 Hz.

• feature_maker (Callable[[str | Path], Tensor]) – Function that takes a path and returns a torch.Tensor. Defaults to torch.load.

• extension (str) – The filename extension of the files to process in root, default is “.pt”.

• seed (int) – The random seed for the subsampling, default is 0.

Return type:

float

Standard classes and functions

Dataset

class fastabx.Dataset(labels, accessor)

Simple interface to a dataset.

Parameters:

• labels (DataFrame) – pl.DataFrame containing the labels of the datapoints.

• accessor (InMemoryAccessor) – InMemoryAccessor to access the data.

classmethod from_dataframe(source, feature_columns, *, separator=',')

Create a dataset from any tabular source containing both the labels and the features.

Accepted inputs for source:

• str or Path: path to a CSV file (uses separator).

• A polars or pandas DataFrame.

• Mapping[str, Sequence] (column name → values).

• Iterable[Mapping] (sequence of row dictionaries).

Parameters:

• source (str | Path | DataFrame | Mapping[str, Sequence[object]] | Iterable[Mapping[str, Any]]) – The tabular source. See above for accepted types.

• feature_columns (str | Collection[str]) – Column name or list of column names containing the features.

• separator (str) – Separator used in the CSV file. Only relevant when source is a path.

Return type:

Dataset

classmethod from_item(item, root, frequency, *, feature_maker=<function load>, extension='.pt', file_col='#file', onset_col='onset', offset_col='offset')

Create a dataset from an item file.

If you want to keep the Libri-Light bug to reproduce previous results, set the environment variable FASTABX_WITH_LIBRILIGHT_BUG=1.

Parameters:

• item (str | Path) – Path to the item file.

• root (str | Path) – Path to the root directory containing either the features or the audio files.

• frequency (int | str | Decimal) – The feature frequency of the features / the output of the feature maker, in Hz. If it is not an integer, pass it as a string to avoid floating-point errors.

• feature_maker (Callable[[str | Path], Tensor]) – Function that takes a path and returns a torch.Tensor. Defaults to torch.load.

• extension (str) – The filename extension of the files to process in root, default is “.pt”.

• file_col (str) – Column in the item file that contains the audio file names, default is “#file”.

• onset_col (str) – Column in the item file that contains the onset times, default is “onset”.

• offset_col (str) – Column in the item file that contains the offset times, default is “offset”.

Return type:

Dataset

classmethod from_item_and_units(item, units, frequency, *, audio_key='audio', units_key='units', file_col='#file', onset_col='onset', offset_col='offset')

Create a dataset from an item file with the units all described in a single JSONL file.

Parameters:

• item (str | Path) – Path to the item file.

• units (str | Path) – Path to the JSONL file containing the units.

• frequency (int | str | Decimal) – The feature frequency, in Hz. If it is not an integer, pass it as a string to avoid floating-point errors.

• audio_key (str) – Key in the JSONL file that contains the audio file names (str), default is “audio”.

• units_key (str) – Key in the JSONL file that contains the units (list[int]), default is “units”.

• file_col (str) – Column in the item file that contains the audio file names, default is “#file”.

• onset_col (str) – Column in the item file that contains the onset times, default is “onset”.

• offset_col (str) – Column in the item file that contains the offset times, default is “offset”.

Return type:

Dataset

classmethod from_item_with_times(item, root_features, root_times, *, feature_maker=<function load>, time_maker=<function load>, extension='.pt', file_col='#file', onset_col='onset', offset_col='offset')

Create a dataset from an item file.

Use arrays containing the times associated to the features instead of a given frequency.

Parameters:

• item (str | Path) – Path to the item file.

• root_features (str | Path) – Path to the root directory containing either the features or the audio files.

• root_times (str | Path) – Path to the root directory containing the times arrays.

• feature_maker (Callable[[str | Path], Tensor]) – Function that takes a path and returns a torch.Tensor. Defaults to torch.load.

• time_maker (Callable[[str | Path], Tensor]) – Function that takes a path and returns a 1D torch.Tensor. Defaults to torch.load.

• extension (str) – The filename extension of the files to process in root_features and root_times, default is “.pt”.

• file_col (str) – Column in the item file that contains the audio file names, default is “#file”.

• onset_col (str) – Column in the item file that contains the onset times, default is “onset”.

• offset_col (str) – Column in the item file that contains the offset times, default is “offset”.

Return type:

Dataset

classmethod from_numpy(features, labels)

Create a dataset from the features and the labels.

Despite the name, features is not restricted to a numpy array: any input accepted by np.asarray works (Python lists, tuples, CPU torch tensors via the __array__ protocol, …). CUDA tensors must be moved to CPU first.

Parameters:

• features (ArrayLike) – 2D array-like containing the features.

• labels (DataFrame | Mapping[str, Sequence[object]]) – Dictionary of sequences, or polars/pandas DataFrame containing the labels.

Return type:

Dataset

normalize_()

L2 normalization of the data. Idempotent: a second call is a no-op.

Return type:

Self

class fastabx.InMemoryAccessor(indices, data)

Data accessor where everything is in memory.

Parameters:

• indices (dict[int, tuple[int, int]])

• data (Tensor)

class fastabx.Batch(data, sizes)

Batch of padded data.

Parameters:

• data (Tensor)

• sizes (Tensor)

Task

class fastabx.Task(dataset, *, on, by=None, across=None, subsampler=None)

The ABX task class.

A Task builds all the Cell given on, by and across conditions. It can be subsampled to limit the number of cells.

To bypass the standard construction with a precomputed cells DataFrame, use Task.from_cells instead.

Parameters:

• dataset (Dataset) – The dataset containing the features and the labels.

• on (str) – The on condition.

• by (list[str] | None) – The list of by conditions.

• across (list[str] | None) – The list of across conditions.

• subsampler (Subsampler | None) – An optional subsampler to limit the number of cells and their sizes.

property cells: DataFrame

Read-only view of the task’s cells.

classmethod from_cells(dataset, cells, *, is_symmetric)

Build a Task from a precomputed cells DataFrame.

Use this when you have hardcoded your own triplets and want to skip the standard on/by/across construction. The DataFrame must carry the columns expected by Task.__iter__: header, description, index_a, index_b, index_x.

Parameters:

• dataset (Dataset) – The dataset containing the features and the labels.

• cells (DataFrame) – The precomputed cells DataFrame.

• is_symmetric (bool) – Whether each cell’s A and X share the same rows (no across condition).

Return type:

Task

Subsample

class fastabx.Subsampler(max_size_group, max_x_across, seed=0)

Subsample the ABX Task.

Each cell is limited to max_size_group items for A, B and X independently. When using “across” conditions, each group of (A, B) is limited to max_x_across possible values for X. Subsampling for one or more conditions can be disabled by setting the corresponding argument to None.

Parameters:

• max_size_group (int | None) – Maximum number of instances of A, B, or X in each Cell. Set to 10 in the original ZeroSpeech ABX code. Disabled if set to None.

• max_x_across (int | None) – In the “across” speaker mode, maximum number of X considered for given values of A and B. Set to 5 in the original ZeroSpeech ABX code. Disabled if set to None.

• seed (int) – The random seed for the subsampling, default is 0.

Score

class fastabx.Score(task, distance_name, *, constraints=None)

Compute the score of a Task using a given distance specified by distance_name.

Additional Constraints can be provided to restrict the possible triplets in each cell.

The full scoring runs eagerly in __init__: constructing a Score is the expensive step, and collapse/details afterwards are cheap.

Warning

Constructing a Score with the "cosine"/"angular" distance mutates the shared task.dataset in place: it L2-normalizes the features and appends the singularity-border column, so the dataset’s feature dimension grows by one and task.dataset.accessor.is_normalized becomes True. If you need the original features back, keep a separate, un-normalized Dataset.

Parameters:

• task (Task) – The Task to score.

• distance_name (DistanceName) – Name of the distance, “angular” (same as “cosine”), “euclidean”, “kl_symmetric” or “identical”. Defaults to “angular”.

• constraints (Constraints | None) – Optional constraints to restrict the possible triplets.

property cells: DataFrame

Return the scored cells.

collapse(*, levels=None, weighted=False)

Collapse the scored cells into the final score.

Use either levels or weighted=True to collapse the scores.

Parameters:

• levels (Sequence[tuple[str, ...] | str] | None) – List of levels to collapse. The order matters a lot.

• weighted (bool) – Whether to collapse the scores using a mean weighted by the size of the cells.

Return type:

float

details(*, levels=None)

Collapse the scored cells and return the final scores and sizes for each (A, B) pairs.

Parameters:

levels (Sequence[tuple[str, ...] | str] | None) – List of levels to collapse. The order matters a lot.

Return type:

DataFrame

write_csv(file)

Write the results of all the cells to a CSV file.

Nested list columns (the per-cell index_a/index_b/index_x) are dropped, since CSV cannot represent them. Use self.cells directly to keep them.

Parameters:

file (str | Path) – Path to the output CSV file.

Return type:

None

Advanced

Pooling

Pooling collapses the frame-level features of each token into a single vector, so that every token is represented by one fixed-size embedding instead of a variable-length sequence. This is useful when you want token-level (rather than frame-level) representations: the comparison no longer relies on DTW, which makes the distance computation faster. Two methods are available: "mean" averages the frames, and "hamming" averages them using a Hamming window (giving less weight to the boundary frames).

fastabx.pool_dataset(dataset, pooling_name)

Pool the Dataset using the pooling method given by pooling_name.

The pooled dataset is a new one, with data stored in memory. For simplicity, we iterate through the original dataset and apply pooling on each element.

Parameters:

• dataset (Dataset) – The dataset to pool.

• pooling_name (PoolingName) – The pooling method, either “mean” or “hamming”.

Return type:

PooledDataset

class fastabx.PooledDataset(labels, accessor, pooling)

Pooled dataset.

Parameters:

• labels (DataFrame)

• accessor (InMemoryAccessor)

• pooling (PoolingName)

class fastabx.PoolingName

Type alias for Literal["mean", "hamming"].

Cell

class fastabx.Cell(a, b, x, header, description, is_symmetric)

Individual cell of the ABX task.

Cells are the unit of work for the ABX Task and Score. They are collections of triplets (A, B, X) that share the same values for the on, by and across conditions.

Parameters:

• a (Batch) – Batch of A samples.

• b (Batch) – Batch of B samples.

• x (Batch) – Batch of X samples.

• header (str) – Short string identifying the cell.

• description (str) – Long string describing the cell.

• is_symmetric (bool) – Whether or not the cell is symmetric (i.e., A and X are the same set).

property num_triplets: int

Get the number of triplets in the cell.

property use_dtw: bool

Whether or not to use the DTW when computing the distances for this cell.

We don’t need DTW if all samples in the cell have a time dimension of 1.

Distance

fastabx.abx_on_cell(cell, distance_name='angular')

Compute the ABX of a cell using the given distance.

Warning

Unlike Score, this low-level helper does not normalize the features. For the default "angular" (and "cosine") distance the cell’s features must already be L2-normalized (e.g. via Dataset.normalize_); otherwise the dot products are only clamped to [-1, 1] and the score is silently wrong. Likewise "kl_symmetric" expects the features to be probability distributions.

Parameters:

• cell (Cell) – The cell to compute the ABX on.

• distance_name (DistanceName) – The name of the distance to use. Defaults to “angular”. Must be one of “euclidean”, “cosine”, “angular”, “kl_symmetric”, “identical”.

Return type:

Tensor

class fastabx.DistanceName

Type alias for Literal["euclidean", "cosine", "angular", "kl_symmetric", "identical"]. "cosine" is an alias for "angular".

class fastabx.Distance

Type alias for Callable[[torch.Tensor, torch.Tensor], torch.Tensor]: a function taking two batches of representations and returning their pairwise distances.

Constraints

class fastabx.Constraints

Type alias for Iterable[pl.Expr].

See With constraints to understand how to use them.

fastabx.constraints_all_different(*columns)

Return Constraints that ensure that each specified column has different values for A, B and X.

Parameters:

columns (str) – The columns to apply the constraints on.

Return type:

Constraints

Environment variables

• FASTABX_WITH_LIBRILIGHT_BUG: If set to 1, changes the behaviour of Dataset.from_item to match Libri-Light. Every feature will now be one frame shorter. This should be set only if you want to replicate previous results obtained with Libri-Light / ZeroSpeech 2021. See Slicing features for more details on how features are sliced.

• FASTABX_OUTPUT: Controls the output format of the fastabx CLI. Defaults to a human-readable "ABX error rate: ..." line; set to json (or jsonl) to emit a single JSON object containing the score and all CLI arguments instead.