API reference

fastabx.zerospeech_abx(item, root, *, speaker='within', context='within', distance='cosine', frequency=50, feature_maker=<function load>, max_size_group=10, max_x_across=5, 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) – the item file

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

• speaker (Literal['within', 'across']) – the speaker mode, either “within” or “across”

• context (Literal['within', 'any']) – the context mode, either “within” or “any”

• distance (DistanceName) – the distance metric, either “cosine”, “euclidean”, “kl_symmetric” or “identical”

• frequency (int) – the feature frequency of the features / the output of the feature maker, in Hz. Default is 50 Hz

• feature_maker (FeatureMaker) – the feature maker. Defaults to just loading the file with torch.load

• max_size_group (int | None) – maximum number of instances of A, B, or X in each Cell. Default is 10. Passed to the Subsampler of the Task. 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. Default is 5. Passed to the Subsampler of the Task. Disabled if set to None

• 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_csv(path, feature_columns, *, separator=',')

Create a dataset from a CSV file.

Parameters:

• path (str | Path)

• feature_columns (str | Collection[str])

• separator (str)

Return type:

Dataset

classmethod from_dataframe(df, feature_columns)

Create a dataset from a DataFrame (polars or pandas).

Parameters:

• df (SupportsInterchange)

• feature_columns (str | Collection[str])

Return type:

Dataset

classmethod from_item(item, root, frequency, feature_maker, *, extension='.pt')

Create a dataset from an item file.

Parameters:

• item (str | Path)

• root (str | Path)

• frequency (int)

• feature_maker (FeatureMaker)

• extension (str)

Return type:

Dataset

classmethod from_numpy(features, labels)

Create a dataset from the features (numpy array) and the labels (dictionary of sequences).

Parameters:

• features (ArrayLike)

• labels (Mapping[str, Sequence[object]])

Return type:

Dataset

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.

Parameters:

• dataset (Dataset)

• on (str)

• by (list[str] | None)

• across (list[str] | None)

• subsampler (Subsampler | None)

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)

• max_x_across (int | None)

• seed (int)

Score

class fastabx.Score(task, distance_name)

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

Parameters:

• task (Task)

• distance_name (DistanceName)

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)

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

Parameters:

levels (Sequence[tuple[str, ...] | str]) – 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.

Parameters:

file (str | Path)

Return type:

None

Pooling

fastabx.pooling(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)

• pooling_name (PoolingName)

Return type:

PooledDataset

Advanced

Cell

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

Individual cell of the ABX task.

Parameters:

• a (Batch)

• b (Batch)

• x (Batch)

• header (str)

• description (str)

• is_symmetric (bool)

property num_triplets: int

Number of triplets in the cell.

property use_dtw: bool

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

Distance

fastabx.distance.distance_on_cell(cell, distance)

Compute the distance matrices between all A and X, and all B and X in the cell, for a given distance.

Parameters:

• cell (Cell)

• distance (Distance)

Return type:

tuple[Tensor, Tensor]

fastabx.distance.abx_on_cell(cell, distance)

Compute the ABX of a cell using the given distance.

Parameters:

• cell (Cell)

• distance (Distance)

Return type:

Tensor

DTW

fastabx.dtw.dtw(distances)

Compute the DTW of the given distances 2D tensor.

Parameters:

distances (Tensor)

Return type:

Tensor

fastabx.dtw.dtw_batch(distances, sx, sy, *, symmetric)

Compute the batched DTW on the distances 4D tensor.

Parameters:

• distances (Tensor)

• sx (Tensor)

• sy (Tensor)

• symmetric (bool)

Return type:

Tensor