> ## Documentation Index
> Fetch the complete documentation index at: https://docs.graphext.com/llms.txt
> Use this file to discover all available pages before exploring further.

# merge_similar_semantics

> Group categories with similar meanings. 

This step calculates embeddings for each category using GloVe vectors provided by spaCy's models.
As similar words will have similar embeddings, we use them to cluster the categories, obtaining new
categories that groups the original ones.

## Usage

The following example shows how the step can be used in a recipe.

<Accordion title="Examples" icon="code" defaultOpen="true">
  <Tabs>
    <Tab title="Example 1">
      The following configuration applies the algorithm with the default values:

      ```stan theme={null}
      merge_similar_semantics(ds.categories, ds.lang) -> (ds.new_categories)
      ```
    </Tab>

    <Tab title="Signature">
      General syntax for using the step in a recipe. Shows the inputs and outputs the step is expected to receive and will produce respectively. For futher details see sections below.

      ```stan theme={null}
      merge_similar_semantics(col: category|text|list[category], language: category, {
          "param": value,
          ...
      }) -> (categories: column)
      ```
    </Tab>
  </Tabs>
</Accordion>

## Inputs & Outputs

The following are the inputs expected by the step and the outputs it produces. These are generally
columns (`ds.first_name`), datasets (`ds` or `ds[["first_name", "last_name"]]`) or models (referenced
by name e.g. `"churn-clf"`).

<Accordion title="Inputs" icon="right-to-bracket">
  <ParamField path="col" type="column[category|text|list[category]]" required>
    Column with categories to merge.
  </ParamField>

  <ParamField path="language" type="column[category]" required />
</Accordion>

<Accordion title="Outputs" icon="right-from-bracket">
  <ParamField path="categories" type="column" required>
    Column containing merged categories.
  </ParamField>
</Accordion>

## Configuration

The following parameters can be used to configure the behaviour of the step by including them in
a json object as the last "input" to the step, i.e. `step(..., {"param": "value", ...}) -> (output)`.

<Accordion title="Parameters" defaultOpen="true" icon="sliders">
  <ParamField path="distance_threshold" type="number" default="0.1">
    Determines which categories will be merged.
    After hierarchically clustering all categories, clusters of categories closer than this distance
    will be merged into one.

    Also see details in [scikit-learn's Agglomerative Clustering](https://scikit-learn.org/stable/modules/clustering.html#hierarchical-clustering).

    Values must be in the following range:

    ```javascript theme={null}
    0 ≤ distance_threshold ≤ 1
    ```
  </ParamField>

  <ParamField path="linkage" type="string" default="single">
    Which linkage criterion to use in the clustering.
    While the distance metric applied is always the cosine between category embeddings, this parameter
    determines how to calculate the distance between clusters of embeddings, e.g. selecting the maximum
    distance between categories in two clusters ("complete"), the minimum ("single") etc.

    Also see details in [scikit-learn's Agglomerative Clustering](https://scikit-learn.org/stable/modules/clustering.html#hierarchical-clustering).

    Values must be one of the following:

    * `single`
    * `ward`
    * `complete`
    * `average`
  </ParamField>
</Accordion>