Troubleshooting¶

Every error below is raised by fastabx itself. They are grouped by the moment they happen.

Building a Dataset¶

Most problems appear here, when the item file and the features meet for the first time. Item files describes what fastabx expects from that file.

InvalidItemFileError — “File extension … is not supported”

The item file must be a .item, .csv, .jsonl or .ndjson file, and its extension decides how it is parsed. Rename a space-separated table to .item, a comma-separated one to .csv.

FileNotFoundError — “N files missing to build the Dataset”

None, or not all, of the files named in the #file column were found under root. Two usual causes: the extension argument does not match your files (.pt by default), or the #file values are not the paths of the feature files relative to root, without their extension. A bare utt1 will not match root/spk1/utt1.pt; the value has to be spk1/utt1. See Matching the features.

FeaturesSizeError — “Input features length is not correct for file …”

The slice asked for by a row of the item file goes past the end of the features of that file. Usually one of:

The feature frequency is wrong. A file of 10 s at a real 50 Hz has 500 frames; ask for 100 Hz and every token in the second half of the file is out of range.
The model produced one frame too few, which happens with unpadded convolutions when the token sits at the very end of the file. Pad the convolutions, or add a little silence at the end of the audio.

EmptyFeaturesError — “N empty entries found”

Some tokens are shorter than a single frame at the given frequency, so their slice is empty. Check the frequency first. If it is right and you do intend to evaluate units that short, remove those rows from the item file. Slicing features explains how the frontiers are computed.

NonFiniteError — “Non-finite values detected in features”

A feature file contains a NaN or an infinity. fastabx refuses it rather than propagating it into the distances, where a single NaN silently poisons every triplet it takes part in. Look at the model that produced that file.

EmptyDataPointsError — “N empty elements were found in the dataset”

Same idea, raised by the accessor: some datapoints span zero frames.

EmptyDatasetError — “The dataset is empty”

There is no datapoint at all, so there is no task to build. Usually an item file whose rows were all filtered out upstream, or labels of length 0.

NonContiguousIndicesError — “The keys of ``indices`` must be exactly the row numbers …”

From a hand-built InMemoryAccessor. Its indices must map every row of Dataset.labels, from 0 to len(labels) - 1, to its [start, end[ frontiers. A gap would make the missing rows read as empty features rather than raise, so it is rejected up front.

FrequencyTypeError — “``frequency`` is getting converted to Decimal”

frequency was a float. Pass an int (50), or a str for a non-integer frequency ("12.5"), so that the times stay exact.

TimesArrayDimensionError, TimesArrayFrontiersError

From Dataset.from_item_with_times: the times array of a file is not 1D, or no timestamp of a file falls between the onset and the offset of one of its tokens. In the second case, check that the times are in seconds and cover the whole file.

Building a Task¶

LabelReservedNameError, LabelSuffixError: A condition column uses a name fastabx needs internally — index, score, size, is_valid, __cell, __group, __lookup, __pos, __triplet — or ends with _a, _b or _x. Rename the column (speaker_x → x_speaker). See the reserved names.
DuplicateConditionsError: The same column appears twice across on, by and across. Each condition plays exactly one role.
UnknownConditionError — “… is not a column of ``Dataset.labels``”: A condition names a column the labels do not have, almost always a typo. The message lists every column that is available. Watch out for the ZeroSpeech names in particular: the ON condition of the standard task is #phone, with the leading #, not phone.
EmptyTaskError — “The task has no cell”: No triplet satisfies the conditions, so there would be nothing to score. A cell needs two different values of the ON condition among datapoints sharing the same BY values, with at least two instances available for A. The most common cause is a BY condition that is redundant with the ON condition — if every speaker utters a single phone, then on="#phone", by=["speaker"] can never pair two phones together. Otherwise, the corpus is too small for the conditions asked for.
InputTypeError: A condition is not a string, or a Subsampler got a non-integer seed. The subsampler also rejects sizes below 2: a cell needs at least two items to compare.
PrecomputedCellsError: From Task.from_cells. The message says which rule was broken: a missing column among header, description, index_a, index_b, index_x; an index column that is not a list of integers; an empty index list; an index outside the dataset; or, for a symmetric task, a row where index_a and index_x differ, or one holding fewer than two rows in index_a — scoring a symmetric cell drops the diagonal, so a single A leaves no triplet at all. See Extending fastabx.
InvalidCellError: A hand-built Cell whose A, B and X are not all 3D tensors, do not share a feature dimension, or whose sizes do not match the number of items.

Scoring¶

IdenticalDistanceDimensionError: The "identical" distance compares discrete units, so it needs features of shape (length, 1), one integer per frame. Encode each unit as a single number — Dataset.from_item_and_units does this for you — or pick a distance defined on vectors.
IncompatibleNormalizationError: You scored a Task with the "angular" (or "cosine") distance, then scored again with another distance. The first Score L2-normalized the dataset in place and appended a singularity column, so the features are no longer in their original space and the second score would be silently wrong. Build a fresh Dataset for the other distance.
CollapseError: Either levels and weighted=True were both given, or neither was, on cells that have more than the two ON columns left to average. The message lists the columns that are still there: pass them through levels in the order you want them averaged, or ask for weighted=True.
EmptyScoreError — “Every cell has a null score”: Only with Constraints, and only when not a single cell kept a valid triplet, so there is nothing left to average. Loosen the constraints, or check that they name the labels you meant (remember the _a, _b and _x suffixes). When only some cells are empty they are skipped by the averages and nothing is raised.
InvalidLevelsError: levels is not a list of strings or tuples of strings, repeats a column, or names a column that is not in the scored cells.
NoConstraintsError: The Constraints expressions do not reference any column of Dataset.labels. Remember the suffixes: a constraint on the speaker label is written with speaker_a, speaker_b and speaker_x. See With constraints.
PoolingNormalizedError: pool_dataset was given a Dataset that an "angular" (or "cosine") Score had already L2-normalized in place. Its features carry an extra singularity column and are no longer in their original space, so pooling them would average that column in and quietly change the measure. Pool first, then score or build a fresh Dataset to pool.

ZeroSpeech ABX¶

MissingMaxXAcrossError: zerospeech_abx was called with speaker="across" but no max_x_across. It has no default because leaving it out is rarely intended: pass 5 for the original ZeroSpeech behaviour, or None explicitly to disable the subsampling.
InvalidSpeakerOrContextError: speaker must be "within" or "across", and context "within" or "any".

Results that look wrong¶

The score is around 0.5. Chance level. The representations do not separate the categories at all — or the labels are shuffled with respect to the features. Check that the rows of labels line up with the rows of features.

The score is suspiciously good. Make sure nothing leaks into the triplets: the same recording appearing as both A and X, for instance. With constraints is the tool for excluding those.

The number is the complement of what you expected. fastabx reports the ABX error rate, so 0.03 means 3% errors, i.e. 97% discriminability.

A score is null. Only happens with Constraints: the cell has no valid triplet left. Those cells are dropped from the averages rather than counted as zero.

Scores differ from Libri-Light or ZeroSpeech 2021. Expected, and explained in Coming from other libraries: their slicing drops one frame per token. Set FASTABX_WITH_LIBRILIGHT_BUG=1 to reproduce the old numbers.

Out of memory¶

Both the features and the intermediate distances live on the same device. See Performance and memory for what is allocated, and for the arguments and environment variables that bound it.

InvalidEnvironmentVariableError: One of the FASTABX_* tuning variables of Performance tuning is set to something that is not a positive integer. The message names the variable; unset it to go back to the default.