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** : :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: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 !!