leaspy.algo.settings ==================== .. py:module:: leaspy.algo.settings .. autoapi-nested-parse:: This module defines the `OutputsSettings` and `AlgorithmSettings` classes. .. !! processed by numpydoc !! Attributes ---------- .. autoapisummary:: leaspy.algo.settings.algo_default_data_dir Classes ------- .. autoapisummary:: leaspy.algo.settings.OutputsSettings leaspy.algo.settings.AlgorithmSettings Module Contents --------------- .. py:data:: algo_default_data_dir .. 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: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 !!