> For the complete documentation index, see [llms.txt](https://docs.sov.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sov.ai/pattern-recognition/clustering-panels.md).

# Clustering Panels

`Tutorials` are the best documentation — [<mark style="color:blue;">`Clustering Panels Tutorial`</mark>](https://colab.research.google.com/github/sovai-research/sovai-public/blob/main/notebooks/computational/Clustering%20Notebook.ipynb)

### Introduction

Can be used to cluster any panel dataset. It is particularly useful for financial analysts, data scientists, and researchers working with time-series data across multiple entities (e.g., stocks, companies) and variables.

#### Initialization

The CustomDataFrame can be initialized using the `sov.data()` function:

```python
import sovai as sov

sov.token_auth(token="your_token_here")
df = sov.data("accounting/weekly")
```

Basic Clustering

Perform clustering on all features:

```python
df_cluster = df.cluster()
```

<figure><img src="/files/dObF9VsdxqJAXIokCUpj" alt=""><figcaption></figcaption></figure>

Feature-Specific Clustering

Cluster based on specific features:

```python
df_cluster_ebit = df.cluster(features=["ebit"])
df_cluster_multi = df.cluster(features=["total_assets", "total_debt", "ebit"])
```

#### Summary Clustering

Get a quick summary of the last 6-months data:

```python
df.cluster("summary")
```

<figure><img src="/files/x9CecNpGmHZMdeqniGg5" alt=""><figcaption></figcaption></figure>

### Visualization Methods

#### Line Plot

Visualize cluster centroids and distances:

```python
df.cluster("line_plot")
```

<figure><img src="/files/jPqTTnQRRmtytDonGvxe" alt=""><figcaption></figcaption></figure>

**Scatter Plot**

Create a scatter plot of clustered data:

```python
df.cluster("scatter_plot")
```

<figure><img src="/files/tpKu5RwXCE7gcIyk8YbC" alt=""><figcaption></figcaption></figure>

#### Animation Plot

Generate an animated plot of cluster evolution:

```python
df.cluster("animation_plot")
```

<figure><img src="/files/asX5nJ12BCFqFqplAM7L" alt=""><figcaption></figcaption></figure>

### Advanced Analysis

#### Distance Calculation

Calculate distances between ticker-cluster combinations:

```python
df_dist = df_cluster.drop(columns=["labels"]).distance(orient="time-series")
```

<figure><img src="/files/OGFGbJetRv7NYiqB2zj1" alt=""><figcaption></figcaption></figure>

### Examples

#### Basic Clustering and Visualization

```python
import sovai as sov

sov.token_auth(token="your_token_here")
df_accounting = sov.data("accounting/weekly")
df_mega = df_accounting.select_stocks("mega").date_range("2018-01-01")
df_cluster = df_mega.cluster()
df_mega.cluster("line_plot")
```

#### Feature-Specific Clustering and Distance Analysis

```python
df_cluster_ebit = df_mega.cluster(features=["ebit"])
df_dist = df_cluster_ebit.drop(columns=["labels"]).distance(orient="time-series")
similar_to_amzn = df_dist.sort_values(["AMZN"])[["AMZN"]].T
```