Kaldialign

https://pypi.org/project/kaldialign/
Admin
Kaldialign is a Python package that exposes edit distance computation functions from Kaldi, enabling...
Tokens:9,089
Snippets:85
Trust Score:10
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install kaldialign from Source

Source: https://pypi.org/project/kaldialign

Clone the repository and install kaldialign locally using pip.

```bash
git clone https://github.com/pzelasko/kaldialign.git
cd kaldialign
python3 -m pip install --verbose .
```

--------------------------------

### Install kaldialign with Pip

Source: https://pypi.org/project/kaldialign

Use this command to install kaldialign using pip.

```bash
pip install --verbose kaldialign
```

--------------------------------

### Install kaldialign with Conda

Source: https://pypi.org/project/kaldialign

Use this command to install kaldialign if you are using Conda.

```bash
conda install -c kaldialign kaldialign
```

--------------------------------

### Install kaldialign from Git with Pip

Source: https://pypi.org/project/kaldialign

Install the latest version of kaldialign directly from its GitHub repository using pip.

```bash
pip install --verbose -U git+https://github.com/pzelasko/kaldialign.git
```

--------------------------------

### bootstrap_wer_ci

Source: https://pypi.org/project/kaldialign

Obtain the 95% confidence intervals for WER using the Bisani and Ney bootstrapping method. This function can also be used to compare two hypotheses (hyp and hyp2) to compute the probability of system 2 improving over system 1.

```APIDOC
## bootstrap_wer_ci

### Description
Calculates the 95% confidence intervals for Word Error Rate (WER) using the Bisani and Ney bootstrapping method. It can also compare two systems (hyp and hyp2) to determine the probability of the second system improving over the first.

### Parameters
- **ref** (list of tuples): Reference transcriptions.
- **hyp** (list of tuples): Hypothesis transcriptions from system 1.
- **hyp2** (list of tuples, optional): Hypothesis transcriptions from system 2. If provided, the function will also compute comparison metrics between system 1 and system 2.
- **merge_compounds** (bool, optional): Whether to merge compound words. Defaults to False.

### Request Example
```python
from kaldialign import bootstrap_wer_ci

ref = [
    ("a", "b", "c"),
    ("d", "e", "f"),
]
hyp = [
    ("a", "b", "d"),
    ("e", "f", "f"),
]
ans = bootstrap_wer_ci(ref, hyp)

print(ans)
# Expected output structure:
# {
#     "wer": 0.4989,
#     "ci95": 0.2312,
#     "ci95min": 0.2678,
#     "ci95max": 0.7301
# }
```

### Request Example with hyp2
```python
from kaldialign import bootstrap_wer_ci

ref = [
    ("a", "b", "c"),
    ("d", "e", "f"),
]
hyp = [
    ("a", "b", "d"),
    ("e", "f", "f"),
]
hyp2 = [
    ("a", "b", "c"),
    ("e", "e", "f"),
]
ans = bootstrap_wer_ci(ref, hyp, hyp2)

print(ans)
# Expected output structure:
# {
#     "system1": {
#         "wer": 0.4989,
#         "ci95": 0.2312,
#         "ci95min": 0.2678,
#         "ci95max": 0.7301
#     },
#     "system2": {
#         "wer": 0.1656,
#         "ci95": 0.2312,
#         "ci95min": -0.0656,
#         "ci95max": 0.3968
#     },
#     "p_s2_improv_over_s1": 1.0
# }
```

### Response
#### Success Response (200)
- **wer** (float): The calculated Word Error Rate.
- **ci95** (float): The 95% confidence interval width.
- **ci95min** (float): The lower bound of the 95% confidence interval.
- **ci95max** (float): The upper bound of the 95% confidence interval.
- **system1** (dict, optional): If `hyp2` is provided, this contains WER details for the first system.
  - **wer** (float): WER for system 1.
  - **ci95** (float): 95% CI width for system 1.
  - **ci95min** (float): Lower bound of 95% CI for system 1.
  - **ci95max** (float): Upper bound of 95% CI for system 1.
- **system2** (dict, optional): If `hyp2` is provided, this contains WER details for the second system.
  - **wer** (float): WER for system 2.
  - **ci95** (float): 95% CI width for system 2.
  - **ci95min** (float): Lower bound of 95% CI for system 2.
  - **ci95max** (float): Upper bound of 95% CI for system 2.
- **p_s2_improv_over_s1** (float, optional): If `hyp2` is provided, the probability that system 2 improves over system 1.
```

--------------------------------

### Bootstrap WER Confidence Intervals

Source: https://pypi.org/project/kaldialign

Obtain 95% confidence intervals for WER using the Bisani and Ney bootstrapping method. Requires reference and hypothesis sequences.

```python
from kaldialign import bootstrap_wer_ci

ref = [
    ("a", "b", "c"),
    ("d", "e", "f"),
]
hyp = [
    ("a", "b", "d"),
    ("e", "f", "f"),
]
ans = bootstrap_wer_ci(ref, hyp)
assert ans["wer"] == 0.4989
assert ans["ci95"] == 0.2312
assert ans["ci95min"] == 0.2678
assert ans["ci95max"] == 0.7301
```

--------------------------------

### Align Sequences with kaldialign

Source: https://pypi.org/project/kaldialign

Obtain the alignment between two string sequences using the `align` function. Ensure `epsilon` is a null symbol not present in the sequences.

```python
from kaldialign import align

EPS = '*'
a = ['a', 'b', 'c']
b = ['a', 's', 'x', 'c']
ali = align(a, b, EPS)
assert ali == [('a', 'a'), ('b', 's'), (EPS, 'x'), ('c', 'c')]
```

--------------------------------

### Compare Two Systems for WER Improvement Probability

Source: https://pypi.org/project/kaldialign

Compute the probability of system 2 improving over system 1 by providing hypotheses from both systems. The `merge_compounds` option is also available.

```python
from kaldialign import bootstrap_wer_ci

ref = [
    ("a", "b", "c"),
    ("d", "e", "f"),
]
hyp = [
    ("a", "b", "d"),
    ("e", "f", "f"),
]
hyp2 = [
    ("a", "b", "c"),
    ("e", "e", "f"),
]
ans = bootstrap_wer_ci(ref, hyp, hyp2)

s = ans["system1"]
assert s["wer"] == 0.4989
assert s["ci95"] == 0.2312
assert s["ci95min"] == 0.2678
assert s["ci95max"] == 0.7301

s = ans["system2"]
assert s["wer"] == 0.1656
assert s["ci95"] == 0.2312
assert s["ci95min"] == -0.0656
assert s["ci95max"] == 0.3968

assert ans["p_s2_improv_over_s1"] == 1.0
```

--------------------------------

### Compound Word Matching with Alignment

Source: https://pypi.org/project/kaldialign

Use `align` with `merge_compounds=True` to visualize compound word matches. Matches are shown as space-joined strings in the alignment.

```python
from kaldialign import edit_distance, align

# "white paper" (2 words) matches "whitepaper" (1 word) with 0 errors
ref = ["the", "white", "paper", "is", "good"]
hyp = ["the", "whitepaper", "is", "good"]

# Alignment shows compound matches as space-joined strings
ali = align(ref, hyp, "*", merge_compounds=True)
assert ali == [
    ("the", "the"),
    ("white paper", "whitepaper"),
    ("is", "is"),
    ("good", "good")
]
```

--------------------------------

### Compound Word Matching

Source: https://pypi.org/project/kaldialign/0.10.0

Demonstrates how to use the `merge_compounds=True` option with `align` and `edit_distance` functions for matching concatenated words.

```APIDOC
## Compound Word Matching with merge_compounds=True

### Description
All functions accept `merge_compounds=True` to allow adjacent words in either sequence to be concatenated (without separator) to match a single word in the other sequence at zero cost. This is useful whenever there are inconsistencies within transcriptions, or between training and testing conditions of a model evaluated with WER.

### Request Example (edit_distance)
```python
from kaldialign import edit_distance

ref = ["the", "white", "paper", "is", "good"]
hyp = ["the", "whitepaper", "is", "good"]

results = edit_distance(ref, hyp, merge_compounds=True)
# results["total"] will be 0

results = edit_distance(hyp, ref, merge_compounds=True)
# results["total"] will be 0
```

### Request Example (align)
```python
from kaldialign import align

ref = ["the", "white", "paper", "is", "good"]
hyp = ["the", "whitepaper", "is", "good"]
ali = align(ref, hyp, "*", merge_compounds=True)
# ali will be [("the", "the"), ("white paper", "whitepaper"), ("is", "is"), ("good", "good")]
```
```

--------------------------------

### Edit Distance with SCLITE Weights

Source: https://pypi.org/project/kaldialign

Calculate edit distance using SCLITE style weights (insertion/deletion cost 3, substitution cost 4) by setting `sclite_mode=True`.

```python
# Example usage for SCLITE mode (assuming edit_distance function is available)
# results = edit_distance(a, b, sclite_mode=True)
```

--------------------------------

### Calculate Edit Distance with kaldialign

Source: https://pypi.org/project/kaldialign

Compute the total edit distance, including insertions, deletions, and substitutions, between two sequences using `edit_distance`.

```python
from kaldialign import edit_distance

a = ['a', 'b', 'c']
b = ['a', 's', 'x', 'c']
results = edit_distance(a, b)
assert results == {
    'ins': 1,
    'del': 0,
    'sub': 1,
    'total': 2
}
```

--------------------------------

### align Function

Source: https://pypi.org/project/kaldialign/0.10.0

Computes the alignment between two string sequences. It takes reference and hypothesis sequences, and an epsilon symbol for null alignment.

```APIDOC
## align(ref, hyp, epsilon, sclite_mode=False, merge_compounds=False)

### Description
Used to obtain the alignment between two string sequences. `epsilon` should be a null symbol (indicating deletion/insertion) that doesn't exist in either sequence.

### Parameters
- **ref** (list[str]) - The reference sequence.
- **hyp** (list[str]) - The hypothesis sequence.
- **epsilon** (str) - A null symbol not present in ref or hyp.
- **sclite_mode** (bool) - Optional. If True, computes WER-based alignments.
- **merge_compounds** (bool) - Optional. If True, allows adjacent words to be concatenated.

### Request Example
```python
from kaldialign import align

EPS = '*'
a = ['a', 'b', 'c']
b = ['a', 's', 'x', 'c']
ali = align(a, b, EPS)
# ali will be [('a', 'a'), ('b', 's'), (EPS, 'x'), ('c', 'c')]
```

### Response
- **ali** (list[tuple[str, str]]) - A list of tuples representing the alignment.
```

--------------------------------

### Compound Word Matching with Edit Distance

Source: https://pypi.org/project/kaldialign

Enable compound word matching by setting `merge_compounds=True` in `edit_distance`. This allows adjacent words to be concatenated to match a single word at zero cost.

```python
from kaldialign import edit_distance, align

# "white paper" (2 words) matches "whitepaper" (1 word) with 0 errors
ref = ["the", "white", "paper", "is", "good"]
hyp = ["the", "whitepaper", "is", "good"]

results = edit_distance(ref, hyp, merge_compounds=True)
assert results["total"] == 0

# Works in both directions
results = edit_distance(hyp, ref, merge_compounds=True)
assert results["total"] == 0
```

--------------------------------

### edit_distance Function

Source: https://pypi.org/project/kaldialign/0.10.0

Calculates the edit distance between two sequences, providing counts for insertions, deletions, and substitutions.

```APIDOC
## edit_distance(ref, hyp, sclite_mode=False, merge_compounds=False)

### Description
Used to obtain the total edit distance, as well as the number of insertions, deletions and substitutions between two sequences.

### Parameters
- **ref** (list[str]) - The reference sequence.
- **hyp** (list[str]) - The hypothesis sequence.
- **sclite_mode** (bool) - Optional. If True, computes WER-based edit distance.
- **merge_compounds** (bool) - Optional. If True, allows adjacent words to be concatenated.

### Request Example
```python
from kaldialign import edit_distance

a = ['a', 'b', 'c']
b = ['a', 's', 'x', 'c']
results = edit_distance(a, b)
# results will be {'ins': 1, 'del': 0, 'sub': 1, 'total': 2}
```

### Response
- **results** (dict) - A dictionary containing 'ins', 'del', 'sub', and 'total' edit counts.
```
Tokens:
Raw