> ## 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.

# link_grouped_embeddings

> Create network links calculating the similarity of embeddings (vectors) within groups. 

Creates network links only if the row's embeddings belong to the same group.

E.g., text embeddings calculated for different languages are not necessarily compatible (even if they
have the same dimension). Use this step if embeddings in different groups cannot be compared directly.

## 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">
      To configure a minimum similarity between embeddings to create a link

      ```stan theme={null}
      link_grouped_embeddings(ds.embedding, ds.group, {
        "similarity_min": 0.7
      }) -> (ds.targets, ds.weights)
      ```
    </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}
      link_grouped_embeddings(embedding: list[number], grouping: category, {
          "param": value,
          ...
      }) -> (targets: column, weights: 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="embedding" type="column[list[number]]" required>
    A categorical column containing embeddings (numerical vectors/lists). Usually the result of previously executing a step embed\_\[entity].
  </ParamField>

  <ParamField path="grouping" type="column[category]" required>
    A categorical column identifying the groups whose embeddings are compatible.
  </ParamField>
</Accordion>

<Accordion title="Outputs" icon="right-from-bracket">
  <ParamField path="targets" type="column" required>
    A column containing for each row a list of IDs (row numbers) identfying other rows it will be linked to.
  </ParamField>

  <ParamField path="weights" type="column" required>
    A column containing for each row a list of weights identfying the "importance" of each link to
    targets identified in the `targets` column.
  </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="n_nearest" type="integer" default="15">
    Number of nearest embeddings to take into account.

    Values must be in the following range:

    ```javascript theme={null}
    1 ≤ n_nearest < inf
    ```
  </ParamField>

  <ParamField path="similarity_min" type="number" default="0">
    Minimum similarity for connecting two nodes (similarity ∈ \[0, 1]).

    Values must be in the following range:

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

  <ParamField path="similarity_min_q" type="number" default="0">
    Minimum similarity for connecting two nodes, expressed as a quantile of the similarity distribution (similarity ∈ \[0, 1]).

    Values must be in the following range:

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

  <ParamField path="n_trees" type="integer" default="30">
    Number of trees.
    Affects the build time and the index size. A larger value will give more accurate results, but will take
    longer to create a larger index.
  </ParamField>

  <ParamField path="search_k_mult" type="integer" default="2">
    Accuracy multipler.
    A larger value will give more accurate results, but will take longer time to return.
  </ParamField>

  <ParamField path="metric" type="string" default="angular">
    Metric to use, only angular supported for now.
    Annoy's angular metric is equivalent to sqrt(2\*(1-cos(u,v))), whose max. is sqrt(2\*2) = 2.
    I.e. the distance between (1,0) and (-1,0), at maximum angular separation, should be exactly 2
    Note that for the weights of the resulting network links Annoy's distances are converted to similarities in the interval \[0,1].

    Values must be one of the following:

    * `angular`
    * `euclidean`
    * `manhattan`
    * `hamming`
    * `dot`
  </ParamField>

  <ParamField path="seed" type="number">
    Used to seed the random number generator, creating deterministic results.
  </ParamField>
</Accordion>