SpectralCluster

https://github.com/wq2012/spectralcluster
Admin
SpectralCluster is a Python library that implements spectral clustering algorithms with affinity...
Tokens:105,437
Snippets:662
Trust Score:9.8
License:Apache-2.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install spectralcluster 0.1.0

Source: https://github.com/wq2012/spectralcluster/blob/master/README.md

Install an older version of the library if you depend on the old API.

```bash
pip3 install spectralcluster==0.1.0
```

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

### Install spectralcluster with pip3

Source: https://github.com/wq2012/spectralcluster/blob/master/README.md

Install the spectralcluster package using pip3.

```bash
pip3 install spectralcluster
```

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

### Example configurations for spectralcluster (ICASSP2018 and Turn-to-Diarize)

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/configs.html

Defines two example configurations for the spectralcluster library: one matching the ICASSP2018 paper "Speaker Diarization with LSTM" and one for the Turn-to-Diarize system using Turn + Constraint Propagation + AutoTune. The ICASSP2018 configuration uses a refinement sequence with Gaussian blur, row-wise thresholding, and diffusion, while the Turn-to-Diarize configuration uses constraint propagation with alpha 0.4 and AutoTune with p_percentile range 0.40-0.95.

```python
1"""Example configurations."""
2
3from spectralcluster import autotune
4from spectralcluster import constraint
5from spectralcluster import laplacian
6from spectralcluster import refinement
7from spectralcluster import spectral_clusterer
8
9AutoTune = autotune.AutoTune
10ConstraintName = constraint.ConstraintName
11ConstraintOptions = constraint.ConstraintOptions
12RefinementName = refinement.RefinementName
13RefinementOptions = refinement.RefinementOptions
14ThresholdType = refinement.ThresholdType
15SymmetrizeType = refinement.SymmetrizeType
16LaplacianType = laplacian.LaplacianType
17SpectralClusterer = spectral_clusterer.SpectralClusterer
18
19# Configurations that are closest to the ICASSP2018 paper
20# "Speaker Diarization with LSTM".
21ICASSP2018_REFINEMENT_SEQUENCE = [
22    RefinementName.CropDiagonal,
23    RefinementName.GaussianBlur,
24    RefinementName.RowWiseThreshold,
25    RefinementName.Symmetrize,
26    RefinementName.Diffuse,
27    RefinementName.RowWiseNormalize,
28]
29
30icassp2018_refinement_options = RefinementOptions(
31    gaussian_blur_sigma=1,
32    p_percentile=0.95,
33    thresholding_soft_multiplier=0.01,
34    thresholding_type=ThresholdType.RowMax,
35    refinement_sequence=ICASSP2018_REFINEMENT_SEQUENCE)
36
37icassp2018_clusterer = SpectralClusterer(
38    min_clusters=2,
39    max_clusters=7,
40    autotune=None,
41    laplacian_type=None,
42    refinement_options=icassp2018_refinement_options,
43    custom_dist="cosine")
44
45# Configurations of Turn-to-Diarize system using the
46# Turn + Constraint Propagation + AutoTune method described in the paper
47# "Turn-to-Diarize: Online Speaker Diarization Constrained by
48# Transformer Transducer Speaker Turn Detection".
49TURNTODIARIZE_REFINEMENT_SEQUENCE = [
50    RefinementName.RowWiseThreshold, RefinementName.Symmetrize
51]
52
53turntodiarize_refinement_options = RefinementOptions(
54    thresholding_soft_multiplier=0.01,
55    thresholding_type=ThresholdType.Percentile,
56    thresholding_with_binarization=True,
57    thresholding_preserve_diagonal=True,
58    symmetrize_type=SymmetrizeType.Average,
59    refinement_sequence=TURNTODIARIZE_REFINEMENT_SEQUENCE)
60
61turntodiarize_constraint_options = ConstraintOptions(
62    constraint_name=ConstraintName.ConstraintPropagation,
63    apply_before_refinement=True,
64    constraint_propagation_alpha=0.4)
65
66turntodiarize_auto_tune = AutoTune(
67    p_percentile_min=0.40,
68    p_percentile_max=0.95,
69    init_search_step=0.05,
70    search_level=1)
71
72turntodiarize_clusterer = SpectralClusterer(
73    min_clusters=2,
74    max_clusters=7,
75    refinement_options=turntodiarize_refinement_options,
76    constraint_options=turntodiarize_constraint_options,
77    autotune=turntodiarize_auto_tune,
78    laplacian_type=LaplacianType.GraphCut,
79    row_wise_renorm=True,
80    custom_dist="cosine")
```

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

### Install spectralcluster with python3 -m pip

Source: https://github.com/wq2012/spectralcluster/blob/master/README.md

Install the spectralcluster package using python3 -m pip.

```bash
python3 -m pip install spectralcluster
```

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

### AutoTune class definition and methods

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/configs.html

Defines the AutoTune class with initialization parameters for percentile range and search settings. Includes methods to get and update the percentile range, and the tune method that performs hierarchical search to minimize a proxy ratio.

```python
class AutoTune:
  """AutoTune Class.

  This auto-tuning method is implemented based on this paper:
  Park, Tae Jin, et al. "Auto-tuning spectral clustering for speaker
  diarization using normalized maximum eigengap." IEEE Signal Processing Letter
  2019.
  """

  def __init__(self,
               p_percentile_min: float = 0.60,
               p_percentile_max: float = 0.95,
               init_search_step: float = 0.01,
               search_level: int = 1,
               proxy: AutoTuneProxy = AutoTuneProxy.PercentileSqrtOverNME):
    """Initialization of the autotune arguments.

    Args:
      p_percentile_min: minimum value of p_percentile
      p_percentile_max: maximum value of p_percentile
      init_search_step: initial search step size for auto-tuning
      search_level: hierarchical search level for auto-tuning
      proxy: which proxy to minimize for auto-tuning
    """
    self.p_percentile_min = p_percentile_min
    self.p_percentile_max = p_percentile_max
    self.search_step = init_search_step
    self.search_level = search_level
    if not isinstance(proxy, AutoTuneProxy):
      raise TypeError("proxy must be an instance of AutoTuneProxy")
    self.proxy = proxy

  def get_percentile_range(self) -> typing.Sequence[float]:
    """Get the current percentile search range."""
    num_steps = int(
        np.ceil(
            (self.p_percentile_max - self.p_percentile_min) / self.search_step))
    return list(
        np.linspace(self.p_percentile_min, self.p_percentile_max, num_steps))

  def update_percentile_range(self,
                              p_percentile_min: float,
                              p_percentile_max: float,
                              search_step: float) -> typing.Sequence[float]:
    """Update the percentile search range."""
    self.p_percentile_min = p_percentile_min
    self.p_percentile_max = p_percentile_max
    self.search_step = search_step
    return self.get_percentile_range()

  def tune(self, p_percentile_to_ratio: typing.Callable) -> (
      typing.Tuple[np.ndarray, int, float]):
    """Tune the hyper-parameter p_percentile.

    Use a proxy ratio of DER to tune the hyper-parameter p_percentile. It also
    performs some side work to do affinity refinement, eigen decomposition, and
    estimate the number of clusters.

    Args:
      p_percentile_to_ratio: a callable to compute the `ratio` given a
        `p_percentile` value

    Returns:
      eigenvectors: sorted eigenvectors. numpy array of shape
      (n_samples, n_samples)
      n_clusters: number of clusters as an integer
      best_p_percentile: p_percentile value that minimizes the ratio
    """
    p_percentile_range = self.get_percentile_range()
    searched = dict()
    for _ in range(self.search_level):
      min_ratio = np.inf
      for index, p_percentile in enumerate(p_percentile_range):
        if p_percentile in searched:
          continue
        # ratio is a proxy value of DER. We minimize this ratio
        # to find a good p_percentile
        ratio, eigenvectors_p, n_clusters_p = p_percentile_to_ratio(
            p_percentile)
        searched[p_percentile] = ratio
        if ratio < min_ratio:
          min_ratio = ratio
          eigenvectors = eigenvectors_p
          n_clusters = n_clusters_p
          best_p_percentile = p_percentile
          best_p_percentile_index = index
      # If the search range is not valid or search step is too small, we stop
      if not p_percentile_range or len(
          p_percentile_range) == 1 or self.search_step < MIN_SEARCH_STEP:
        break
      # Update the search range of p_percentile.
      # We search again from `start_index` position to `end_index` position
      # which is `local_search_dist` away from the found
      # `best_p_percentile_index` position. `search_step` is reduced to half of
      # the original size
      local_search_dist = max(2, len(p_percentile_range) // 8)
      start_index = max(0, best_p_percentile_index - local_search_dist)
      end_index = min(
          len(p_percentile_range) - 1,
          best_p_percentile_index + local_search_dist)
      p_percentile_min = p_percentile_range[start_index]
      p_percentile_max = p_percentile_range[end_index]
      self.search_step = self.search_step / 2
      p_percentile_range = self.update_percentile_range(p_percentile_min,
                                                        p_percentile_max,
                                                        self.search_step)
    return eigenvectors, n_clusters, best_p_percentile
```

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

### GaussianBlur.__init__ method

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/refinement.html

Constructor for GaussianBlur, sets the sigma parameter.

```python
def __init__(self, sigma: int = 1):
  self.sigma = sigma
```

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

### AutoTune.__init__

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/autotune.html

Initializes the AutoTune object with parameters for the percentile range, search step, search level, and proxy type.

```APIDOC
## AutoTune.__init__

### Description
Initializes the AutoTune object with parameters for the percentile range, search step, search level, and proxy type.

### Method
Constructor

### Parameters
- **p_percentile_min** (float) - Optional - Minimum value of p_percentile. Default: 0.60
- **p_percentile_max** (float) - Optional - Maximum value of p_percentile. Default: 0.95
- **init_search_step** (float) - Optional - Initial search step size for auto-tuning. Default: 0.01
- **search_level** (int) - Optional - Hierarchical search level for auto-tuning. Default: 1
- **proxy** (AutoTuneProxy) - Optional - Which proxy to minimize for auto-tuning. Default: AutoTuneProxy.PercentileSqrtOverNME

### Returns
None
```

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

### AutoTune.__init__

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/autotune.html

Initializes the AutoTune object with configurable parameters for the percentile range, search step, search level, and proxy type.

```APIDOC
## AutoTune.__init__

### Description
Initializes the AutoTune object with parameters for auto-tuning the p_percentile hyper-parameter.

### Method
Constructor

### Signature
python
def __init__(self,
             p_percentile_min: float = 0.60,
             p_percentile_max: float = 0.95,
             init_search_step: float = 0.01,
             search_level: int = 1,
             proxy: AutoTuneProxy = AutoTuneProxy.PercentileSqrtOverNME)


### Parameters
- **p_percentile_min** (float) - Optional - Minimum value of p_percentile. Default: 0.60
- **p_percentile_max** (float) - Optional - Maximum value of p_percentile. Default: 0.95
- **init_search_step** (float) - Optional - Initial search step size for auto-tuning. Default: 0.01
- **search_level** (int) - Optional - Hierarchical search level for auto-tuning. Default: 1
- **proxy** (AutoTuneProxy) - Optional - Which proxy to minimize for auto-tuning. Must be an instance of AutoTuneProxy. Default: AutoTuneProxy.PercentileSqrtOverNME

### Raises
- **TypeError** - If `proxy` is not an instance of AutoTuneProxy.

```

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

### get_refinement_operator

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster.html

Method to get the refinement operator for the affinity matrix based on a given RefinementName.

```APIDOC
## get_refinement_operator(name: RefinementName) -> AffinityRefinementOperation

### Description
Get the refinement operator for the affinity matrix.

### Parameters
- **name** (RefinementName) - Required - a RefinementName

### Returns
- object of the operator

### Raises
- **TypeError** - if name is not a RefinementName
- **ValueError** - if name is an unknown refinement operation
```

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

### ConstraintPropagation.__init__

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/constraint.html

Initializes the ConstraintPropagation instance with an alpha parameter.

```APIDOC
## ConstraintPropagation.__init__

### Description
Initializes the ConstraintPropagation instance with the given alpha parameter.

### Parameters
- **alpha** (float) - Optional - The propagation parameter, defaults to 0.6.

### Request Example
```python
propagation = ConstraintPropagation(alpha=0.6)
```
```

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

### Get cluster centroids from embeddings

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/utils.html

Computes the centroid (mean) of each cluster from the embeddings, returning an array of shape (n_clusters, n_features).

```python
def get_cluster_centroids(
    embeddings: np.ndarray, labels: np.ndarray
    ) -> np.ndarray:
  """Get the centroids of each cluster from the embeddings.

  Args:
    embeddings: numpy array of shape (n_samples, n_features)
    labels: numpy array of shape (n_samples, )

  Returns:
    numpy array of shape (n_clusters, n_features)
  """
  n_clusters = max(labels) + 1
  centroids = []
  for i in range(n_clusters):
    cluster_embeddings = embeddings[labels == i, :]
    cluster_centroid = np.mean(cluster_embeddings, axis=0)
    centroids.append(cluster_centroid)
  return np.stack(centroids)
```

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

### AutoTune.__init__

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/autotune.html

Initializes the AutoTune object with the given parameters for auto-tuning.

```APIDOC
## AutoTune.__init__

### Description
Initialization of the autotune arguments.

### Method
Constructor

### Signature
python
AutoTune(p_percentile_min: float = 0.60,
         p_percentile_max: float = 0.95,
         init_search_step: float = 0.01,
         search_level: int = 1,
         proxy: AutoTuneProxy = AutoTuneProxy.PercentileSqrtOverNME)


### Parameters
- **p_percentile_min** (float) - Optional - Minimum value of p_percentile. Default: 0.60
- **p_percentile_max** (float) - Optional - Maximum value of p_percentile. Default: 0.95
- **init_search_step** (float) - Optional - Initial search step size for auto-tuning. Default: 0.01
- **search_level** (int) - Optional - Hierarchical search level for auto-tuning. Default: 1
- **proxy** (AutoTuneProxy) - Optional - Which proxy to minimize for auto-tuning. Must be an instance of AutoTuneProxy. Default: AutoTuneProxy.PercentileSqrtOverNME

### Raises
- **TypeError** - If proxy is not an instance of AutoTuneProxy.

### Attributes
- **p_percentile_min** (float) - Minimum value of p_percentile
- **p_percentile_max** (float) - Maximum value of p_percentile
- **search_step** (float) - Initial search step size
- **search_level** (int) - Hierarchical search level
- **proxy** (AutoTuneProxy) - Proxy to minimize
```

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

### NaiveClusterer.__init__ method

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/naive_clusterer.html

Initializes the NaiveClusterer with a threshold and optional adaptation_threshold. Raises ValueError if adaptation_threshold is smaller than threshold. Sets up the centroids list.

```python
29  def __init__(self,
30               threshold: float,
31               adaptation_threshold: typing.Optional[float] = None):
32    """Initialized the clusterer.
33
34    Note that since this is online clustering, fit_predict and predict
35    are the same.
36
37    Args:
38      threshold: if cosine similarity is larger than this threshold, the
39        embedding will be considered to belong to the cluster
40      adaptation_threshold: if cosine similarity is larger than
41        adaptation_threshold, the embedding will be merged to the cluster.
42        If None, we use threshold as adaptation_threshold
43
44    Raises:
45      ValueError: if adaptation_threshold is smaller than threshold
46    """
47    self.threshold = threshold
48    if adaptation_threshold is None:
49      self.adaptation_threshold = threshold
50    elif adaptation_threshold < threshold:
51      raise ValueError("adaptation_threshold cannot be smaller than threshold")
52    else:
53      self.adaptation_threshold = adaptation_threshold
54    self.centroids = []
```

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

### transform_labels(labels)

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/utils.html

Transforms a label sequence to an ordered form, making it permutation invariant. The new labels start with 0 and smaller labels always appear first.

```APIDOC
## transform_labels(labels)

### Description
Transforms the label sequence to an ordered form, making it permutation invariant. The new labels start with 0 and smaller labels always appear first.

### Parameters
- **labels** (array of integers) - Required - The input label sequence.

### Returns
- **new_labels** (array of integers) - The transformed label sequence, starting with 0 and with smaller labels appearing first.
```

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

### AutoTune.__init__

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/autotune.html

Constructor for the AutoTune class. Initializes the AutoTune object with parameters for percentile range, search step, search level, and proxy.

```APIDOC
## AutoTune.__init__

### Description
Constructor for the AutoTune class. Initializes the AutoTune object with parameters for percentile range, search step, search level, and proxy.

### Parameters
- **p_percentile_min** (float) - Minimum percentile value for tuning.
- **p_percentile_max** (float) - Maximum percentile value for tuning.
- **search_step** (float) - Step size for searching percentile values.
- **search_level** (int) - Number of search levels.
- **proxy** (AutoTuneProxy) - Proxy object used for tuning.

```

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

### Transform labels to ordered form

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/utils.html

Reorders label sequence to start from 0 and ensure smaller labels appear first, making the sequence permutation invariant as used in the paper 'Discriminative neural clustering for speaker diarisation'.

```python
def transform_labels(labels: np.ndarray) -> np.ndarray:
  """Transform the label sequence to an ordered form.

  This is the same type of label sequence used in the paper "Discriminative
  neural clustering for speaker diarisation". This makes the label sequence
  permutation invariant.

  Args:
    labels: an array of integers

  Returns:
    new_labels: an array of integers, where it starts with 0 and smaller
      labels always appear first
  """
  new_labels = labels.copy()
  max_label = -1
  label_map = {}
  for element in labels.tolist():
    if element not in label_map:
      max_label += 1
      label_map[element] = max_label
  for key in label_map:
    new_labels[labels == key] = label_map[key]
  return new_labels
```

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

### AutoTune.__init__ constructor with default parameters

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/autotune.html

Initializes the autotune arguments for the AutoTune class. Accepts p_percentile_min, p_percentile_max, init_search_step, search_level, and proxy parameters with defaults. Use when creating an AutoTune instance for spectral clustering auto-tuning.

```python
36  def __init__(self,
37               p_percentile_min: float = 0.60,
38               p_percentile_max: float = 0.95,
39               init_search_step: float = 0.01,
40               search_level: int = 1,
41               proxy: AutoTuneProxy = AutoTuneProxy.PercentileSqrtOverNME):
42    """Initialization of the autotune arguments.
43
44    Args:
45      p_percentile_min: minimum value of p_percentile
46      p_percentile_max: maximum value of p_percentile
47      init_search_step: initial search step size
48      search_level: search level
49      proxy: AutoTuneProxy instance
50    """
51      self.p_percentile_min = p_percentile_min
52      self.p_percentile_max = p_percentile_max
53      self.init_search_step = init_search_step
54      self.search_level = search_level
55      self.proxy = proxy

```

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

### AutoTune class initialization

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster.html

Defines the AutoTune class with its constructor and docstring. Use this when configuring spectral clustering auto-tuning parameters like p_percentile_min, p_percentile_max, init_search_step, search_level, and proxy.

```python
 27class AutoTune:
 28  """AutoTune Class.
 29
 30  This auto-tuning method is implemented based on this paper:
 31  Park, Tae Jin, et al. "Auto-tuning spectral clustering for speaker
 32  diarization using normalized maximum eigengap." IEEE Signal Processing Letter
 33  2019.
 34  """
 35
 36  def __init__(self,
 37               p_percentile_min: float = 0.60,
 38               p_percentile_max: float = 0.95,
 39               init_search_step: float = 0.01,
 40               search_level: int = 1,
 41               proxy: AutoTuneProxy = AutoTuneProxy.PercentileSqrtOverNME):
 42    """Initialization of the autotune arguments.
 43
 44    Args:
 45      p_percentile_min: minimum value of p_percentile
 46      p_percentile_max: maximum value of p_percentile
 47      init_search_step: initial search step size for auto-tuning
 48      search_level: hierarchical search level for auto-tuning
 49      proxy: which proxy to minimize for auto-tuning
 50    """
 51    self.p_percentile_min = p_percentile_min
 52    self.p_percentile_max = p_percentile_max
 53    self.search_step = init_search_step
 54    self.search_level = search_level
 55    self.proxy = proxy

```

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

### enforce_ordered_labels: Transform labels to ordered form

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/utils.html

Transforms a label sequence into an ordered form, making it permutation invariant as used in the paper "Discriminative neural clustering for speaker diarisation". The output starts with 0 and smaller labels always appear first.

```python
def enforce_ordered_labels(labels: np.ndarray) -> np.ndarray:
  """Transform the label sequence to an ordered form.

  This is the same type of label sequence used in the paper "Discriminative
  neural clustering for speaker diarisation". This makes the label sequence
  permutation invariant.

  Args:
    labels: an array of integers

  Returns:
    new_labels: an array of integers, where it starts with 0 and smaller
      labels always appear first
  """
  new_labels = labels.copy()
  max_label = -1
  label_map = {}
  for element in labels.tolist():
    if element not in label_map:
      max_label += 1
      label_map[element] = max_label
  for key in label_map:
    new_labels[labels == key] = label_map[key]
  return new_labels
```

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

### NaiveClusterer.__init__

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/naive_clusterer.html

Initializes the NaiveClusterer with a threshold and optional adaptation threshold.

```APIDOC
## NaiveClusterer.__init__

### Description
Initialized the clusterer. Note that since this is online clustering, fit_predict and predict are the same.

### Method
__init__

### Signature
`def __init__(self, threshold: float, adaptation_threshold: typing.Optional[float] = None)`

### Parameters
- **threshold** (float) - Required - If cosine similarity is larger than this threshold, the embedding will be considered to belong to the cluster.
- **adaptation_threshold** (Optional[float]) - Optional - If cosine similarity is larger than adaptation_threshold, the embedding will be merged to the cluster. If None, we use threshold as adaptation_threshold.

### Raises
- **ValueError** - If adaptation_threshold is smaller than threshold.
```

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

### NaiveClusterer.__init__

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/naive_clusterer.html

Initializes a NaiveClusterer with a threshold value.

```APIDOC
## NaiveClusterer.__init__

### Description
Initializes a NaiveClusterer instance with the given threshold.

### Method
Constructor

### Parameters
- **threshold** (float) - Required - The similarity threshold for merging clusters.

### Returns
A new NaiveClusterer object.
```

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

### Symmetrize.__init__

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/refinement.html

Constructor for the Symmetrize refinement operation, which symmetrizes an affinity matrix using either the Max or Average strategy.

```APIDOC
## Symmetrize.__init__

### Description
Initializes a Symmetrize refinement operation with the specified symmetrization type.

### Parameters
- **symmetrize_type** (SymmetrizeType) - Optional - The symmetrization strategy to use. Defaults to SymmetrizeType.Max.

### Request Example
{
  "symmetrize_type": 
```

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

### NaiveClusterer.__init__

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/naive_clusterer.html

Initializes the NaiveClusterer with a threshold and optional adaptation threshold for online clustering.

```APIDOC
## NaiveClusterer.__init__

### Description
Initializes the NaiveClusterer with a threshold and optional adaptation threshold for online clustering.

### Parameters
- **threshold** (float) - Required - if cosine similarity is larger than this threshold, the embedding will be considered to belong to the cluster
- **adaptation_threshold** (Optional[float]) - Optional - if cosine similarity is larger than adaptation_threshold, the embedding will be merged to the cluster. If None, use threshold as adaptation_threshold

### Raises
- **ValueError** - if adaptation_threshold is smaller than threshold
```

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

### ConstraintMatrix.__init__

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/constraint.html

Initializes a ConstraintMatrix object with speaker turn scores and a threshold.

```APIDOC
## ConstraintMatrix.__init__

### Description
Initializes the constraint matrix arguments.

### Parameters
- **speaker_turn_scores** (typing.Sequence[float]) - Required - A list of speaker turn confidence scores. All score values are larger or equal to 0. If score is 0, there is no speaker turn. speaker_turn_scores[i+1] means the speaker turn confidence score between turn i+1 and turn i. The first score speaker_turn_scores[0] is not used.
- **threshold** (float) - Optional - A threshold value for the speaker turn confidence score. Default is 1.

### Raises
- **ValueError** - If any score in speaker_turn_scores is less than 0.

```

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

### NaiveCentroid.__init__ constructor

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/naive_clusterer.html

Constructor for NaiveCentroid, initializing the centroid with an embedding and setting the count to 1.

```python
def __init__(self, embedding: np.ndarray):
    """Create a new centroid."""
    self.embedding = embedding
    self.count = 1
```

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

### MultiStageClusterer.__init__

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/multi_stage_clusterer.html

Initializes a MultiStageClusterer instance with a main SpectralClusterer, fallback threshold, and size limits. It configures the main clusterer's fallback options and creates a pre-clusterer for compression.

```APIDOC
## MultiStageClusterer.__init__

### Description
Initializes a MultiStageClusterer instance with a main SpectralClusterer, fallback threshold, and size limits. It configures the main clusterer's fallback options and creates a pre-clusterer for compression.

### Method
Constructor

### Signature
```python
def __init__(
    self,
    main_clusterer: spectral_clusterer.SpectralClusterer,
    fallback_threshold: float = 0.5,
    L: int = 50,
    U1: int = 100,
    U2: int = 600,
    deflicker: Deflicker = Deflicker.NoDeflicker
)
```

### Parameters
- **main_clusterer** (SpectralClusterer) - Required - The main spectral clusterer to use.
- **fallback_threshold** (float) - Optional - Threshold for fallback AHC clusterer. Default: 0.5.
- **L** (int) - Optional - Lower bound of main clusterer (spectral_min_embeddings). Default: 50.
- **U1** (int) - Optional - Upper bound of main clusterer. Default: 100.
- **U2** (int) - Optional - Upper bound of pre-clusterer. Default: 600.
- **deflicker** (Deflicker) - Optional - Deflicker mode. Default: Deflicker.NoDeflicker.

### Raises
- **ValueError** - If `main_clusterer.max_spectral_size` is set.
```

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

### MultiStageClusterer.__init__

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/multi_stage_clusterer.html

Initializes a MultiStageClusterer with a main SpectralClusterer, fallback threshold, and streaming parameters. Configures the main clusterer's fallback options and pre-clusterer.

```APIDOC
## MultiStageClusterer.__init__

### Description
Initializes a MultiStageClusterer with a main SpectralClusterer, fallback threshold, and streaming parameters. Configures the main clusterer's fallback options and pre-clusterer.

### Method
Constructor

### Signature
`__init__(self, main_clusterer: spectral_clusterer.SpectralClusterer, fallback_threshold: float = 0.5, L: int = 50, U1: int = 100, U2: int = 600, deflicker: Deflicker = Deflicker.NoDeflicker)`

### Parameters
- **main_clusterer** (spectral_clusterer.SpectralClusterer) - Required - The main spectral clusterer to use.
- **fallback_threshold** (float) - Optional - Threshold for fallback AHC clusterer. Default: 0.5.
- **L** (int) - Optional - Lower bound of main clusterer (spectral_min_embeddings). Default: 50.
- **U1** (int) - Optional - Upper bound of main clusterer. Default: 100.
- **U2** (int) - Optional - Upper bound of pre-clusterer. Default: 600.
- **deflicker** (Deflicker) - Optional - Method to deflicker streaming output labels. Default: Deflicker.NoDeflicker.

### Raises
- **ValueError** - If `main_clusterer.max_spectral_size` is set.
```

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

### NaiveCentroid.__init__

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/naive_clusterer.html

Initializes a NaiveCentroid object with an embedding and count.

```APIDOC
## NaiveCentroid.__init__

### Description
Initializes a NaiveCentroid instance with the given embedding and count.

### Method
Constructor

### Parameters
- **embedding** (array-like) - Required - The embedding vector for the centroid.
- **count** (int) - Required - The number of points represented by this centroid.

### Returns
A new NaiveCentroid object.
```

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

### MultiStageClusterer class definition and __init__

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/multi_stage_clusterer.html

Defines the MultiStageClusterer class and its constructor. The constructor validates that max_spectral_size is not set on the main SpectralClusterer, then configures the fallback threshold, pre-clusterer bounds (L, U1, U2), and optional deflicker.

```python
class MultiStageClusterer:
  """Multi-stage clustering class."""

  def __init__(
      self,
      main_clusterer: spectral_clusterer.SpectralClusterer,
      fallback_threshold: float = 0.5,
      L: int = 50,
      U1: int = 100,
      U2: int = 600,
      deflicker: Deflicker = Deflicker.NoDeflicker
  ):
    self.deflicker = deflicker

    # Main clusterer.
    self.main = main_clusterer

    if self.main.max_spectral_size:
      raise ValueError(
        
```

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

### MultiStageClusterer constructor

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/multi_stage_clusterer.html

Initializes the MultiStageClusterer with a main SpectralClusterer, fallback threshold, and bounds U1 and U2. Raises ValueError if max_spectral_size is set on the main clusterer. Sets up fallback options and a pre-clusterer.

```python
 71  def __init__(
 72      self,
 73      main_clusterer: spectral_clusterer.SpectralClusterer,
 74      fallback_threshold: float = 0.5,
 75      L: int = 50,
 76      U1: int = 100,
 77      U2: int = 600,
 78      deflicker: Deflicker = Deflicker.NoDeflicker
 79  ):
 80    self.deflicker = deflicker
 81
 82    # Main clusterer.
 83    self.main = main_clusterer
 84
 85    if self.main.max_spectral_size:
 86      raise ValueError(
 87        "Do not set max_spectral_size for SpectralClusterer when"
 88        "using MultiStageClusterer.")
 89
 90    # Lower bound of main clusterer.
 91    self.main.fallback_options.spectral_min_embeddings = L
 92
 93    # Upper bound of main clusterer.
 94    self.U1 = U1
 95
 96    # Upper bound of pre-clusterer.
 97    self.U2 = U2
 98
 99    # Threshold for fallback AHC clusterer.
100    self.main.fallback_options.agglomerative_threshold = fallback_threshold
101
102    # Other configs for fallback.
103    self.main.fallback_options.single_cluster_condition = (
104      fallback_clusterer.SingleClusterCondition.FallbackClusterer)
105    self.main.fallback_options.fallback_clusterer_type = (
106      fallback_clusterer.FallbackClustererType.Agglomerative)
107
108    # Pre-clusterer.
109    self.pre = AgglomerativeClustering(
110        n_clusters=U1,
111        metric="cosine",
112        linkage="complete")
113
114    # All cached centroids.
115    self.cache = None
116
117    # Number of clustered embeddings.
118    self.num_embeddings = 0
119
120    # Array of shape (n_samples,), mapping from original embedding to compressed
121    # centroid.
122    self.compression_labels = None
123
124    self.previous_output = None
```

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

### AutoTune Class

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/spectral_clusterer.html

Documentation for the AutoTune class, including its constructor and methods.

```APIDOC
## AutoTune Class

### Description
Auto-tuning method for spectral clustering based on the paper "Auto-tuning spectral clustering for speaker diarization using normalized maximum eigengap" (Park et al., 2019).

### Constructor
`AutoTune(p_percentile_min: float = 0.60, p_percentile_max: float = 0.95, init_search_step: float = 0.01, search_level: int = 1, proxy: AutoTuneProxy = AutoTuneProxy.PercentileSqrtOverNME)`

#### Parameters
- **p_percentile_min** (float) - Optional - Minimum value of p_percentile.
- **p_percentile_max** (float) - Optional - Maximum value of p_percentile.
- **init_search_step** (float) - Optional - Initial search step size for auto-tuning.
- **search_level** (int) - Optional - Hierarchical search level for auto-tuning.
- **proxy** (AutoTuneProxy) - Optional - Which proxy to minimize for auto-tuning. Must be an instance of AutoTuneProxy.

### Methods

#### get_percentile_range()

##### Description
Get the current percentile search range.

##### Returns
- **typing.Sequence[float]** - List of percentile values in the search range.

#### update_percentile_range(p_percentile_min: float, p_percentile_max: float, search_step: float)

##### Description
Update the percentile search range.

##### Parameters
- **p_percentile_min** (float) - Required - Minimum value of p_percentile.
- **p_percentile_max** (float) - Required - Maximum value of p_percentile.
- **search_step** (float) - Required - Search step size.

##### Returns
- **typing.Sequence[float]** - Updated list of percentile values.

#### tune(p_percentile_to_ratio: typing.Callable)

##### Description
Tune the hyper-parameter p_percentile. Uses a proxy ratio of DER to tune the hyper-parameter. Also performs side work for affinity refinement, eigen decomposition, and estimating the number of clusters.

##### Parameters
- **p_percentile_to_ratio** (typing.Callable) - Required - A callable that computes the `ratio` given a `p_percentile` value.

##### Returns
- **eigenvectors** (np.ndarray) - Sorted eigenvectors of shape (n_samples, n_samples).
- **n_clusters** (int) - Number of clusters.
- **best_p_percentile** (float) - p_percentile value that minimizes the ratio.
```

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

### SpectralClusterer.__init__

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster/configs.html

Constructor of the SpectralClusterer class, initializing all clustering parameters.

```APIDOC
## SpectralClusterer.__init__

### Description
Constructor of the clusterer. Initializes the spectral clustering algorithm with configurable parameters for clustering behavior, refinement, and fallback options.

### Method
Constructor

### Signature
```python
def __init__(
    self,
    min_clusters: typing.Optional[int] = None,
    max_clusters: typing.Optional[int] = None,
    refinement_options: typing.Optional[RefinementOptions] = None,
    autotune: typing.Optional[AutoTune] = None,
    fallback_options: typing.Optional[FallbackOptions] = None,
    laplacian_type: typing.Optional[LaplacianType] = None,
    stop_eigenvalue: float = 1e-2,
    row_wise_renorm: bool = False,
    custom_dist: typing.Union[str, typing.Callable] = "cosine",
    max_iter: int = 300,
    constraint_options: typing.Optional[ConstraintOptions] = None,
    eigengap_type: EigenGapType = EigenGapType.Ratio,
    max_spectral_size: typing.Optional[int] = None,
    affinity_function: typing.Callable = utils.compute_affinity_matrix,
    post_eigen_cluster_function: typing.Callable = (
        custom_distance_kmeans.run_kmeans)
)
```

### Parameters
- **min_clusters** (Optional[int]) - Optional - Minimal number of clusters allowed (only effective if not None).
- **max_clusters** (Optional[int]) - Optional - Maximal number of clusters allowed (only effective if not None), can be used together with min_clusters to fix the number of clusters.
- **refinement_options** (Optional[RefinementOptions]) - Optional - A RefinementOptions object that contains refinement arguments for the affinity matrix. If None, we will not refine.
- **autotune** (Optional[AutoTune]) - Optional - An AutoTune object to automatically search p_percentile.
- **fallback_options** (Optional[FallbackOptions]) - Optional - A FallbackOptions object to indicate when to run fallback clusterer instead of spectral clusterer.
- **laplacian_type** (Optional[LaplacianType]) - Optional - A LaplacianType. If None, we do not use a laplacian matrix.
- **stop_eigenvalue** (float) - Optional - When computing the number of clusters using Eigen Gap, we do not look at eigen values smaller than this value. Default is 1e-2.
- **row_wise_renorm** (bool) - Optional - If True, perform row-wise re-normalization on the spectral embeddings. Default is False.
- **custom_dist** (Union[str, Callable]) - Optional - Custom distance measure for k-means. If a string, "cosine", "euclidean", "mahalanobis", or any other distance functions defined in scipy.spatial.distance can be used. Default is "cosine".
- **max_iter** (int) - Optional - The maximum number of iterations for the custom k-means. Default is 300.
- **constraint_options** (Optional[ConstraintOptions]) - Optional - A ConstraintOptions object that contains constraint arguments.
- **eigengap_type** (EigenGapType) - Optional - The type of the eigengap computation. Default is EigenGapType.Ratio.
- **max_spectral_size** (Optional[int]) - Optional - The maximal size of input to the spectral clustering algorithm. If this is set, and the actual input size is larger than this value, then we are going to first use hierarchical clustering to reduce the input size to this number. This can significantly reduce the computational cost for steps like Laplacian matrix and eigen decomposition. However, please note that this may degrade the quality of the final clustering results. This corresponds to the U1 value in the multi-stage clustering paper (https://arxiv.org/abs/2210.13690).
- **affinity_function** (Callable) - Optional - A function to compute the affinity matrix from the embeddings. This defaults to (cos(x,y)+1)/2.
- **post_eigen_cluster_function** (Callable) - Optional - A function to cluster the spectral embeddings after the eigenvalue computations. This function must have the same signature as custom_distance_kmeans.run_kmeans.

### Returns
None
```

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

### SpectralClusterer Constructor

Source: https://github.com/wq2012/spectralcluster/blob/master/docs/spectralcluster.html

Documentation for the SpectralClusterer class constructor and its configuration parameters.

```APIDOC
## SpectralClusterer Constructor

### Description
Initializes a SpectralClusterer instance with various configuration options for spectral clustering.

### Parameters
- **min_clusters** (int) - Optional - Minimal number of clusters allowed (only effective if not None).
- **max_clusters** (int) - Optional - Maximal number of clusters allowed (only effective if not None), can be used together with min_clusters to fix the number of clusters.
- **refinement_options** (RefinementOptions) - Optional - A RefinementOptions object that contains refinement arguments for the affinity matrix. If None, we will not refine.
- **autotune** (AutoTune) - Optional - An AutoTune object to automatically search p_percentile.
- **fallback_options** (FallbackOptions) - Optional - A FallbackOptions object to indicate when to run fallback clusterer instead of spectral clusterer.
- **laplacian_type** (LaplacianType) - Optional - A LaplacianType. If None, we do not use a laplacian matrix.
- **stop_eigenvalue** (float) - Optional - When computing the number of clusters using Eigen Gap, we do not look at eigen values smaller than this value.
- **row_wise_renorm** (bool) - Optional - If True, perform row-wise re-normalization on the spectral embeddings.
- **custom_dist** (str or callable) - Optional - Custom distance measure for k-means. If a string, "cosine", "euclidean", "mahalanobis", or any other distance functions defined in scipy.spatial.distance can be used.
- **max_iter** (int) - Optional - The maximum number of iterations for the custom k-means.
- **constraint_options** (ConstraintOptions) - Optional - A ConstraintOptions object that contains constraint arguments.
- **eigengap_type** (str) - Optional - The type of the eigengap computation.
- **max_spectral_size** (int) - Optional - The maximal size of input to the spectral clustering algorithm. If this is set, and the actual input size is larger than this value, then we are going to first use hierarchical clustering to reduce the input size to this number. This can significantly reduce the computational cost for steps like Laplacian matrix and eigen decomposition. However, please note that this may degrade the quality of the final clustering results. This corresponds to the U1 value in the multi-stage clustering paper (https://arxiv.org/abs/2210.13690).
- **affinity_function** (callable) - Optional - A function to compute the affinity matrix from the embeddings. This defaults to (cos(x,y)+1)/2.
- **post_eigen_cluster_function** (callable) - Optional - A function to cluster the spectral embeddings after the eigenvalue computations. This function must have the same signature as custom_distance_kmeans.run_kmeans.
```
Tokens:
Raw