leaspy.algo.settings#

This module defines the OutputsSettings and AlgorithmSettings classes.

Attributes#

algo_default_data_dir

Classes#

OutputsSettings

Used to create the logs folder to monitor the convergence of the fit algorithm.

AlgorithmSettings

Used to set the algorithms' settings.

Module Contents#

algo_default_data_dir#
class OutputsSettings(settings)#

Used to create the logs folder to monitor the convergence of the fit algorithm.

Parameters:
settingsdict[str, Any]

Configuration mapping. Supported keys:

  • path (str | None): destination folder for logs. If None, defaults to "./_outputs/" when saving.

  • print_periodicity (int | None): print information every N iterations.

  • save_periodicity (int | None): save convergence data every N iterations (default 50).

  • plot_periodicity (int | None): plot convergence data every N iterations; must not be more frequent than saves.

  • plot_sourcewise (bool): plot source-based parameters per source instead of per feature (default False).

  • overwrite_logs_folder (bool): remove any existing logs folder before writing (default False).

  • nb_of_patients_to_plot (int): number of patients plotted when enabled (default 5).

Raises:
LeaspyAlgoInputError
DEFAULT_LOGS_DIR = '_outputs'#
print_periodicity = None#
plot_periodicity = None#
save_periodicity = None#
plot_patient_periodicity = None#
plot_sourcewise = False#
nb_of_patients_to_plot = 5#
root_path = None#
parameter_convergence_path = None#
plot_path = None#
patients_plot_path = None#
class AlgorithmSettings(name, **kwargs)#

Used to set the algorithms’ settings.

All parameters except the algorithm name have default values, which can be overwritten by the user.

Parameters:
namestr

Algorithm name. Accepted values: - fit: "mcmc_saem" or "lme_fit" (LME only) - personalize: "scipy_minimize", "mean_real", "mode_real", "constant_prediction" (constant model only), "lme_personalize" (LME only) - simulate: "simulation"

**kwargs

Optional algorithm-specific settings. Common keys: - seed (int | None): seed for stochastic algorithms. - algorithm_initialization_method (str | None): strategy name accepted by the target algorithm. - n_iter (int | None): number of iterations (no auto stopping for MCMC SAEM). - n_burn_in_iter (int | None): burn-in iterations for MCMC SAEM. - use_jacobian (bool): use Jacobian in scipy_minimize to switch to L-BFGS (default True). - n_jobs (int): joblib parallelism for scipy_minimize (default 1). - progress_bar (bool): show a progress bar (default True). - device (int | torch.device | str): computation device for algorithms that support it.

Refer to each algorithm documentation in leaspy.algo for the full list of supported parameters.

Attributes:
namestr

The algorithm’s name.

algorithm_initialization_methodstr, optional

Personalize the algorithm initialization method, according to those possible for the given algorithm (refer to its documentation in leaspy.algo).

seedint, optional, default None

Used for stochastic algorithms.

parametersdict

Contains the other parameters: n_iter, n_burn_in_iter, use_jacobian, n_jobs & progress_bar.

logsOutputsSettings, optional

Used to create a logs file containing convergence information during fitting the model.

devicestr (or torch.device), optional, default ‘cpu’

Specifies the computation device. Only ‘cpu’ and ‘cuda’ are supported. Note that specifying an indexed CUDA device (such as ‘cuda:1’) is not supported. In order to specify the precise cuda device index, one should use the CUDA_VISIBLE_DEVICES environment variable.

Raises:
LeaspyAlgoInputError
Parameters:

name (str)

Notes

Developers can use _dynamic_default_parameters to define settings that depend on other parameters when not explicitly specified by the user.

name: AlgorithmName#
parameters: leaspy.utils.typing.KwargsType | None = None#
seed: int | None = None#
algorithm_initialization_method: str | None = None#
logs: OutputsSettings | None = None#
check_consistency()#

Check internal consistency of algorithm settings and warn or raise a LeaspyAlgoInputError if not.

Return type:

None

classmethod load(path_to_algorithm_settings)#

Instantiate a AlgorithmSettings object a from json file.

Parameters:
path_to_algorithm_settingsstr

Path of the json file.

Returns:
AlgorithmSettings

An instanced of AlgorithmSettings with specified parameters.

Raises:
LeaspyAlgoInputError

if anything is invalid in algo settings

Parameters:

path_to_algorithm_settings (Union[str, Path])

Examples

>>> from leaspy.algo import AlgorithmSettings
>>> leaspy_univariate = AlgorithmSettings.load('outputs/leaspy-univariate_model-settings.json')
save(path, **kwargs)#

Save an AlgorithmSettings object in a json file.

TODO? save leaspy version as well for retro/future-compatibility issues?

Parameters:
pathstr

Path to store the AlgorithmSettings.

kwargsdict

Keyword arguments for json.dump method. Default: dict(indent=2)

Parameters:

path (Union[str, Path])

Examples

>>> from leaspy.algo import AlgorithmSettings
>>> settings = AlgorithmSettings("scipy_minimize", seed=42)
>>> settings.save("outputs/scipy_minimize-settings.json")
set_logs(**kwargs)#

Use this method to monitor the convergence of a model fit.

This method creates CSV files and plots to track the evolution of population parameters (i.e., fixed effects) during the fitting.

Parameters:
**kwargs

Supported keys: - path (str | None): folder where graphs and CSV files will be saved. If None, DEFAULT_LOGS_DIR is used. - print_periodicity (int | None): print every N iterations (default 100 when provided). - save_periodicity (int | None): save CSV values every N iterations (default 50 when provided). - plot_periodicity (int | None): generate plots every N iterations; must be a multiple of save_periodicity (default 1000). - plot_patient_periodicity (int | None): frequency for saving patient reconstructions. - plot_sourcewise (bool): plot source-based parameters per source (default False). - overwrite_logs_folder (bool): overwrite existing content in path (default False). - nb_of_patients_to_plot (int): number of patients to plot when plotting is enabled (default 5).

Raises:
LeaspyAlgoInputError

If the folder given in path already exists and if overwrite_logs_folder is set to False.

Notes

By default, if the folder given in path already exists, the method will raise an error. To overwrite the content of the folder, set overwrite_logs_folder it to True.