leaspy.algo =========== .. py:module:: leaspy.algo Submodules ---------- .. toctree:: :maxdepth: 1 /reference/api/leaspy/algo/algo_with_annealing/index /reference/api/leaspy/algo/algo_with_device/index /reference/api/leaspy/algo/algo_with_samplers/index /reference/api/leaspy/algo/base/index /reference/api/leaspy/algo/fit/index /reference/api/leaspy/algo/personalize/index /reference/api/leaspy/algo/settings/index /reference/api/leaspy/algo/simulate/index Attributes ---------- .. autoapisummary:: leaspy.algo.algo_default_data_dir Classes ------- .. autoapisummary:: leaspy.algo.AlgorithmName leaspy.algo.AlgorithmType leaspy.algo.BaseAlgorithm leaspy.algo.AlgorithmSettings leaspy.algo.OutputsSettings Functions --------- .. autoapisummary:: leaspy.algo.algorithm_factory leaspy.algo.get_algorithm_class leaspy.algo.get_algorithm_type Package Contents ---------------- .. py:class:: AlgorithmName Bases: :py:obj:`str`, :py:obj:`enum.Enum` The available algorithms in Leaspy. .. !! processed by numpydoc !! .. py:attribute:: FIT_MCMC_SAEM :value: 'mcmc_saem' .. py:attribute:: FIT_LME :value: 'lme_fit' .. py:attribute:: PERSONALIZE_SCIPY_MINIMIZE :value: 'scipy_minimize' .. py:attribute:: PERSONALIZE_MEAN_POSTERIOR :value: 'mean_posterior' .. py:attribute:: PERSONALIZE_MODE_POSTERIOR :value: 'mode_posterior' .. py:attribute:: PERSONALIZE_CONSTANT :value: 'constant_prediction' .. py:attribute:: PERSONALIZE_LME :value: 'lme_personalize' .. py:attribute:: SIMULATE :value: 'simulate' .. py:class:: AlgorithmType Bases: :py:obj:`str`, :py:obj:`enum.Enum` The type of the algorithms. .. !! processed by numpydoc !! .. py:attribute:: FIT :value: 'fit' .. py:attribute:: PERSONALIZE :value: 'personalize' .. py:attribute:: SIMULATE :value: 'simulate' .. py:class:: BaseAlgorithm(settings) Bases: :py:obj:`abc.ABC`, :py:obj:`Generic`\ [\ :py:obj:`ModelType`\ , :py:obj:`ReturnType`\ ] Base class containing common methods for all algorithm classes. :Parameters: **settings** : :class:`~leaspy.algo.AlgorithmSettings` The specifications of the algorithm as a :class:`~leaspy.algo.AlgorithmSettings` instance. :Attributes: **name** : :class:`~leaspy.algo.base.AlgorithmName` Name of the algorithm. **family** : :class:`~leaspy.algo.base.AlgorithmType` Family of the algorithm. **deterministic** : :obj:`bool` True, if and only if algorithm does not involve randomness. Setting a seed will have no effect on such algorithms. **algo_parameters** : :obj:`dict` Contains the algorithm's parameters. Those are controlled by the :attr:`leaspy.algo.AlgorithmSettings.parameters` class attribute. **seed** : :obj:`int`, optional Seed used by :mod:`numpy` and :mod:`torch`. .. !! processed by numpydoc !! .. py:attribute:: name :type: AlgorithmName :value: None .. py:attribute:: family :type: AlgorithmType :value: None .. py:attribute:: deterministic :type: bool :value: False .. py:attribute:: seed .. py:attribute:: algo_parameters .. py:attribute:: output_manager :value: None .. py:method:: set_output_manager(output_settings) :abstractmethod: .. py:method:: run(model, dataset = None, **kwargs) Main method, run the algorithm. :Parameters: **model** : :class:`~leaspy.models.BaseModel` The used model. **dataset** : :class:`~leaspy.io.data.Dataset` Contains all the subjects' observations with corresponding timepoints, in torch format to speed up computations. :Returns: ReturnType: Depends on algorithm class. .. seealso:: :class:`.AbstractFitAlgo` .. :class:`.AbstractPersonalizeAlgo` .. .. !! processed by numpydoc !! .. py:method:: load_parameters(parameters) Update the algorithm's parameters by the ones in the given dictionary. The keys in the input which does not belong to the algorithm's parameters are ignored. :Parameters: **parameters** : :obj:`dict` Contains the pairs (key, value) of the requested parameters .. rubric:: Examples >>> from leaspy.algo import AlgorithmSettings, algorithm_factory, OutputsSettings >>> my_algo = algorithm_factory(AlgorithmSettings("mcmc_saem")) >>> my_algo.algo_parameters {'progress_bar': True, 'n_iter': 10000, 'n_burn_in_iter': 9000, 'n_burn_in_iter_frac': 0.9, 'burn_in_step_power': 0.8, 'random_order_variables': True, 'sampler_ind': 'Gibbs', 'sampler_ind_params': {'acceptation_history_length': 25, 'mean_acceptation_rate_target_bounds': [0.2, 0.4], 'adaptive_std_factor': 0.1}, 'sampler_pop': 'Gibbs', 'sampler_pop_params': {'random_order_dimension': True, 'acceptation_history_length': 25, 'mean_acceptation_rate_target_bounds': [0.2, 0.4], 'adaptive_std_factor': 0.1}, 'annealing': {'do_annealing': False, 'initial_temperature': 10, 'n_plateau': 10, 'n_iter': None, 'n_iter_frac': 0.5}} >>> parameters = {'n_iter': 5000, 'n_burn_in_iter': 4000} >>> my_algo.load_parameters(parameters) >>> my_algo.algo_parameters {'progress_bar': True, 'n_iter': 5000, 'n_burn_in_iter': 4000, 'n_burn_in_iter_frac': 0.9, 'burn_in_step_power': 0.8, 'random_order_variables': True, 'sampler_ind': 'Gibbs', 'sampler_ind_params': {'acceptation_history_length': 25, 'mean_acceptation_rate_target_bounds': [0.2, 0.4], 'adaptive_std_factor': 0.1}, 'sampler_pop': 'Gibbs', 'sampler_pop_params': {'random_order_dimension': True, 'acceptation_history_length': 25, 'mean_acceptation_rate_target_bounds': [0.2, 0.4], 'adaptive_std_factor': 0.1}, 'annealing': {'do_annealing': False, 'initial_temperature': 10, 'n_plateau': 10, 'n_iter': None, 'n_iter_frac': 0.5}} .. !! processed by numpydoc !! .. py:function:: algorithm_factory(settings) Return the requested algorithm based on the provided settings. :Parameters: **settings** : :class:`leaspy.algo.AlgorithmSettingss` The algorithm settings. :Returns: **algorithm** : child class of :class:`~leaspy.algo.BaseAlgorithm` The requested algorithm. If it exists, it will be compatible with algorithm family. .. !! processed by numpydoc !! .. py:function:: get_algorithm_class(name) Return the algorithm class. :Parameters: **name** : :obj:`str` or :class:`~leaspy.algo.base.AlgorithmName` The name of the algorithm. :Returns: algorithm class: :class:`~leaspy.algo.BaseAlgorithm` .. .. !! processed by numpydoc !! .. py:function:: get_algorithm_type(name) Return the algorithm type. :Parameters: **name** : :obj:`str` or :class:`~leaspy.algo.base.AlgorithmName` The name of the algorithm. :Returns: algorithm type: :class:`leaspy.algo.AlgorithmType` .. .. !! processed by numpydoc !! .. py: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: **name** : str 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'`` **\*\*kwargs** : any Depending on the algorithm, various parameters are possible: * seed : :obj:`int`, optional, default None Used for stochastic algorithms. * algorithm_initialization_method : :obj:`str`, optional Personalize the algorithm initialization method, according to those possible for the given algorithm (refer to its documentation in :mod:`leaspy.algo`). * n_iter : :obj:`int`, optional Number of iteration. Note that there is no stopping criteria for MCMC SAEM algorithms. * n_burn_in_iter : :obj:`int`, optional Number of iteration during burning phase, used for the MCMC SAEM algorithms. * use_jacobian : :obj:`bool`, optional, default True Used in ``scipy_minimize`` algorithm to perform a `L-BFGS` instead of a `Powell` algorithm. * n_jobs : :obj:`bool`, optional, default 1 Used in ``scipy_minimize`` algorithm to accelerate calculation with parallel derivation using joblib. * progress_bar : :obj:`bool`, optional, default True Used to display a progress bar during computation. * device : :obj:`int` 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: **name** : :obj:`str` The algorithm's name. **algorithm_initialization_method** : :obj:`str`, optional Personalize the algorithm initialization method, according to those possible for the given algorithm (refer to its documentation in :mod:`leaspy.algo`). **seed** : :obj:`int`, optional, default None Used for stochastic algorithms. **parameters** : :obj:`dict` Contains the other parameters: `n_iter`, `n_burn_in_iter`, `use_jacobian`, `n_jobs` & `progress_bar`. **logs** : :class:`.OutputsSettings`, optional Used to create a ``logs`` file containing convergence information during fitting the model. **device** : :obj:`str` (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: :exc:`.LeaspyAlgoInputError` .. .. rubric:: Notes Developers can use `_dynamic_default_parameters` to define settings that depend on other parameters when not explicitly specified by the user. .. !! processed by numpydoc !! .. py:attribute:: name :type: leaspy.algo.AlgorithmName .. py:attribute:: parameters :type: Optional[leaspy.utils.typing.KwargsType] :value: None .. py:attribute:: seed :type: Optional[int] :value: None .. py:attribute:: algorithm_initialization_method :type: Optional[str] :value: None .. py:attribute:: logs :type: Optional[OutputsSettings] :value: None .. py:method:: check_consistency() Check internal consistency of algorithm settings and warn or raise a `LeaspyAlgoInputError` if not. .. !! processed by numpydoc !! .. py:method:: load(path_to_algorithm_settings) :classmethod: Instantiate a AlgorithmSettings object a from json file. :Parameters: **path_to_algorithm_settings** : :obj:`str` Path of the json file. :Returns: :class:`.AlgorithmSettings` An instanced of AlgorithmSettings with specified parameters. :Raises: :exc:`.LeaspyAlgoInputError` if anything is invalid in algo settings .. rubric:: Examples >>> from leaspy.algo import AlgorithmSettings >>> leaspy_univariate = AlgorithmSettings.load('outputs/leaspy-univariate_model-settings.json') .. !! processed by numpydoc !! .. py:method:: save(path, **kwargs) Save an AlgorithmSettings object in a json file. TODO? save leaspy version as well for retro/future-compatibility issues? :Parameters: **path** : :obj:`str` Path to store the AlgorithmSettings. **\*\*kwargs** Keyword arguments for json.dump method. Default: dict(indent=2) .. rubric:: Examples >>> from leaspy.algo import AlgorithmSettings >>> settings = AlgorithmSettings("scipy_minimize", seed=42) >>> settings.save("outputs/scipy_minimize-settings.json") .. !! processed by numpydoc !! .. py:method:: 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** path : :obj:`str`, optional The path of the folder where graphs and csv files will be saved. If None, DEFAULT_LOGS_DIR will be used. * print_periodicity : :obj:`int`, optional, default 100 Prints every N iterations. * save_periodicity : :obj:`int`, optional, default 50 Saves the values in csv files every N iterations. * plot_periodicity : :obj:`int`, 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_periodicity : :obj:`int` Set the frequency of the saves of the patients' reconstructions * plot_sourcewise : :obj:`bool`, optional, default False Set this to True to plot the source-based parameters sourcewise. * overwrite_logs_folder : :obj:`bool`, optional, default False Set it to ``True`` to overwrite the content of the folder in ``path``. * nb_of_patients_to_plot : :obj:`int`, optional default 5 number of patients to plot :Raises: :exc:`.LeaspyAlgoInputError` If the folder given in ``path`` already exists and if ``overwrite_logs_folder`` is set to ``False``. .. rubric:: 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``. .. !! processed by numpydoc !! .. py:class:: OutputsSettings(settings) Used to create the `logs` folder to monitor the convergence of the fit algorithm. :Parameters: **settings** : :obj:`dict` [:obj:`str`, Any] * path : :obj:`str` or None Path to store logs. If None, default path "./_outputs/" will be used. * print_periodicity : :obj:`int` >= 1 or None Print information every N iterations * save_periodicity : :obj:`int` >= 1, optional Save convergence data every N iterations Default=50. * plot_periodicity : :obj:`int` >= 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_sourcewise : :obj:`bool` 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_folder : :obj:`bool` Flag to remove all previous logs if existing (default False) :Raises: :exc:`.LeaspyAlgoInputError` .. .. !! processed by numpydoc !! .. py:attribute:: DEFAULT_LOGS_DIR :value: '_outputs' .. py:attribute:: print_periodicity :value: None .. py:attribute:: plot_periodicity :value: None .. py:attribute:: save_periodicity :value: None .. py:attribute:: plot_patient_periodicity :value: None .. py:attribute:: plot_sourcewise :value: False .. py:attribute:: nb_of_patients_to_plot :value: 5 .. py:attribute:: root_path :value: None .. py:attribute:: parameter_convergence_path :value: None .. py:attribute:: plot_path :value: None .. py:attribute:: patients_plot_path :value: None .. py:data:: algo_default_data_dir