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 theSubsampler
of theTask
. Disabled if set toNone
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 theTask
. Disabled if set toNone
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:
- 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:
Task¶
- class fastabx.Task(dataset, *, on, by=None, across=None, subsampler=None)[source]¶
The ABX task class.
A Task builds all the
Cell
givenon
,by
andacross
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 tomax_x_across
possible values for X. Subsampling for one or more conditions can be disabled by setting the corresponding argument toNone
.- 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 bydistance_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
Pooling¶
- fastabx.pooling(dataset, pooling_name)[source]¶
Pool the
Dataset
using the pooling method given bypooling_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