leaspy.algo.fit =============== .. py:module:: leaspy.algo.fit Submodules ---------- .. toctree:: :maxdepth: 1 /reference/api/leaspy/algo/fit/base/index /reference/api/leaspy/algo/fit/fit_output_manager/index /reference/api/leaspy/algo/fit/lme_fit/index /reference/api/leaspy/algo/fit/mcmc_saem/index Classes ------- .. autoapisummary:: leaspy.algo.fit.FitAlgorithm leaspy.algo.fit.FitOutputManager leaspy.algo.fit.LMEFitAlgorithm leaspy.algo.fit.TensorMcmcSaemAlgorithm Package Contents ---------------- .. py:class:: FitAlgorithm(settings) Bases: :py:obj:`leaspy.algo.base.IterativeAlgorithm`\ [\ :py:obj:`leaspy.algo.base.ModelType`\ , :py:obj:`leaspy.algo.base.ReturnType`\ ] Abstract class containing common method for all `fit` algorithm classes. The algorithm is proven to converge if the sequence `burn_in_step` is positive, with an infinite sum :math:`\sum_k \epsilon_k = +\infty` and a finite sum of the squares :math:`\sum_k \epsilon_k^2 < \infty` (see following paper). `Construction of Bayesian Deformable Models via a Stochastic Approximation Algorithm: A Convergence Study `_ :Parameters: **settings** : :class:`~leaspy.algo.AlgorithmSettings` The specifications of the algorithm as a :class:`~leaspy.algo.AlgorithmSettings` instance. :Attributes: **algorithm_device** : :obj:`str` Valid :class:`torch.device` **current_iteration** : :obj:`int`, default 0 The number of the current iteration. The first iteration will be 1 and the last one `n_iter`. **sufficient_statistics** : :obj:`dict` [:obj:`str`, :class:`torch.Tensor`] or None Sufficient statistics of the previous step. It is None during all the burn-in phase. **output_manager** : :class:`~leaspy.io.logs.fit_output_manager.FitOutputManager` Optional output manager of the algorithm **Inherited attributes** From :class:`~leaspy.algo.AbstractAlgo` .. seealso:: :meth:`leaspy.api.Leaspy.fit` .. .. !! processed by numpydoc !! .. py:attribute:: family .. py:attribute:: logs .. py:attribute:: sufficient_statistics :type: Optional[leaspy.utils.typing.DictParamsTorch] :value: None .. py:method:: set_output_manager(output_settings) Set a :class:`~leaspy.algo.fit.FitOutputManager` object for the run of the algorithm. :Parameters: **output_settings** : :class:`~leaspy.algo.OutputsSettings` Contains the logs settings for the computation run (console print periodicity, plot periodicity ...) .. rubric:: Examples >>> from leaspy.algo import AlgorithmSettings, algorithm_factory, OutputsSettings >>> algo_settings = AlgorithmSettings("mcmc_saem") >>> my_algo = algorithm_factory(algo_settings) >>> settings = { 'path': 'brouillons', 'print_periodicity': 50, 'plot_periodicity': 100, 'save_periodicity': 50 } >>> my_algo.set_output_manager(OutputsSettings(settings)) .. !! processed by numpydoc !! .. py:class:: FitOutputManager(outputs) Class used by :class:`~leaspy.algo.AbstractAlgo` (and its child classes) to display & save plots and statistics during algorithm execution. :Parameters: **outputs** : :class:`~leaspy.algo.OutputsSettings` Initialize the `FitOutputManager` class attributes, like the logs paths, the console print periodicity and so forth. :Attributes: **path_output** : :obj:`str` Path of the folder containing all the outputs **path_plot** : :obj:`str` Path of the subfolder of path_output containing the logs plots **path_plot_convergence_model_parameters** : :obj:`str` Path of the first plot of the convergence of the model's parameters (in the subfolder path_plot) **path_plot_patients** : :obj:`str` Path of the subfolder of path_plot containing the plot of the reconstruction of the patients' longitudinal trajectory by the model **nb_of_patients_to_plot** : :obj:`int` Number of patients for whom the reconstructions will be plotted. **path_save_model_parameters_convergence** : :obj:`str` Path of the subfolder of path_output containing the progression of the model's parameters convergence **periodicity_plot** : :obj:`int` (default 100) Set the frequency of the display of the plots **periodicity_print** : :obj:`int` Set the frequency of the display of the statistics **periodicity_save** : :obj:`int` Set the frequency of the saves of the model's parameters **periodicity_plot_patients** : :obj:`int` Set the frequency of the saves of the patients' reconstructions **plot_sourcewise** : :obj:`bool` If True, plots will be generated for each source separately. .. !! processed by numpydoc !! .. py:attribute:: periodicity_print .. py:attribute:: periodicity_save .. py:attribute:: periodicity_plot .. py:attribute:: nb_of_patients_to_plot .. py:attribute:: periodicity_plot_patients .. py:attribute:: plot_sourcewise .. py:attribute:: time .. py:method:: iteration(algo, model, data) Call methods to save state of the running computation, display statistics & plots if the current iteration is a multiple of `periodicity_print`, `periodicity_plot` or `periodicity_save` :Parameters: **algo** : :class:`~leaspy.algo.fit.FitAlgo` A fitting algorithm. **model** : :class:`~leaspy.models.McmcSaemCompatibleModel` The model used by the computation. **data** : :class:`.Dataset` The data used by the computation .. !! processed by numpydoc !! .. py:method:: print_time() Prints the duration since the last periodic point. .. !! processed by numpydoc !! .. py:method:: print_model_statistics(model) Prints model's statistics. :Parameters: **model** : :class:`~leaspy.models.McmcSaemCompatibleModel` The model used by the computation .. !! processed by numpydoc !! .. py:method:: print_algo_statistics(algo) Prints algorithm's statistics :Parameters: **algo** : :class:`~leaspy.algo.fit.FitAlgo` A fitting algorithm. .. !! processed by numpydoc !! .. py:method:: save_model_parameters_convergence(iteration, model) Saves the current state of the model's parameters :Parameters: **iteration** : :obj:`int` The current iteration. **model** : :class:`~.models.abstract_model.McmcSaemCompatibleModel` The model used by the computation .. !! processed by numpydoc !! .. py:method:: save_plot_convergence_model_parameters(model) Saves figures of the model parameters' convergence in multiple pages of a PDF. :Parameters: **model** : :class:`~leaspy.models.McmcSaemCompatibleModel` The model used by the computation .. !! processed by numpydoc !! .. py:method:: save_plot_patient_reconstructions(iteration, model, data) Saves figures of real longitudinal values and their reconstructions computed by the model for maximum 5 patients during each iteration. :Parameters: **iteration** : :obj:`int` The current iteration **model** : :class:`~leaspy.models.McmcSaemCompatibleModel` The model used by the computation **data** : :class:`~leaspy.io.data.Dataset` The dataset used by the computation .. !! processed by numpydoc !! .. py:class:: LMEFitAlgorithm(settings) Bases: :py:obj:`leaspy.algo.fit.base.FitAlgorithm`\ [\ :py:obj:`leaspy.models.LMEModel`\ , :py:obj:`tuple`\ ] Fitting algorithm associated to :class:`~.models.LMEModel`. :Parameters: **settings** : :class:`.AlgorithmSettings` * force_independent_random_effects : :obj:`bool` Force independence of random intercept & random slope * other keyword arguments passed to :meth:`statsmodels.regression.mixed_linear_model.MixedLM.fit` .. seealso:: :class:`statsmodels.regression.mixed_linear_model.MixedLM` .. .. !! processed by numpydoc !! .. py:attribute:: name :type: leaspy.algo.base.AlgorithmName .. py:attribute:: force_independent_random_effects .. py:attribute:: sm_fit_parameters .. py:method:: set_output_manager(output_settings) Not implemented. .. !! processed by numpydoc !! .. py:class:: TensorMcmcSaemAlgorithm(settings) Bases: :py:obj:`leaspy.algo.algo_with_device.AlgorithmWithDeviceMixin`, :py:obj:`leaspy.algo.algo_with_annealing.AlgorithmWithAnnealingMixin`, :py:obj:`leaspy.algo.algo_with_samplers.AlgorithmWithSamplersMixin`, :py:obj:`leaspy.algo.fit.base.FitAlgorithm`\ [\ :py:obj:`leaspy.models.McmcSaemCompatibleModel`\ , :py:obj:`leaspy.variables.state.State`\ ] Main algorithm for MCMC-SAEM. :Parameters: **settings** : :class:`~leaspy.algo.AlgorithmSettings` MCMC fit algorithm settings :Attributes: **samplers** : :obj:`dict` [:obj:`str`, :class:`~leaspy.samplers.AbstractSampler` ] Dictionary of samplers per each variable **random_order_variables** : :obj:`bool` (default True) This attribute controls whether we randomize the order of variables at each iteration. `Article `_ gives a reason on why we should activate this flag. **temperature** : :obj:`float` .. **temperature_inv** : :obj:`float` Temperature and its inverse are modified during algorithm if annealing is used .. seealso:: :mod:`leaspy.samplers` .. .. !! processed by numpydoc !! .. py:attribute:: name :type: leaspy.algo.base.AlgorithmName .. py:method:: log_current_iteration(state) .. py:method:: is_current_iteration_in_last_n() Return True if current iteration is within the last n realizations defined in logging settings. .. !! processed by numpydoc !! .. py:method:: should_current_iteration_be_saved() Return True if current iteration should be saved based on log saving periodicity. .. !! processed by numpydoc !!