cluster_embeddings

Eqivalent to cluster_dataset, but instead of a dataset expects a column of embeddings as input. The input may e.g. be word2vec embeddings from an embed_text step, or whole dataset embeddings from an embed_dataset step. Optionally reduces the dimensionality of the embeddings (by default using UMAP). This may help with making the data denser (counteracting the “curse-of-dimensionality”), and thus making it potentially easier to identify clusters. The clustering algorithm used by default is (HDBSCAN), which produces a column of positive cluster IDs, or -1 if a data point is considered noise (not belonging to any cluster). For further detail on HDBSCAN’s parameters see its documentation here (for usage) and here (for its API).

Usage

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

Examples

Example 1
Signature

The following configuration applies clustering with the default values:

cluster_embeddings(ds, {
  "algorithm": "hdbscan",
  "min_cluster_size": 120,
  "min_samples": 15,
  "reduce": {
      "weights": null,
      "weights_max": 32,
      "weights_exp": 2,
      "algorithm": "umap",
      "n_components": 10,
      "n_neighbors": 100,
      "min_dist": 0,
      "random_state": 42
  }
}) -> (ds.cluster)

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.

cluster_embeddings(embeddings: list[number], {
    "param": value,
    ...
}) -> (*cluster: column)

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").

Inputs

column[list[number]]

required

A column of embeddings (list/vectors of numbers).

Outputs

column

One or two columns containing the clustering results. If one column name is provided, the single output will contain the cluster labels. If two column names are provided, the second column will contain the the probability that a data points belongs to the assigned cluster.

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

Parameters

string

default:"euclidean"

The metric used to calculate similarity between data points.Values must be one of the following:euclidean manhattan chebyshev minkowski canberra braycurtis haversine mahalanobis wminkowski seuclidean cosine correlation hamming jaccard dice russellrao kulsinski rogerstanimoto sokalmichener sokalsneath yule

string

default:"hdbscan"

Algorithm to use. The name of a supported clustering algorithm (currently allows "hdbscan" only).Values must be one of the following:

hdbscan

integer

default:"120"

Minimum cluster size. The minimum size for considering a region of dense data points a proper cluster.Values must be in the following range:

1 ≤ min_cluster_size < inf

integer

default:"15"

The larger the value, the more conservative the clustering. More points will be declared as noise, and clusters will be restricted to progressively more dense areas.Values must be in the following range:

1 ≤ min_samples < inf

[object, null]

Umap configuration. See more here. Params for dimensionality reduction.

Properties

string

default:"umap"

Algorithm. The name of a supported dimensionality reduction algorithm.Values must be one of the following:

umap

boolean

default:"true"

Toggle encoding of feature columns. When enabled, Graphext will auto-convert any column types to the numeric type before (optionally) reducing the data’s dimensionality. How this conversion is done can be configured using the feature_encoder option below.

If disabled, the dimensionality reduction algorithm applied in this step will assume that input data is already numerical and doesn’t contain any missing values.

[null, object]

Configures encoding of feature columns. By default (null), Graphext chooses automatically how to convert any column types the model may not understand natively to a numeric type.A configuration object can be passed instead to overwrite specific parameter values with respect to their default values.

Properties

object

Numeric encoder. Configures encoding of numeric features.

Properties

boolean

Toggle the addition of a column using 0s and 1s to indicate where an input column contained missing values.

[null, string]

Whether and how to impute (replace/fill) missing values.Values must be one of the following:

Mean
Median
MostFrequent
Const
None

[null, string]

Whether and how to scale the final numerical values (across a single column).Values must be one of the following:

Standard
Robust
KNN
None

object

Further parameters passed to the scaler function. Details depend no the particular scaler used.

object

Boolean encoder. Configures encoding of boolean features.

Properties

boolean

Toggle the addition of a column using 0s and 1s to indicate where an input column contained missing values.

[null, string]

Whether and how to impute (replace/fill) missing values.Values must be one of the following:

MostFrequent
Const
None

object

Ordinal encoder. Configures encoding of categorical features that have a natural order.

Properties

boolean

Toggle the addition of a column using 0s and 1s to indicate where an input column contained missing values.

[null, string]

Whether and how to impute (replace/fill) missing values.Values must be one of the following:

MostFrequent
Const
None

[object, object]

Category encoder. May contain either a single configuration for all categorical variables, or two different configurations for low- and high-cardinality variables. For further details pick one of the two options below.

Options

Simple category encoder
Conditional category encoder

boolean

Toggle the addition of a column using 0s and 1s to indicate where an input column contained missing values.

[null, string]

Whether and how to impute (replace/fill) missing values.Values must be one of the following:

MostFrequent
Const
None

[null, integer]

Maximum number of unique categories to encode. Only the N-1 most common categories will be encoded, and the rest will be grouped into a single “Others” category.Values must be in the following range:

1 ≤ max_categories < inf

[null, string]

How to encode categories.Values must be one of the following:OneHot Label Ordinal Binary Frequency None

[null, string]

Whether and how to scale the final numerical values (across a single column).Values must be one of the following:

Standard
Robust
KNN
None

integer

Condition for application of low- or high-cardinality configuration. Number of unique categories below which the low_cardinality configuration is used, and above which the high_cardinality configuration is used.Values must be in the following range:

3 ≤ cardinality_treshold < inf

object

Low cardinality configuration. Used for categories with fewer than cardinality_threshold unique categories.

Properties

boolean

Toggle the addition of a column using 0s and 1s to indicate where an input column contained missing values.

[null, string]

Whether and how to impute (replace/fill) missing values.Values must be one of the following:

MostFrequent
Const
None

[null, integer]

1 ≤ max_categories < inf

[null, string]

How to encode categories.Values must be one of the following:OneHot Label Ordinal Binary Frequency None

[null, string]

Whether and how to scale the final numerical values (across a single column).Values must be one of the following:

Standard
Robust
KNN
None

object

High cardinality configuration. Used for categories with more than cardinality_threshold unique categories.

Properties

boolean

Toggle the addition of a column using 0s and 1s to indicate where an input column contained missing values.

[null, string]

Whether and how to impute (replace/fill) missing values.Values must be one of the following:

MostFrequent
Const
None

[null, integer]

1 ≤ max_categories < inf

[null, string]

How to encode categories.Values must be one of the following:OneHot Label Ordinal Binary Frequency None

[null, string]

Whether and how to scale the final numerical values (across a single column).Values must be one of the following:

Standard
Robust
KNN
None

[object, object]

Multilabel encoder. Configures encoding of multivalued categorical features (variable length lists of categories, or the semantic type list[category] for short). May contain either a single configuration for all multilabel variables, or two different configurations for low- and high-cardinality variables. For further details pick one of the two options below.

Options

Simple multilabel encoder
Conditional multilabel encoder

boolean

Toggle the addition of a column using 0s and 1s to indicate where an input column contained missing values.

[null, string]

How to encode categories/labels in multilabel (list[category]) columns.Values must be one of the following:

Binarizer
TfIdf
None

[null, integer]

Maximum number of categories/labels to encode. If a number is provided, the result of the encoding will be reduced to these many dimensions (columns) using scikit-learn’s truncated SVD. When applied together with (after a) Tf-Idf encoding, this performs a kind of latent semantic analysis.Values must be in the following range:

2 ≤ max_categories < inf

[null, string]

How to scale the encoded (numerical columns).Values must be one of the following:

Euclidean
KNN
Norm
None

integer

3 ≤ cardinality_treshold < inf

object

Low cardinality configuration. Used for mulitabel columns with fewer than cardinality_threshold unique categories/labels.

Properties

boolean

Toggle the addition of a column using 0s and 1s to indicate where an input column contained missing values.

[null, string]

How to encode categories/labels in multilabel (list[category]) columns.Values must be one of the following:

Binarizer
TfIdf
None

[null, integer]

2 ≤ max_categories < inf

[null, string]

How to scale the encoded (numerical columns).Values must be one of the following:

Euclidean
KNN
Norm
None

object

High cardinality configuration. Used for categories with more than cardinality_threshold unique categories.

Properties

boolean

Toggle the addition of a column using 0s and 1s to indicate where an input column contained missing values.

[null, string]

How to encode categories/labels in multilabel (list[category]) columns.Values must be one of the following:

Binarizer
TfIdf
None

[null, integer]

2 ≤ max_categories < inf

[null, string]

How to scale the encoded (numerical columns).Values must be one of the following:

Euclidean
KNN
Norm
None

object

Datetime encoder. Configures encoding of datetime (timestamp) features.

Properties

boolean

Toggle the addition of a column using 0s and 1s to indicate where an input column contained missing values.

array[string]

A list of numerical components to extract. Will create one numeric column for each component.

Array items

string

Each item in array.Values must be one of the following:day dayofweek dayofyear hour minute month quarter season second week weekday weekofyear year

array[string]

A list of cyclical time features to extract. “Cycles” are numerical transformations of features that should be represented on a circle. E.g. months, ranging from 1 to 12, should be arranged such that 12 and 1 are next to each other, rather than on opposite ends of a linear scale. We represent such cyclical time features on a circle by creating two columns for each original feature: the sin and cos of the numerical feature after appropriate scaling.

Array items

string

Each item in array.Values must be one of the following:

day
dayofweek
dayofyear
hour
month

[null, boolean]

Whether to include the epoch as new feature (seconds since 01/01/1970).

[null, string]

Whether and how to impute (replace/fill) missing values.Values must be one of the following:

Mean
Median
MostFrequent
Const
None

[null, string]

Whether and how to scale the final numerical values (across a single column).Values must be one of the following:

Standard
Robust
KNN
None

[null, string]

How to scale the encoded (numerical columns).Values must be one of the following:

Euclidean
KNN
Norm
None

object

Embedding/vector encoder. Configures encoding of multivalued numerical features (variable length lists of numbers, i.e. vectors, or the semantic type list[number] for short).

Properties

boolean

Toggle the addition of a column using 0s and 1s to indicate where an input column contained missing values.

[null, string]

How to scale the encoded (numerical columns).Values must be one of the following:

Euclidean
KNN
Norm
None

object

Text encoder. Configures encoding of text (natural language) features. Currently only allows Tf-Idf embeddings to represent texts. If you wish to use other embeddings, e.g. semantic, Word2Vec etc., transform your text column first using another step, and then use that result instead of the original texts.

Texts are excluded by default from the overall encoding of the dataset. See parameter include_text_features below to active it.

Properties

boolean

Toggle the addition of a column using 0s and 1s to indicate where an input column contained missing values.

object

Parameters to be passed to the text encoder (Tf-Idf parameters only for now). See scikit-learn’s documentation for detailed parameters and their explanation.

integer

How many output features to generate. The resulting Tf-Idf vectors will be reduced to these many dimensions (columns) using scikit-learn’s truncated SVD. This performs a kind of latent semantic analysis. By default we will reduce to 200 components.Values must be in the following range:

2 ≤ n_components ≤ 1024

[null, string]

How to scale the encoded (numerical columns).Values must be one of the following:

Euclidean
KNN
Norm
None

boolean

default:"false"

Whether to include or ignore text columns during the processing of input data. Enabling this will convert texts to their Tf-Idf representation. Each text will be converted to an N-dimensional vector in which each component measures the relative “over-representation” of a specific word (or n-gram) relative to its overall frequency in the whole dataset. This is disabled by default because it will often be better to convert texts explicitly using a previous step, such as embed_text or embed_text_with_model.

[object, null]

Weights used to multiply the normalized columns/features after vectorization. Should be a dictionary/object of {"column_name": weight, ...} items. Will be scaled using the parameters weights_max, and weights_exp before being applied. So only the relative weight of the columns is important here, not their absolute values.

Item properties

number

A "column_name": numeric_weight pair. Each column name must refer to an existing column in the dataset.

Examples

{"date": 0.5, "age": 2}

[object, null]

Weights used to multiply the normalized columns/features after vectorization. Should be a dictionary/object of "type": weight" items. Will be scaled using the parameters weights_max, and weights_exp before being applied. So only the relative weight of the columns is important here, not their absolute values.

Properties

number

Weight for columns of type Number

number

Weight for columns of type Datetime

number

Weight for columns of type Category

number

Weight for columns of type Ordinal

number

Weight for columns of type Embedding (List[Number]).

number

Weight for columns of type Multilabel (List[Category]).

number

default:"32"

Maximum weight to scale the normalized columns with.Values must be in the following range:

0 ≤ weights_max < inf

integer

default:"2"

Weight exponent. Weights will be raised to this power before(!) scaling to weights_max. This allows for a non-linear mapping from input weights to those used eventually to multiply the normalized columns.

integer

default:"100"

Number of neighbours. Use smaller numbers to concentrate on the local structure in the data, and larger values to focus on the more global structure.For further details see here.Values must be in the following range:

1 ≤ n_neighbors < inf

number

default:"0.1"

Minimum distance between reduced data points. Controls how tightly UMAP is allowed to pack points together in the reduced space. Smaller values will lead to points more tightly packed together (potentially useful if result is used to cluster the points). Larger values will distribute points with more space between them (which may be desirable for visualization, or to focus more on the global structure of the date).For further details see here.Values must be in the following range:

0 ≤ min_dist < inf

integer

default:"10"

Dimensionality of the reduced data.Values must be in the following range:

1 ≤ n_components < inf

string

default:"euclidean"

Metric to use for measuring similarity between data points.Values must be one of the following:euclidean manhattan chebyshev minkowski canberra braycurtis haversine mahalanobis wminkowski seuclidean cosine correlation hamming jaccard dice russellrao kulsinski rogerstanimoto sokalmichener sokalsneath yule

[integer, null]

Number of training iterations used in optimizing the embedding. Larger values result in more accurate embeddings. If null is specified a value will be selected based on the size of the input dataset (200 for large datasets, 500 for small).

string

default:"auto"

How to initialize the low dimensional embedding. When “spectral”, uses a (relatively expensive) spectral embedding. “pca” uses the first n_components from a principal component analysis. “tswspectral” is a cheaper alternative to “spectral”. When “random”, assigns initial embedding positions at random. This uses the least amount of memory and time but may make UMAP slower to converge on the optimal embedding. “auto” selects between “spectral” and “random” automatically depending on the size of the dataset.Values must be one of the following:

spectral
pca
tswspectral
random
auto

[boolean, string, null]

default:"auto"

Avoid excessive memory use. For some datasets nearest neighbor computations can consume a lot of memory. If you find the step is failing due to memory constraints, consider setting this option to true. This approach is more computationally expensive, but avoids excessive memory use. Setting it to “auto”, will enable this mode automatically depending on the size of the dataset.Values must be one of the following:

True
False
auto
None

[string, null]

Target variable (labels) for supervised dimensionality reduction. Name of the column that contains your target values (labels).

number

default:"0.5"

Weighting factor between features and target. A value of 0.0 weights entirely on data, and a value of 1.0 weights entirely on target. The default of 0.5 balances the weighting equally between data and target.

boolean

default:"false"

Try to better preserve local densities in the data. Specifies whether the density-augmented objective of densMAP should be used for optimization. Turning on this option generates an embedding where the local densities are encouraged to be correlated with those in the original space.

number

default:"2.0"

Strength of local density preservation. Controls the regularization weight of the density correlation term in densMAP. Higher values prioritize density preservation over the UMAP objective, and vice versa for values closer to zero. Setting this parameter to zero is equivalent to running the original UMAP algorithm.

boolean

default:"false"

Drop duplicate rows before embedding. If you have more duplicates than you have n_neighbors you can have the identical data points lying in different regions of your space. It also violates the definition of a metric. This option will remove duplicates before embedding, and then map the original data points back to the reduced space. Duplicate data points will be placed in the exact same location as the original data points.

[integer, null]

default:"42"

A random number to initialize the algorithm for reproducibility.

Analyse

Report

Prepare

Usage

Inputs & Outputs

Configuration

​Usage

​Inputs & Outputs

​Configuration

Usage

Inputs & Outputs

Configuration