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

> Create network links between rows/nodes calculating the similarity of embeddings (vectors). 

Uses Spotify's `Annoy` to perform approximate nearest neighbour search.

## Usage

The following examples show how the step can be used in a recipe.

<Accordion title="Examples" icon="code" defaultOpen="true">
  <Tabs>
    <Tab title="Example 1">
      To link similar embeddings with default configuration

      ```stan theme={null}
      link_embeddings(ds.embedding) -> (ds.targets, ds.weights)
      ```
    </Tab>

    <Tab title="Example 2">
      To use a similarity cutoff below which similar embeddings won't be connected

      ```stan theme={null}
      link_embeddings(ds.embedding, {"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_embeddings(embedding: list[number], {
          "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>
</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 neighbours to connect to.

    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.

    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.

    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>