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 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 :mod:`leaspy.algo` for the full list of supported parameters. :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:`~leaspy.algo.settings.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** : dict 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** 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: :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** : dict[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: :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