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]

• pathstr or None

  Path to store logs. If None, default path “./_outputs/” will be used.

• print_periodicityint >= 1 or None

  Print information every N iterations

• save_periodicityint >= 1, optional

  Save convergence data every N iterations Default=50.

• plot_periodicityint >= 1 or None

  Plot convergence data every N iterations. If None, no plots will be saved. Note that plotting requires saving to be realized and can not be more than saves.

• plot_sourcewisebool

  Flag to plot source based multidimensional parameters such as mixing_matrix for each source. Otherwise, they will be plotted according to the other dimension such as feature. Default=False

• overwrite_logs_folderbool

  Flag to remove all previous logs if existing (default False)

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

The algorithm’s name. Must be one of:

• For fit algorithms:

  • 'mcmc_saem'

  • 'lme_fit' (for LME model only)

• For personalize algorithms:

  • 'scipy_minimize'

  • 'mean_real'

  • 'mode_real'

  • 'constant_prediction' (for constant model only)

  • 'lme_personalize' (for LME model only)

• For simulate algorithms:

  • 'simulation'

**kwargsany

Depending on the algorithm, various parameters are possible:

• seedint, optional, default None

  Used for stochastic algorithms.

• algorithm_initialization_methodstr, optional

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

• n_iterint, optional

  Number of iteration. Note that there is no stopping criteria for MCMC SAEM algorithms.

• n_burn_in_iterint, optional

  Number of iteration during burning phase, used for the MCMC SAEM algorithms.

• use_jacobianbool, optional, default True

  Used in scipy_minimize algorithm to perform a L-BFGS instead of a Powell algorithm.

• n_jobsbool, optional, default 1

  Used in scipy_minimize algorithm to accelerate calculation with parallel derivation using joblib.

• progress_barbool, optional, default True

  Used to display a progress bar during computation.

• deviceint or torch.device, optional

  Specifies on which device the algorithm will run. Only ‘cpu’ and ‘cuda’ are supported for this argument. Only 'mcmc_saem', 'mean_real' and 'mode_real' algorithms support this setting.

For the complete list of the available parameters for a given algorithm, please directly refer to its documentation.

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

**kwargs

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

pathstr, optional

The path of the folder where graphs and csv files will be saved. If None, DEFAULT_LOGS_DIR will be used.

• print_periodicityint, optional, default 100

  Prints every N iterations.

• save_periodicityint, optional, default 50

  Saves the values in csv files every N iterations.

• plot_periodicityint, optional, default 1000

  Generates plots from saved values every N iterations. Notes:

  • Must be a multiple of save_periodicity.

  • Setting this value too low may significantly slow down the fitting process.

• plot_patient_periodicityint

  Set the frequency of the saves of the patients’ reconstructions

• plot_sourcewisebool, optional, default False

  Set this to True to plot the source-based parameters sourcewise.

• overwrite_logs_folderbool, optional, default False

  Set it to True to overwrite the content of the folder in path.

• nb_of_patients_to_plotint, optional default 5

  number of patients to plot

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.