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

# embed_with_trees

> Reduce the dataset to an n-dimensional numeric vector embedding using a Forest model's tree indices. 

Usually employed after the `train_classifcation` or `train_regression` steps with RandomForest/ExtraTrees/Catboost models.
???+ info "Prediction Model"
To use this step successfully you need to make sure the dataset you're predicting on is
as similar as possible to the one the model was trained on. We check that the necessary data
types and columns are present, but you should pay attention to how you handled these in the
recipe the model was generated. Any changes might lead to a significant degradation in
model performance.

This process needs a pre-trained RandomForest, ExtraTrees or Catboost model trained through the `train_classification` or `train_regression` methods on the same dataset that is used as input.
By calling this method, each data point in the dataset is passed through the trees in the forest,
and the leaf node where each data point ends up in each tree is recorded.
The indices of these leaf nodes across all trees in the forest are then used to form a sparse
high-dimensional representation of each data point. This representation can be thought of as an embedding,
where the position of each data point in this high-dimensional space captures aspects of its similarity
to other data points, as determined by the structure of the trees in the model.
For more detailed information on the method followed, you can check the `apply` method of sklearns' forest classes
and its usage [here](https://scikit-learn.org/stable/modules/generated/sklearn.ensemble.RandomForestClassifier.html#sklearn.ensemble.RandomForestClassifier.apply).

## 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, simplest, example, creates a new embedding column from a dataset and a RandomForest model.

      ```stan theme={null}
      embed_with_trees(ds, "rf") -> (ds.embedding)
      ```
    </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}
      embed_with_trees(ds: dataset, model: file
      ) -> (embedding: list[number])
      ```
    </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="ds" type="dataset" required>
    An arbitrary input dataset.
  </ParamField>

  <ParamField path="model" type="file" required>
    A trained model of the RandomForest, ExtraTrees or Catboost kind.
  </ParamField>
</Accordion>

<Accordion title="Outputs" icon="right-from-bracket">
  <ParamField path="embedding" type="column[list[number]]" required>
    A column containing embedding vectors (lists of numbers) numerically representing the correspoding rows in `ds`.
  </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">
  This step doesn't expect any configuration.
</Accordion>