leaspy.io.outputs.result ======================== .. py:module:: leaspy.io.outputs.result Classes ------- .. autoapisummary:: leaspy.io.outputs.result.Result Module Contents --------------- .. py:class:: Result(data, individual_parameters, noise_std=None) Result object class. Used as logs by personalize algorithms & simulation algorithm. :Parameters: **data** : :class:`.Data` Object containing the information of the individuals, in particular the time-points :math:`(t_{i,j})` and the observations :math:`(y_{i,j})`. **individual_parameters** : :obj:`dict` [:obj:`str`, :class:`torch.Tensor`] Contains log-acceleration 'xi', time-shifts 'tau' & 'sources' **noise_std** : :obj:`float` or :class:`torch.FloatTensor`, optional (default None) Desired noise standard deviation level :Attributes: **data** : :class:`.Data` Object containing the information of the individuals, in particular the time-points :math:`(t_{i,j})` and the observations :math:`(y_{i,j})`. **individual_parameters** : :obj:`dict` [:obj:`str`, :class:`torch.Tensor`] Contains log-acceleration 'xi', time-shifts 'tau' & 'sources' (dictionary of `torch.Tensor`). **ID_to_idx** : :obj:`dict` The keys are the individual ID & the items are their respective ordered position in the data file given by the user. This order remains the same during the computation. Example - in Result.individual_parameters['xi'], the first element corresponds to the first patient in ID_to_idx. **noise_std** : :obj:`float` or :class:`torch.FloatTensor` Desired noise standard deviation level. .. !! processed by numpydoc !! .. py:attribute:: data .. py:attribute:: individual_parameters .. py:attribute:: ID_to_idx :type: dict[leaspy.utils.typing.IDType, int] .. py:attribute:: noise_std :value: None .. py:method:: get_torch_individual_parameters(ID = None) Getter function for the individual parameters. :Parameters: **ID** : :obj:`str` or :obj:`list`[:obj:`str`], optional (default None) Contains the identifiers of the wanted subject. :Returns: :obj:`dict` [:obj:`str`, :class:`torch.Tensor`] Contains the individual parameters. .. !! processed by numpydoc !! .. py:method:: get_dataframe_individual_parameters(cofactors = None) Return the dataframe of the individual parameters. Each row corresponds to a subject. The columns correspond (in this order) to the subjects' ID, the individual parameters (one column per individual parameter) & the cofactors (one column per cofactor). :Parameters: **cofactors** : :obj:`str` or :obj:`list`[:obj:`str`], optional (default None) Contains the cofactor(s) to join to the logs dataframe. :Returns: :class:`pandas.DataFrame` Contains for each patient his ID & his individual parameters (optional and his cofactors states) .. rubric:: Notes The cofactors must be present in the leaspy data object stored into the .data attribute of the result instance. See the example. .. rubric:: Examples Load a longitudinal multivariate dataset & the subjects' cofactors. Compute the individual parameters for this dataset & get the corresponding dataframe with the genetic APOE cofactor >>> import pandas as pd >>> from leaspy.api import Leaspy >>> from leaspy.algo import AlgorithmSettings >>> from leaspy.io.data import Data >>> from leaspy.io.logs.visualization import Plotter >>> leaspy_logistic = Leaspy('logistic') >>> data = Data.from_csv_file('data/my_leaspy_data.csv') # replace with your own path! >>> genes_cofactors = pd.read_csv('data/genes_cofactors.csv') # replace with your own path! >>> print(genes_cofactors.head()) ID APOE4 0 sub-HS0102 1 1 sub-HS0112 0 2 sub-HS0113 0 3 sub-HS0114 1 4 sub-HS0115 0 >>> data.load_cofactors(genes_cofactors, ['GENES']) >>> model_settings = AlgorithmSettings('mcmc_saem', seed=0) >>> personalize_settings = AlgorithmSettings('mode_real', seed=0) >>> leaspy_logistic.fit(data, model_settings) >>> individual_results = leaspy_logistic.personalize(data, model_settings) >>> individual_results_df = individual_results.get_dataframe_individual_parameters('GENES') >>> print(individual_results_df.head()) tau xi sources_0 sources_1 APOE4 ID sub-HS0102 70.329201 0.120465 5.969921 -0.245034 1 sub-HS0112 95.156624 -0.692099 1.520273 3.477707 0 sub-HS0113 74.900673 -1.769864 -1.222979 1.665889 0 sub-HS0114 81.792763 -1.003620 1.021321 2.371716 1 sub-HS0115 89.724648 -0.820971 -0.480975 0.741601 0 .. !! processed by numpydoc !! .. py:method:: save_individual_parameters_csv(path, idx = None, cofactors=None, **args) Save the individual parameters in a csv format. :Parameters: **path** : :obj:`str` The logs' path. **idx** : :obj:`list` [:obj:`str`], optional (default None) Contain the IDs of the selected subjects. If ``None``, all the subjects are selected. **cofactors** : :obj:`str` or :obj:`list` [:obj:`str`], optional (default None) Contains the cofactor(s) to join to the logs dataframe. **\*\*args** Parameters to pass to :meth:`pandas.DataFrame.to_csv`. .. rubric:: Notes The cofactors must be present in the leaspy data object stored into the :attr:`.data` attribute of the result instance. See the example. .. rubric:: Examples Save the individual parameters of the twenty first subjects. >>> from leaspy.algo import AlgorithmSettings >>> from leaspy.api import Leaspy >>> from leaspy.io.data import Data >>> leaspy_logistic = Leaspy('logistic') >>> data = Data.from_csv_file('data/my_leaspy_data.csv') # replace with your own path! >>> genes_cofactors = pd.read_csv('data/genes_cofactors.csv') # replace with your own path! >>> data.load_cofactors(genes_cofactors, ['GENES']) >>> model_settings = AlgorithmSettings('mcmc_saem', seed=0) >>> personalize_settings = AlgorithmSettings('mode_real', seed=0) >>> leaspy_logistic.fit(data, model_settings) >>> individual_results = leaspy_logistic.personalize(data, model_settings) >>> output_path = 'outputs/logistic_seed0-mode_real_seed0-individual_parameter.csv' >>> idx = list(individual_results.individual_parameters.keys())[:20] >>> individual_results.save_individual_parameters_csv(output_path, idx, cofactors='GENES') .. !! processed by numpydoc !! .. py:method:: save_individual_parameters_json(path, idx = None, human_readable=None, **args) Save the individual parameters in a json format. :Parameters: **path** : :obj:`str` The logs' path. **idx** : :obj:`list` [:obj:`str`], optional (default None) Contain the IDs of the selected subjects. If ``None``, all the subjects are selected. **human_readable** : Any, optional (default None) --> TODO change to bool .. deprecated:: 1.0 * If None (default): save as json file * If not None: call :meth:`.save_individual_parameters_torch`. **\*\*args** Arguments to pass to json.dump. Default to: dict(indent=2) :Raises: :class:`NotADirectoryError` if parent directory of path does not exist. .. rubric:: Examples Save the individual parameters of the twenty first subjects. >>> from leaspy.algo import AlgorithmSettings >>> from leaspy.api import Leaspy >>> from leaspy.io.data import Data >>> leaspy_logistic = Leaspy('logistic') >>> data = Data.from_csv_file('data/my_leaspy_data.csv') >>> model_settings = AlgorithmSettings('mcmc_saem', seed=0) >>> personalize_settings = AlgorithmSettings('mode_real', seed=0) >>> leaspy_logistic.fit(data, model_settings) >>> individual_results = leaspy_logistic.personalize(data, model_settings) >>> output_path = 'outputs/logistic_seed0-mode_real_seed0-individual_parameter.json' >>> idx = list(individual_results.individual_parameters.keys())[:20] >>> individual_results.save_individual_parameters_json(output_path, idx) .. !! processed by numpydoc !! .. py:method:: save_individual_parameters_torch(path, idx = None, **args) Save the individual parameters in a torch format. :Parameters: **path** : :obj:`str` The logs' path. **idx** : :obj:`list` [:obj:`str`], optional (default None) Contain the IDs of the selected subjects. If ``None``, all the subjects are selected. **\*\*args** Arguments to pass to torch.save. :Raises: :exc:`NotADirectoryError` if parent directory of path does not exist. .. rubric:: Examples Save the individual parameters of the twenty first subjects. >>> from leaspy.algo import AlgorithmSettings >>> from leaspy.api import Leaspy >>> from leaspy.io.data import Data >>> leaspy_logistic = Leaspy('logistic') >>> data = Data.from_csv_file('data/my_leaspy_data.csv') >>> model_settings = AlgorithmSettings('mcmc_saem', seed=0) >>> personalize_settings = AlgorithmSettings('mode_real', seed=0) >>> leaspy_logistic.fit(data, model_settings) >>> individual_results = leaspy_logistic.personalize(data, model_settings) >>> output_path = 'outputs/logistic_seed0-mode_real_seed0-individual_parameter.pt' >>> idx = list(individual_results.individual_parameters.keys())[:20] >>> individual_results.save_individual_parameters_torch(output_path, idx) .. !! processed by numpydoc !! .. py:method:: load_individual_parameters_from_csv(path, *, verbose=True, **kwargs) :classmethod: Load individual parameters from a csv. :Parameters: **path** : :obj:`str` The file's path. The csv file musts contain two columns named 'tau' and 'xi'. If the individual parameters come from a multivariate model, it must also contain the columns 'sources_i' for i in [0, ..., n_sources]. **verbose** : :obj:`bool` (default True) Whether to have verbose output or not **\*\*kwargs** Parameters to pass to :func:`pandas.read_csv`. :Returns: :obj:`dict` [:obj:`str`, :class:`torch.Tensor`] A dictionary of torch.tensor which contains the individual parameters. .. rubric:: Examples Load an individual parameters dictionary from a saved file. >>> from leaspy.io.outputs import Result >>> path = 'outputs/logistic_seed0-mode_real_seed0-individual_parameter.csv' >>> individual_parameters = Result.load_individual_parameters_from_csv(path) .. !! processed by numpydoc !! .. py:method:: load_individual_parameters_from_dataframe(df) :staticmethod: Load individual parameters from a :class:`pandas.DataFrame`. :Parameters: **df** : :class:`pandas.DataFrame` Must contain two columns named 'tau' and 'xi'. If the individual parameters come from a multivariate model, it must also contain the columns 'sources_i' for i in [0, ..., n_sources]. :Returns: :obj:`dict`[:obj:`str`, :class:`torch.Tensor`] A dictionary of torch.tensor which contains the individual parameters. .. !! processed by numpydoc !! .. py:method:: load_individual_parameters_from_json(path, *, verbose=True, **kwargs) :staticmethod: Load individual parameters from a json file. Deprecated : also load torch files. :Parameters: **path** : :obj:`str` The file's path. **verbose** : :obj:`bool` (default True) Whether to have verbose output or not **\*\*kwargs** Parameters to pass to :func:`json.load`. :Returns: :obj:`dict` [:obj:`str`, :class:`torch.Tensor`] A dictionary of `torch.Tensor` which contains the individual parameters. .. rubric:: Examples Load an individual parameters dictionary from a saved file. >>> from leaspy.io.outputs import Result >>> path = 'outputs/logistic_seed0-mode_real_seed0-individual_parameter.json' >>> individual_parameters = Result.load_individual_parameters_from_json(path) .. !! processed by numpydoc !! .. py:method:: load_individual_parameters_from_torch(path, *, verbose=True, **kwargs) :staticmethod: Load individual parameters from a torch file. :Parameters: **path** : :obj:`str` The file's path. **verbose** : :obj:`bool` (default True) Whether to have verbose output or not **\*\*kwargs** Parameters to pass to :func:`torch.load`. :Returns: :obj:`dict` [:obj:`str`, :class:`torch.Tensor`] A dictionary of `torch.Tensor` which contains the individual parameters. .. rubric:: Examples Load an individual parameters dictionary from a saved file. >>> from leaspy.io.outputs import Result >>> path = 'outputs/logistic_seed0-mode_real_seed0-individual_parameter.pt' >>> individual_parameters = Result.load_individual_parameters_from_torch(path) .. !! processed by numpydoc !! .. py:method:: load_individual_parameters(path_or_df, **kwargs) :classmethod: Load individual parameters from a :class:`pandas.DataFrame`, a csv, a json file or a torch file. :Parameters: **path_or_df** : str or :class:`pandas.DataFrame` The file's path or a DataFrame containing the individual parameters. **\*\*kwargs** Keyword-arguments to be passed to the corresponding load function. :Returns: :obj:`dict` [:obj:`str`, :class:`torch.Tensor`] A dictionary of torch.tensor which contains the individual parameters. :Raises: :exc:`FileNotFoundError` if path is invalid .. !! processed by numpydoc !! .. py:method:: load_result(data, individual_parameters, *, cofactors=None, **kwargs) :classmethod: Load a `Result` class object from two file - one for the individual data & one for the individual parameters. :Parameters: **data** : :obj:`str` or :class:`pandas.DataFrame` or :class:`.Data` The file's path or a DataFrame containing the features' scores. **individual_parameters** : :obj:`str` or :class:`pandas.DataFrame` The file's path or a DataFrame containing the individual parameters. **cofactors** : :obj:`str` or :class:`pandas.DataFrame`, optional (default None) The file's path or a DataFrame containing the individual cofactors. The ID must be in index! Thus, the shape is (n_subjects, n_cofactors). **\*\*kwargs** Parameters to pass to `Result.load_individual_parameters` method. :Returns: :class:`Result` A Result class object which contains the individual parameters and the individual data. .. rubric:: Examples Launch an individual parameters estimation, save it and reload it. >>> from leaspy.algo import AlgorithmSettings >>> from leaspy.io.outputs import Result >>> from leaspy.api import Leaspy >>> from leaspy.io.data import Data >>> leaspy_logistic = Leaspy('logistic') >>> data = Data.from_csv_file('data/my_leaspy_data.csv') >>> model_settings = AlgorithmSettings('mcmc_saem', seed=0) >>> personalize_settings = AlgorithmSettings('mode_real', seed=0) >>> leaspy_logistic.fit(data, model_settings) >>> individual_results = leaspy_logistic.personalize(data, model_settings) >>> path_data = 'data/my_leaspy_data.csv' >>> path_individual_parameters = 'outputs/logistic_seed0-mode_real_seed0-individual_parameter.json' >>> individual_results.data.to_dataframe().to_csv(path_data) >>> individual_results.save_individual_parameters_json(path_individual_parameters) >>> individual_parameters = Result.load_result(path_data, path_individual_parameters) .. !! processed by numpydoc !! .. py:method:: get_error_distribution_dataframe(model, cofactors=None) Get signed residual distribution per patient, per sub-score & per visit. Each residual is equal to the modeled data minus the observed data. :Parameters: **model** : :class:`~.models.abstract_model.AbstractModel` .. **cofactors** : str, list [str], optional (default None) Contains the cofactors' names to be included in the DataFrame. By default, no cofactors are returned. If cofactors == "all", all the available cofactors are returned. :Returns: **residuals_dataframe** : :class:`pandas.DataFrame` with index ['ID', 'TIME'] .. .. rubric:: Examples Get mean absolute error per feature: >>> from leaspy.algo import AlgorithmSettings >>> from leaspy.api import Leaspy >>> from leaspy.io.data import Data >>> data = Data.from_csv_file("/my/data/path") >>> leaspy_logistic = Leaspy('logistic') >>> settings = AlgorithmSettings("mcmc_saem", seed=0) >>> leaspy_logistic.calibrate(data, settings) >>> settings = AlgorithmSettings("mode_real", seed=0) >>> results = leaspy_logistic.personalize(data, settings) >>> residuals_dataframe = results.get_error_distribution_dataframe(model) >>> residuals_dataframe.abs().mean() .. !! processed by numpydoc !! .. py:method:: get_cofactor_states(cofactors) :staticmethod: .. deprecated:: 1.0 Given a list of string return the list of unique elements. :Parameters: **cofactors** : list[str] Distribution list of the cofactors. :Returns: list Unique occurrences of the input vector. .. !! processed by numpydoc !! .. py:method:: get_parameter_distribution(parameter, cofactor=None) .. deprecated:: 1.0 Return the wanted parameter distribution (one distribution per covariate state). :Parameters: **parameter** : str The wanted parameter's name (ex: 'xi', 'tau', ...). It can also be `sources_i` to only get the i-th dimension of multivariate `sources` parameter. **cofactor** : str, optional (default None) The wanted cofactor's name. :Returns: list[float] or dict[str, Any] .. :Raises: :exc:`.LeaspyIndividualParamsInputError` if unsupported individual parameters :exc:`.LeaspyInputError` if unknown cofactor .. rubric:: Notes If ``cofactor is None``: * If the parameter is univariate => return a list the parameter's distribution: list[float] * If the parameter is multivariate => return a dictionary: {'parameter1': distribution of parameter variable 1, 'parameter2': ...} If ``cofactor is not None``: * If the parameter is univariate => return a dictionary: {'cofactor1': parameter distribution such that patient.covariate = covariate1, 'cofactor2': ...} * If the parameter is multivariate => return a dictionary: {'cofactor1': {'parameter1': ..., 'parameter2': ...}, 'cofactor2': {...}, ...} .. !! processed by numpydoc !! .. py:method:: get_cofactor_distribution(cofactor) .. deprecated:: 1.0 Get the list of the cofactor's distribution. :Parameters: **cofactor** : str Cofactor's name :Returns: list Cofactor's distribution. .. !! processed by numpydoc !! .. py:method:: get_patient_individual_parameters(idx) .. deprecated:: 1.0 Get the dictionary of the wanted patient's individual parameters :Parameters: **idx** : str ID of the wanted patient :Returns: dict[param_name:str, `torch.Tensor`] Patient's individual parameters .. !! processed by numpydoc !!