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

# Utils

> systematica.portfolio.tuners.utils

## `resolve_optuna`

```python theme={null}
resolve_optuna(
    trial,
    item: systematica.portfolio.tuners.utils.BaseOptunaTrial | typing.Any,
) ‑> Any
```

Resolve an Optuna trial by suggesting parameters if applicable.

**Parameters**:

| Name    | Type                 | Default | Description                                                                               |
| ------- | -------------------- | ------- | ----------------------------------------------------------------------------------------- |
| `trial` | `optuna.trial.Trial` | `--`    | The Optuna trial object.                                                                  |
| `item`  | `BaseOptunaTrial`    | `--`    | or Any The parameter or object to resolve. If it has a `suggest` method, it will be used. |

**Returns**:

| Type  | Description                                                                           |
| ----- | ------------------------------------------------------------------------------------- |
| `Any` | The suggested value if `item` has a `suggest` method, otherwise returns `item` as-is. |

## `resolve_metric_output`

```python theme={null}
resolve_metric_output(
    metric: Any,
) ‑> int | float | Tuple[int | float, ...]
```

Resolves the output metric from a portfolio pipeline into a float or tuple
of floats.

This function checks for NaN values in the metric and ensures the output is
in a format suitable for Optuna optimization. It supports metrics that are
floats, lists, pandas DataFrames, or pandas Series.

**Parameters**:

| Name     | Type  | Default | Description                                                                                                 |
| -------- | ----- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `metric` | `Any` | `--`    | The metric returned by the portfolio pipeline. It can be a float, list, pandas DataFrame, or pandas Series. |

**Returns**:

| Type                                       | Description                                                                                                                                                   |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `int \| float \| Tuple[int \| float, ...]` | The resolved metric as a single float or a tuple of floats. If the input is a DataFrame, Series, or list, it is flattened and converted to a tuple of floats. |

**Raises**:

| Type                 | Description                                                                   |
| -------------------- | ----------------------------------------------------------------------------- |
| `optuna.TrialPruned` | If the metric contains NaN values, is empty, or is None, the trial is pruned. |

**Examples**:

```python theme={null}
>>> resolve_metric_output(1.5)
# 1.5
>>> resolve_metric_output([1.2, 3.4, 5.6])
# (1.2, 3.4, 5.6)
>>> resolve_metric_output(pd.Series([1.0, 2.0, np.nan]))
# optuna.TrialPruned  # Raises because of NaN values
```

## `BaseOptunaTrial`

```python theme={null}
BaseOptunaTrial()
```

Base Optuna trial class used to suggest value.

### Ancestors

* `abc.ABC`

### Descendants

* `systematica.portfolio.tuners.utils.Categorical`
* `systematica.portfolio.tuners.utils.Float`
* `systematica.portfolio.tuners.utils.Int`
* `systematica.portfolio.tuners.utils.Param`

### Methods

#### `suggest`

```python theme={null}
suggest(
    self,
    trial: optuna.trial._trial.Trial,
) ‑> Any
```

Suggest a value for the parameter.

**Parameters**:

| Name    | Type           | Default | Description              |
| ------- | -------------- | ------- | ------------------------ |
| `trial` | `optuna.Trial` | `--`    | The Optuna trial object. |

**Returns**:

| Type     | Description                          |
| -------- | ------------------------------------ |
| `tp.Any` | A suggested value for the parameter. |

## `Float`

```python theme={null}
Float(
    name: str,
    low: float,
    high: float,
    step: float | None = None,
    log: bool = False,
)
```

Class that represents a float Optuna suggestion.

Method generated by attrs for class Float.

### Ancestors

* `systematica.portfolio.tuners.utils.BaseOptunaTrial`
* `abc.ABC`

### Instance variables

* `high: float`: Upper endpoint of the range of suggested values. `high` is included in  the range. `high` must be greater than or equal to `low`.

* `log: bool`: A flag to sample the value from the log domain or not. If `log` is `True`, the value is sampled from the range in the log  domain. Otherwise, the value is sampled from the range in the linear  domain.

* `low: float`: Lower endpoint of the range of suggested values. `low` is included in  the range. `low` must be less than or equal to `high`. If `log`  is `True`, `low` must be larger than 0.

* `name: str`: A parameter name.

* `step: float | None`: A step of discretization.

### Methods

#### `suggest`

```python theme={null}
suggest(
    self,
    trial: optuna.trial._trial.Trial,
) ‑> float
```

Suggest a value for the floating point parameter.

**Parameters**:

| Name    | Type           | Default | Description              |
| ------- | -------------- | ------- | ------------------------ |
| `trial` | `optuna.Trial` | `--`    | The Optuna trial object. |

**Returns**:

| Type    | Description              |
| ------- | ------------------------ |
| `float` | A suggested float value. |

## `Int`

```python theme={null}
Int(
    name: str,
    low: int,
    high: int,
    step: int = 1,
    log: bool = False,
)
```

Class that represents an integer Optuna suggestion.

Method generated by attrs for class Int.

### Ancestors

* `systematica.portfolio.tuners.utils.BaseOptunaTrial`
* `abc.ABC`

### Instance variables

* `high: int`: Upper endpoint of the range of suggested values. `high` is included in  the range. `high` must be greater than or equal to `low`.

* `log: bool`: A flag to sample the value from the log domain or not. If `log` is true, the value is sampled from the range in the log domain. Otherwise, the value is sampled from the range in the linear domain.

* `low: int`: Lower endpoint of the range of suggested values. `low` is included in  the range. `low` must be less than or equal to `high`. If `log` is  `True`, `low` must be larger than 0.

* `name: str`: A parameter name.

* `step: int`: A step of discretization.

### Methods

#### `suggest`

```python theme={null}
suggest(
    self,
    trial: optuna.trial._trial.Trial,
) ‑> int
```

Suggest a value for the integer parameter.

The value is sampled from the integers in :math:`[\mathsf{low}, \mathsf{high}]`.

**Parameters**:

| Name    | Type           | Default | Description              |
| ------- | -------------- | ------- | ------------------------ |
| `trial` | `optuna.Trial` | `--`    | The Optuna trial object. |

**Returns**:

| Type  | Description            |
| ----- | ---------------------- |
| `int` | A suggested int value. |

## `Categorical`

```python theme={null}
Categorical(
    name: str,
    choices: Sequence[bool | int | float | str | None],
)
```

Class that represents a categorical Optuna suggestion.

Method generated by attrs for class Categorical.

### Ancestors

* `systematica.portfolio.tuners.utils.BaseOptunaTrial`
* `abc.ABC`

### Instance variables

* `choices: Sequence[bool | int | float | str | None]`: Parameter value candidates.

* `name: str`: A parameter name.

### Methods

#### `suggest`

```python theme={null}
suggest(
    self,
    trial: optuna.trial._trial.Trial,
) ‑> bool | int | float | str | None
```

Suggest a value for the categorical parameter.

The value is sampled from `choices`.

**Parameters**:

| Name    | Type           | Default | Description              |
| ------- | -------------- | ------- | ------------------------ |
| `trial` | `optuna.Trial` | `--`    | The Optuna trial object. |

**Returns**:

| Type                                         | Description                    |
| -------------------------------------------- | ------------------------------ |
| `optuna.distributions.CategoricalChoiceType` | A suggested categorical value. |

## `Param`

```python theme={null}
Param(
    name: str,
    choices: Sequence[bool | int | float | str | None] = None,
    low: int = None,
    high: int = None,
    step: int = 1,
    log: bool = False,
)
```

Class that represents a any Optuna suggestion.

Method generated by attrs for class Param.

### Ancestors

* `systematica.portfolio.tuners.utils.BaseOptunaTrial`
* `abc.ABC`

### Instance variables

* `choices: Sequence[bool | int | float | str | None]`: Parameter value candidates.

* `high: int`: Upper endpoint of the range of suggested values. `high` is included in  the range. `high` must be greater than or equal to `low`.

* `log: bool`: A flag to sample the value from the log domain or not. If `log` is true, the value is sampled from the range in the log domain. Otherwise, the value is sampled from the range in the linear domain.

* `low: int`: Lower endpoint of the range of suggested values. `low` is included in  the range. `low` must be less than or equal to `high`. If `log` is  `True`, `low` must be larger than 0.

* `name: str`: A parameter name.

* `step: int`: A step of discretization.

### Methods

#### `suggest`

```python theme={null}
suggest(
    self,
    trial: optuna.trial._trial.Trial,
) ‑> bool | int | float | str | None
```

Suggest a value for any parameter.

**Parameters**:

| Name    | Type           | Default | Description              |
| ------- | -------------- | ------- | ------------------------ |
| `trial` | `optuna.Trial` | `--`    | The Optuna trial object. |

**Returns**:

| Type                                                         | Description        |
| ------------------------------------------------------------ | ------------------ |
| `int \| float \| optuna.distributions.CategoricalChoiceType` | A suggested value. |