Utils

systematica.portfolio.tuners.utils

resolve_optuna

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

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:

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

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

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

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

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

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

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

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

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

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

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.