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)[source]

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)[source]

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=',')[source]

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)[source]

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')[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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

Parameters:

file (str | Path)

Return type:

None

Pooling

fastabx.pooling(dataset, pooling_name)[source]

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)[source]

Individual cell of the ABX task.

Parameters:
  • a (Batch)

  • b (Batch)

  • x (Batch)

  • header (str)

  • description (str)

  • is_symmetric (bool)

property num_triplets: int[source]

Number of triplets in the cell.

property use_dtw: bool[source]

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

Distance

fastabx.distance.distance_on_cell(cell, distance)[source]

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)[source]

Compute the ABX of a cell using the given distance.

Parameters:
  • cell (Cell)

  • distance (Distance)

Return type:

Tensor

DTW

fastabx.dtw.dtw(distances)[source]

Compute the DTW of the given distances 2D tensor.

Parameters:

distances (Tensor)

Return type:

Tensor

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

Compute the batched DTW on the distances 4D tensor.

Parameters:
  • distances (Tensor)

  • sx (Tensor)

  • sy (Tensor)

  • symmetric (bool)

Return type:

Tensor