> ## Documentation Index
> Fetch the complete documentation index at: https://systematica.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Trial Selectors

> systematica.tuners.trial_selectors

## `TrialSelector`

```python theme={null}
TrialSelector(
    strategies: List[systematica.tuners.base.BaseTrialSelector],
)
```

Wrapper for parameter selectors.

This class allows multiple selection strategies to be run on the same data.

Method generated by attrs for class TrialSelector.

### Instance variables

* `strategies: List[systematica.tuners.base.BaseTrialSelector]`: List of selector strategies to apply.

### Methods

#### `run_all`

```python theme={null}
run_all(
    self,
    df: pandas.core.frame.DataFrame,
) ‑> dict
```

Run all selector strategies on the provided data.

**Parameters**:

| Name | Type               | Default | Description                    |
| ---- | ------------------ | ------- | ------------------------------ |
| `df` | `pandas.DataFrame` | `--`    | Data to run the strategies on. |

**Returns**:

| Type   | Description                                             |
| ------ | ------------------------------------------------------- |
| `dict` | Dictionary mapping strategy names to selection results. |

## `ElbowPoint`

```python theme={null}
ElbowPoint(
    x: str,
    y: str,
    name=None,
)
```

Selects the point with maximum curvature on the Pareto front.

This strategy finds the "elbow" or point of maximum curvature where improvement
in one objective starts requiring large sacrifices in the other.

The elbow point represents the best trade-off between competing objectives
and is computed as the point with maximum curvature in normalized space.

Method generated by attrs for class ElbowPoint.

### Ancestors

* `systematica.tuners.base.BaseTrialSelector`
* `abc.ABC`

### Instance variables

* `x: str`: Column name for the x-axis metric (typically Sharpe ratio).

* `y: str`: Column name for the y-axis metric (typically returns).

### Methods

#### `run`

```python theme={null}
run(
    self,
    df: pandas.core.frame.DataFrame,
) ‑> pandas.core.series.Series
```

Execute the elbow point selection algorithm.

**Parameters**:

| Name | Type           | Default | Description                                     |
| ---- | -------------- | ------- | ----------------------------------------------- |
| `df` | `pd.DataFrame` | `--`    | DataFrame containing parameters to select from. |

**Returns**:

| Type        | Description                                                    |
| ----------- | -------------------------------------------------------------- |
| `pd.Series` | The selected parameter combination or None if selection fails. |

## `Preference`

```python theme={null}
Preference(
    x: str,
    y: str,
    alpha: float = 0.5,
    name=None,
)
```

Selects based on weighted preferences between objectives.

This method computes a scalarized score:

$$
score = \alpha O_1 + (1-\alpha) O_2
$$

Where $O_1$ and $O_2$ are the two objectives (e.g., Sharpe ratio and returns),
and $\alpha$ is a weight coefficient. The point with the highest score is selected.

Useful when you have a clear business requirement or constraint.

Method generated by attrs for class Preference.

### Ancestors

* `systematica.tuners.base.BaseTrialSelector`
* `abc.ABC`

### Instance variables

* `alpha: float`: Weight coefficient for the y metric. 1-alpha is applied to x metric.

* `x: str`: Column name for the x-axis metric (typically Sharpe ratio).

* `y: str`: Column name for the y-axis metric (typically returns).

### Methods

#### `run`

```python theme={null}
run(
    self,
    df: pandas.core.frame.DataFrame,
) ‑> pandas.core.series.Series
```

Execute the preference-based selection algorithm.

**Parameters**:

| Name | Type           | Default | Description                                     |
| ---- | -------------- | ------- | ----------------------------------------------- |
| `df` | `pd.DataFrame` | `--`    | DataFrame containing parameters to select from. |

**Returns**:

| Type        | Description                                                    |
| ----------- | -------------------------------------------------------------- |
| `pd.Series` | The selected parameter combination with highest utility score. |

## `EpsilonConstraint`

```python theme={null}
EpsilonConstraint(
    x: str,
    y: str,
    min_x: float = 1.5,
    name=None,
)
```

Selects solutions satisfying a hard constraint on one objective.

This approach finds the solution with the highest y value among those
that satisfy x ≥ min\_x. For example, among solutions with Sharpe ratio ≥ 1.5,
pick the one with the highest return.

Method generated by attrs for class EpsilonConstraint.

### Ancestors

* `systematica.tuners.base.BaseTrialSelector`
* `abc.ABC`

### Instance variables

* `min_x: float`: Minimum acceptable value for the x metric.

* `x: str`: Column name for the constraint metric (typically Sharpe ratio).

* `y: str`: Column name for the optimization metric (typically returns).

### Methods

#### `run`

```python theme={null}
run(
    self,
    df: pandas.core.frame.DataFrame,
) ‑> pandas.core.series.Series
```

Execute the epsilon-constraint selection algorithm.

**Parameters**:

| Name | Type           | Default | Description                                     |
| ---- | -------------- | ------- | ----------------------------------------------- |
| `df` | `pd.DataFrame` | `--`    | DataFrame containing parameters to select from. |

**Returns**:

| Type        | Description                                                                         |
| ----------- | ----------------------------------------------------------------------------------- |
| `pd.Series` | The selected parameter combination or None if no parameters satisfy the constraint. |

## `ClosestIdealPoint`

```python theme={null}
ClosestIdealPoint(
    x: str,
    y: str,
    points: Tuple[float, float] = (1.0, 1.0),
    name=None,
)
```

Selects the solution closest to an ideal point.

This strategy normalizes objectives and minimizes Euclidean distance
to the specified ideal point, representing the best theoretical values for
all objectives.

Method generated by attrs for class ClosestIdealPoint.

### Ancestors

* `systematica.tuners.base.BaseTrialSelector`
* `abc.ABC`

### Instance variables

* `points: Tuple[float, float]`: Ideal point coordinates in normalized space, e.g., (1.0, 1.0) for perfect Sharpe and returns.

* `x: str`: Column name for the x-axis metric (typically Sharpe ratio).

* `y: str`: Column name for the y-axis metric (typically returns).

### Methods

#### `run`

```python theme={null}
run(
    self,
    df: pandas.core.frame.DataFrame,
) ‑> pandas.core.series.Series
```

Execute the closest-to-ideal point selection algorithm.

**Parameters**:

| Name | Type           | Default | Description                                     |
| ---- | -------------- | ------- | ----------------------------------------------- |
| `df` | `pd.DataFrame` | `--`    | DataFrame containing parameters to select from. |

**Returns**:

| Type        | Description                                           |
| ----------- | ----------------------------------------------------- |
| `pd.Series` | The parameter combination closest to the ideal point. |

## `DiversitySampling`

```python theme={null}
DiversitySampling(
    metrics: List[str],
    n_clusters: int = 3,
    random_state: int = None,
    name=None,
)
```

Clusters Pareto-optimal solutions and selects representatives.

This approach clusters the Pareto-optimal solutions in the objective space
using k-means and selects representative points from each cluster.
Helps reduce redundancy and provide a diverse set of trade-offs.

Method generated by attrs for class DiversitySampling.

### Ancestors

* `systematica.tuners.base.BaseTrialSelector`
* `abc.ABC`

### Instance variables

* `metrics: List[str]`: List of column names for the metrics to use in clustering.

* `n_clusters: int`: Number of clusters to form. Default is 3.

* `random_state: int`: Random seed for reproducibility. Default is None, which means no fixed seed.

### Methods

#### `run`

```python theme={null}
run(
    self,
    df: pandas.core.frame.DataFrame,
) ‑> pandas.core.series.Series
```

Execute the k-means clustering selection algorithm.

**Parameters**:

| Name | Type           | Default | Description                                     |
| ---- | -------------- | ------- | ----------------------------------------------- |
| `df` | `pd.DataFrame` | `--`    | DataFrame containing parameters to select from. |

**Returns**:

| Type           | Description                                                                                                              |
| -------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `pd.DataFrame` | DataFrame of representative points from each cluster. Empty DataFrame if there are fewer points than requested clusters. |

## `RiskAwareUtility`

```python theme={null}
RiskAwareUtility(
    x: str,
    y: str,
    alpha: float = 0.5,
    name=None,
)
```

Selects based on a risk-aware utility function.

Computes Utility:

$$
\alpha O_1 + (1-\alpha) O_2
$$

Choose alpha based on risk tolerance. If $\alpha = 0.5$, both metrics are weighted equally.

Method generated by attrs for class RiskAwareUtility.

### Ancestors

* `systematica.tuners.base.BaseTrialSelector`
* `abc.ABC`

### Instance variables

* `alpha: float`: Weight coefficient for the return metric. 1-alpha is applied to the risk metric.

* `x: str`: Column name for the risk metric (typically Sharpe ratio).

* `y: str`: Column name for the return metric (typically returns).

### Methods

#### `run`

```python theme={null}
run(
    self,
    df: pandas.core.frame.DataFrame,
) ‑> pandas.core.series.Series
```

Execute the risk-aware utility selection algorithm.

**Parameters**:

| Name | Type           | Default | Description                                     |
| ---- | -------------- | ------- | ----------------------------------------------- |
| `df` | `pd.DataFrame` | `--`    | DataFrame containing parameters to select from. |

**Returns**:

| Type        | Description                                           |
| ----------- | ----------------------------------------------------- |
| `pd.Series` | The parameter combination with highest utility score. |

## `BestMetricPoint`

```python theme={null}
BestMetricPoint(
    best_metrics: pandas.core.frame.DataFrame,
    name=None,
)
```

Selects the solution with best metric.
This selector filters the DataFrame based on the best metrics provided.

Method generated by attrs for class BestMetricPoint.

### Ancestors

* `systematica.tuners.base.BaseTrialSelector`
* `abc.ABC`

### Instance variables

* `best_metrics: pandas.core.frame.DataFrame`: DataFrame containing the best metrics for selection.

### Methods

#### `run`

```python theme={null}
run(
    self,
    df: pandas.core.frame.DataFrame,
) ‑> pandas.core.series.Series
```

Execute the best metric selection algorithm.

**Parameters**:

| Name | Type           | Default | Description                                     |
| ---- | -------------- | ------- | ----------------------------------------------- |
| `df` | `pd.DataFrame` | `--`    | DataFrame containing parameters to select from. |

**Returns**:

| Type        | Description          |
| ----------- | -------------------- |
| `pd.Series` | Selected parameters. |

## `MaxMetricPoint`

```python theme={null}
MaxMetricPoint(
    x: str,
    name=None,
)
```

Selects the solution with maximum metric.

Method generated by attrs for class MaxMetricPoint.

### Ancestors

* `systematica.tuners.base.BaseTrialSelector`
* `abc.ABC`

### Instance variables

* `x: str`: Column name for the metric to maximize.

### Methods

#### `run`

```python theme={null}
run(
    self,
    df: pandas.core.frame.DataFrame,
) ‑> pandas.core.series.Series
```

Execute the maximum metric.

**Parameters**:

| Name | Type           | Default | Description                                     |
| ---- | -------------- | ------- | ----------------------------------------------- |
| `df` | `pd.DataFrame` | `--`    | DataFrame containing parameters to select from. |

**Returns**:

| Type        | Description          |
| ----------- | -------------------- |
| `pd.Series` | Selected parameters. |

## `MinMetricPoint`

```python theme={null}
MinMetricPoint(
    x: str,
    name=None,
)
```

Selects the solution with minimum metric.

Method generated by attrs for class MinMetricPoint.

### Ancestors

* `systematica.tuners.base.BaseTrialSelector`
* `abc.ABC`

### Instance variables

* `x: str`: Column name for the metric to minimize.

### Methods

#### `run`

```python theme={null}
run(
    self,
    df: pandas.core.frame.DataFrame,
) ‑> pandas.core.series.Series
```

Execute the minimum metric.

**Parameters**:

| Name | Type           | Default | Description                                     |
| ---- | -------------- | ------- | ----------------------------------------------- |
| `df` | `pd.DataFrame` | `--`    | DataFrame containing parameters to select from. |

**Returns**:

| Type        | Description          |
| ----------- | -------------------- |
| `pd.Series` | Selected parameters. |

## `RegretMinimization`

```python theme={null}
RegretMinimization(
    x: str,
    y: str,
    name=None,
)
```

Selects the solution that minimizes maximum possible regret.

This approach minimizes the combined distance from the best possible values
for both objectives, representing the minimum "regret" for not choosing the
best solution for each individual metric.

Method generated by attrs for class RegretMinimization.

### Ancestors

* `systematica.tuners.base.BaseTrialSelector`
* `abc.ABC`

### Instance variables

* `x: str`: Column name for the risk metric (typically Sharpe ratio).

* `y: str`: Column name for the return metric (typically returns).

### Methods

#### `run`

```python theme={null}
run(
    self,
    df: pandas.core.frame.DataFrame,
) ‑> pandas.core.series.Series
```

Execute the regret minimization selection algorithm.

**Parameters**:

| Name | Type           | Default | Description                                     |
| ---- | -------------- | ------- | ----------------------------------------------- |
| `df` | `pd.DataFrame` | `--`    | DataFrame containing parameters to select from. |

**Returns**:

| Type        | Description                                    |
| ----------- | ---------------------------------------------- |
| `pd.Series` | The parameter combination with minimum regret. |

## `HullMidPoint`

```python theme={null}
HullMidPoint(
    metrics: List[str],
    name=None,
)
```

Selects solutions based on the convex hull of the Pareto front. Returns
the point closest to the midpoint of the hull.

This method uses the geometry of the Pareto front to identify key
trade-off points:

* Convex Pareto front: Select solutions on the convex hull, representing
  efficient trade-offs.
* Concave Pareto front: Mid-front solutions may be better as extremes may
  represent diminishing returns.

Use cases:

* Convex: Favor extreme efficient strategies (maximize Sharpe or Return)
* Concave: Favor balanced strategies (mid-front), as returns may plateau

Method generated by attrs for class HullMidPoint.

### Ancestors

* `systematica.tuners.base.BaseTrialSelector`
* `abc.ABC`

### Instance variables

* `metrics: List[str]`: List of metrics to use for the convex hull selection.

### Methods

#### `run`

```python theme={null}
run(
    self,
    df: pandas.core.frame.DataFrame,
) ‑> pandas.core.series.Series
```

Execute the convex hull-based selection algorithm.

**Parameters**:

| Name | Type           | Default | Description                                     |
| ---- | -------------- | ------- | ----------------------------------------------- |
| `df` | `pd.DataFrame` | `--`    | DataFrame containing parameters to select from. |

**Raises**:

| Type         | Description                                                 |
| ------------ | ----------------------------------------------------------- |
| `ValueError` | If points lower than 3 after dropping NaNs to compute hull. |

**Returns**:

| Type                        | Description                                                                                                              |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `pd.DataFrame or pd.Series` | Selected parameter combinations based on the chosen mode. Returns entire DataFrame if fewer than 3 points are available. |

## `HullPoint`

```python theme={null}
HullPoint(
    metrics: List[str],
    name=None,
)
```

Selects solutions based on the convex hull of the Pareto front. Returns all
points on the convex hull

This method uses the geometry of the Pareto front to identify key
trade-off points:

* Convex Pareto front: Select solutions on the convex hull, representing
  efficient trade-offs.
* Concave Pareto front: Mid-front solutions may be better as extremes may
  represent diminishing returns.

Use cases:

* Convex: Favor extreme efficient strategies (maximize Sharpe or Return)
* Concave: Favor balanced strategies (mid-front), as returns may plateau

Method generated by attrs for class HullPoint.

### Ancestors

* `systematica.tuners.base.BaseTrialSelector`
* `abc.ABC`

### Instance variables

* `metrics: List[str]`: List of metrics to use for the convex hull selection.

### Methods

#### `run`

```python theme={null}
run(
    self,
    df: pandas.core.frame.DataFrame,
) ‑> pandas.core.series.Series
```

Execute the convex hull-based selection algorithm.

**Parameters**:

| Name | Type           | Default | Description                                     |
| ---- | -------------- | ------- | ----------------------------------------------- |
| `df` | `pd.DataFrame` | `--`    | DataFrame containing parameters to select from. |

**Raises**:

| Type         | Description                                                 |
| ------------ | ----------------------------------------------------------- |
| `ValueError` | If points lower than 3 after dropping NaNs to compute hull. |

**Returns**:

| Type                        | Description                                                                                                              |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `pd.DataFrame or pd.Series` | Selected parameter combinations based on the chosen mode. Returns entire DataFrame if fewer than 3 points are available. |

## `HullExtremePoint`

```python theme={null}
HullExtremePoint(
    metrics: List[str],
    name=None,
)
```

Selects solutions based on the convex hull of the Pareto front. Returns
only max metrics from the hull.

This method uses the geometry of the Pareto front to identify key
trade-off points:

* Convex Pareto front: Select solutions on the convex hull, representing
  efficient trade-offs.
* Concave Pareto front: Mid-front solutions may be better as extremes may
  represent diminishing returns.

Use cases:

* Convex: Favor extreme efficient strategies (maximize Sharpe or Return)
* Concave: Favor balanced strategies (mid-front), as returns may plateau

Method generated by attrs for class HullExtremePoint.

### Ancestors

* `systematica.tuners.base.BaseTrialSelector`
* `abc.ABC`

### Instance variables

* `metrics: List[str]`: List of metrics to use for the convex hull selection.

### Methods

#### `run`

```python theme={null}
run(
    self,
    df: pandas.core.frame.DataFrame,
) ‑> pandas.core.series.Series
```

Execute the convex hull-based selection algorithm.

**Parameters**:

| Name | Type           | Default | Description                                     |
| ---- | -------------- | ------- | ----------------------------------------------- |
| `df` | `pd.DataFrame` | `--`    | DataFrame containing parameters to select from. |

**Raises**:

| Type         | Description                                                 |
| ------------ | ----------------------------------------------------------- |
| `ValueError` | If points lower than 3 after dropping NaNs to compute hull. |

**Returns**:

| Type                        | Description                                                                                                              |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `pd.DataFrame or pd.Series` | Selected parameter combinations based on the chosen mode. Returns entire DataFrame if fewer than 3 points are available. |

## `AUCMaximization`

```python theme={null}
AUCMaximization(
    x: str,
    y: str,
    name=None,
)
```

Selects the point with maximum contribution to the area under the Pareto curve.

This approach approximates the area under the Pareto front curve (in 2D)
and selects the point that contributes most to maximizing this area.
Promotes broad coverage of the objective space.

Method generated by attrs for class AUCMaximization.

### Ancestors

* `systematica.tuners.base.BaseTrialSelector`
* `abc.ABC`

### Instance variables

* `x: str`: Column name for the x-axis metric (typically Sharpe ratio).

* `y: str`: Column name for the y-axis metric (typically returns).

### Methods

#### `run`

```python theme={null}
run(
    self,
    df: pandas.core.frame.DataFrame,
) ‑> pandas.core.series.Series
```

Execute the AUC maximization selection algorithm.

**Parameters**:

| Name | Type           | Default | Description                                     |
| ---- | -------------- | ------- | ----------------------------------------------- |
| `df` | `pd.DataFrame` | `--`    | DataFrame containing parameters to select from. |

**Returns**:

| Type        | Description                                                     |
| ----------- | --------------------------------------------------------------- |
| `pd.Series` | The parameter combination with maximum contribution to the AUC. |

## `HypervolumeContribution`

```python theme={null}
HypervolumeContribution(
    study: optuna.study.study.Study,
    name=None,
)
```

Selects the solution with largest contribution to the dominated hypervolume.

This is a key concept in multi-objective optimization, where the hypervolume
measures the quality of the Pareto front, and the marginal contribution of
a point is the unique volume it adds to this hypervolume. This approach
captures global performance better than a single scalar score and ensures
that selected points represent significant improvements over dominated
solutions.

Method generated by attrs for class HypervolumeContribution.

### Ancestors

* `systematica.tuners.base.BaseTrialSelector`
* `abc.ABC`

### Instance variables

* `study: optuna.study.study.Study`: Optuna study containing the trials.

### Methods

#### `run`

```python theme={null}
run(
    self,
    df: pandas.core.frame.DataFrame,
) ‑> pandas.core.series.Series
```

Execute the hypervolume contribution selection algorithm.

**Parameters**:

| Name | Type           | Default | Description                                                                                  |
| ---- | -------------- | ------- | -------------------------------------------------------------------------------------------- |
| `df` | `pd.DataFrame` | `--`    | DataFrame containing parameters to select from with a 'number' column matching trial.number. |

**Raises**:

| Type         | Description                                                                         |
| ------------ | ----------------------------------------------------------------------------------- |
| `ValueError` | If no Pareto front trials are found or no matching trial is found in the DataFrame. |

**Returns**:

| Type        | Description                                                      |
| ----------- | ---------------------------------------------------------------- |
| `pd.Series` | The parameter combination with maximum hypervolume contribution. |

## `Random`

```python theme={null}
Random(
    name=None,
)
```

Selects randomly among Pareto-optimal points.

Useful when there's no clear preference or for robustness testing.

Method generated by attrs for class Random.

### Ancestors

* `systematica.tuners.base.BaseTrialSelector`
* `abc.ABC`

### Methods

#### `run`

```python theme={null}
run(
    self,
    df: pandas.core.frame.DataFrame,
) ‑> pandas.core.series.Series
```

Execute the random selection algorithm.

**Parameters**:

| Name | Type           | Default | Description                                     |
| ---- | -------------- | ------- | ----------------------------------------------- |
| `df` | `pd.DataFrame` | `--`    | DataFrame containing parameters to select from. |

**Returns**:

| Type        | Description                                |
| ----------- | ------------------------------------------ |
| `pd.Series` | A randomly selected parameter combination. |

## `EfficientFrontierProjection`

```python theme={null}
EfficientFrontierProjection(
    x: str,
    y: str,
    risk_free_rate: float = 0.0,
    name=None,
)
```

Projects Pareto points onto an efficient frontier and selects optimal point.

This approach treats each Pareto point as a portfolio and projects it onto
the efficient frontier. It then selects the point with the maximum x value
(return/risk). Useful when simulating an allocation frontier using trial
results.

Method generated by attrs for class EfficientFrontierProjection.

### Ancestors

* `systematica.tuners.base.BaseTrialSelector`
* `abc.ABC`

### Instance variables

* `risk_free_rate: float`: Risk-free rate for volatility calculation. Defaults to 0.0.

* `x: str`: Column name for the risk metric (standard deviation or inverse sharpe).

* `y: str`: Column name for the return metric.

### Methods

#### `run`

```python theme={null}
run(
    self,
    df: pandas.core.frame.DataFrame,
) ‑> pandas.core.series.Series
```

Execute the efficient frontier projection selection algorithm.

**Parameters**:

| Name | Type           | Default | Description                                     |
| ---- | -------------- | ------- | ----------------------------------------------- |
| `df` | `pd.DataFrame` | `--`    | DataFrame containing parameters to select from. |

**Returns**:

| Type        | Description                                          |
| ----------- | ---------------------------------------------------- |
| `pd.Series` | The parameter combination with maximum Sharpe ratio. |