Market Graph Clustering API Reference
Data
Data model for Market Graph Clustering use case.
MarketGraphClusteringData
Bases: UcData
Data for the Market Graph Clustering use case.
This use case clusters stocks based on their return correlations using a k-medoids approach on a correlation-derived distance metric.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
Literal['market_graph_clustering']
|
Identifier for this data type. |
returns_matrix |
NumPyArray
|
An n_stocks x n_observations matrix of stock returns. |
k |
int
|
Number of clusters to form. |
stock_names |
list[str]
|
Identifiers for each stock. |
from_corr_matrix(corr_matrix: np.ndarray, k: int, stock_names: list[str] | None = None) -> MarketGraphClusteringData
classmethod
Create data from a symmetric correlation matrix.
The correlation matrix is symmetrised via (C + C^T) / 2 to
guard against small floating-point asymmetries.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
corr_matrix
|
ndarray
|
An n_stocks x n_stocks symmetric correlation matrix. |
required |
k
|
int
|
Number of clusters to form. |
required |
stock_names
|
list[str] | None
|
Identifiers for each stock. Auto-generated if |
None
|
Returns:
| Type | Description |
|---|---|
MarketGraphClusteringData
|
A data instance backed by the correlation matrix. |
plot(*, ax: Axes | None = None) -> Axes
Plot the correlation matrix as a heatmap.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ax
|
Axes | None
|
Matplotlib axes to draw on. Creates a new figure if |
None
|
Returns:
| Type | Description |
|---|---|
Axes
|
The axes with the plot. |
to_string() -> str
Return a string describing the data.
Returns:
| Type | Description |
|---|---|
str
|
String representation of the data. |
generate_random(n_stocks: int = 6, n_observations: int = 20, k: int = 2, seed: int | None = None) -> MarketGraphClusteringData
staticmethod
Generate a random Market Graph Clustering instance.
Creates correlated groups of stock returns to simulate market sectors.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_stocks
|
int
|
Number of stocks, by default 6. |
6
|
n_observations
|
int
|
Number of return observations per stock, by default 20. |
20
|
k
|
int
|
Number of clusters, by default 2. |
2
|
seed
|
int | None
|
Random seed for reproducibility, by default None. |
None
|
Returns:
| Type | Description |
|---|---|
MarketGraphClusteringData
|
A randomly generated data instance. |
Formulation
Formulation for Market Graph Clustering use case.
MarketGraphClusteringFormulation
Bases: UcFormulation[MarketGraphClusteringData, MarketGraphClusteringSolution]
Constraint-based formulation for Market Graph Clustering.
Preprocessing converts Pearson correlations to distances using d_ij = sqrt(0.5 * (1 - corr_ij)), then applies the standard k-medoids formulation.
Mathematical Formulation
Decision Variables: z_i in {0,1}: 1 if stock i is a medoid y_{i,j} in {0,1}: 1 if stock i is assigned to medoid j
Objective: minimize sum_{i,j} d[i][j] * y[i,j]
Constraints: 1. Exactly k medoids: sum_i z[i] == k 2. Each stock assigned to one medoid: sum_j y[i,j] == 1 for all i 3. Assign only to medoids: y[i,j] <= z[j] for all i,j 4. Medoid self-assignment: y[j,j] >= z[j] for all j
to_string(data: MarketGraphClusteringData) -> str
staticmethod
Return a string describing the formulation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
MarketGraphClusteringData
|
The problem data. |
required |
Returns:
| Type | Description |
|---|---|
str
|
String representation of the formulation. |
formulate(data: MarketGraphClusteringData) -> Model
staticmethod
Formulate the Market Graph Clustering problem.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
MarketGraphClusteringData
|
The problem data. |
required |
Returns:
| Type | Description |
|---|---|
Model
|
A Luna Model ready to be solved. |
interpret(solution: Solution, data: MarketGraphClusteringData) -> MarketGraphClusteringSolution
staticmethod
Extract solution from quantum result.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
solution
|
Solution
|
The quantum solution. |
required |
data
|
MarketGraphClusteringData
|
The problem data. |
required |
Returns:
| Type | Description |
|---|---|
MarketGraphClusteringSolution
|
Structured solution with metrics. |
Solution
Solution model for Market Graph Clustering use case.
MarketGraphClusteringSolution
Bases: UcSolution
Solution for the Market Graph Clustering use case.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
Literal['market_graph_clustering']
|
Identifier for this solution type. |
medoids |
list[str]
|
List of selected medoid stock names. |
cluster_assignments |
dict[str, str]
|
Mapping from each stock to its assigned medoid (str keys for JSON). |
total_objective |
float
|
Sum of correlation-derived distances from each stock to its medoid. |
is_valid |
bool
|
Whether the solution satisfies all constraints. |
plot(data: MarketGraphClusteringData | None = None, *, ax: Axes | None = None) -> Axes
Plot the clustering solution as a return-vs-volatility scatter.
Each stock is positioned by its mean return (x-axis) and volatility (y-axis). Stocks are coloured by cluster, with medoids shown as larger square markers. Light lines connect each stock to its medoid.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
MarketGraphClusteringData | None
|
Problem data used to compute return and volatility coordinates.
When |
None
|
ax
|
Axes | None
|
Matplotlib axes to draw on. Creates a new figure if |
None
|
Returns:
| Type | Description |
|---|---|
Axes
|
The axes with the plot. |
to_string() -> str
Return a string describing the solution.
Returns:
| Type | Description |
|---|---|
str
|
String representation of the solution. |
Instance
Instance model for MarketGraphClustering use case.
MarketGraphClusteringInstance
Bases: UcInstance[MarketGraphClusteringData, MarketGraphClusteringFormulation, MarketGraphClusteringSolution]
Instance combining data and formulation for MarketGraphClustering.
Collection
Collection of Market Graph Clustering instances.
MarketGraphClusteringCollection
Bases: UcInstanceCollection[MarketGraphClusteringInstance]
Collection of Market Graph Clustering instances.
from_random(min_size: int, max_size: int, num_instances: int = 1, *, n_observations: int = 20, k: int = 2, seed: int | None = None) -> MarketGraphClusteringCollection
classmethod
Generate random Market Graph Clustering instances.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
min_size
|
int
|
Minimum number of stocks. |
required |
max_size
|
int
|
Maximum number of stocks. |
required |
num_instances
|
int
|
Number of instances per size, by default 1. |
1
|
n_observations
|
int
|
Number of return observations, by default 20. |
20
|
k
|
int
|
Number of clusters, by default 2. |
2
|
seed
|
int | None
|
Random seed for reproducibility, by default None. |
None
|
Returns:
| Type | Description |
|---|---|
MarketGraphClusteringCollection
|
Collection containing generated instances. |