leaspy.io.outputs.individual_parameters ======================================= .. py:module:: leaspy.io.outputs.individual_parameters Classes ------- .. autoapisummary:: leaspy.io.outputs.individual_parameters.IndividualParameters Module Contents --------------- .. py:class:: IndividualParameters Data container for individual parameters, contains IDs, timepoints and observations values. Output of the :class:`.leaspy.algo.personalize` method, contains the *random effects*. There are used as output of the `personalization algorithms` and as input/output of the `simulation algorithm`, to provide an initial distribution of individual parameters. :Attributes: **_indices** : :obj:`list` List of the patient indices **_individual_parameters** : :obj:`dict` Individual indices (key) with their corresponding individual parameters {parameter name: parameter value} **_parameters_shape** : :obj:`dict` Shape of each individual parameter **_default_saving_type** : :obj:`str` Default extension for saving when none is provided .. !! processed by numpydoc !! .. py:attribute:: VALID_IO_EXTENSIONS :value: ['csv', 'json'] .. py:method:: add_individual_parameters(index, individual_parameters) Add the individual parameter of an individual to the IndividualParameters object :Parameters: **index** : :class::class:`~leaspy..utils.typing.IDType` Index of the individual **individual_parameters** : :class:`~leaspy.utils.typing.DictParams` Individual parameters of the individual :Raises: :exc:`.LeaspyIndividualParamsInputError` * If the index is not a string or has already been added * Or if the individual parameters is not a dict. * Or if individual parameters are not self-consistent. .. rubric:: Examples Add two individual with tau, xi and sources parameters >>> ip = IndividualParameters() >>> ip.add_individual_parameters('index-1', {"xi": 0.1, "tau": 70, "sources": [0.1, -0.3]}) >>> ip.add_individual_parameters('index-2', {"xi": 0.2, "tau": 73, "sources": [-0.4, -0.1]}) .. !! processed by numpydoc !! .. py:method:: items() Get the items of the individual parameters dictionary. :Returns: ItemsView A view object displaying a list of tuples (individual ID, parameters dict) .. rubric:: Examples >>> ip = IndividualParameters() >>> ip.add_individual_parameters('index-1', {"xi": 0.1, "tau": 70, "sources": [0.1, -0.3]}) >>> list(ip.items()) ['index-1', {"xi": 0.1, "tau": 70, "sources": [0.1, -0.3]}] .. !! processed by numpydoc !! .. py:method:: subset(indices, *, copy = True) Returns IndividualParameters object with a subset of the initial individuals :Parameters: **indices** : :obj:`Iterable`[:class:`~leaspy.utils.typing.IDType`] List of strings that corresponds to the indices of the individuals to return **copy** : :obj:`bool`, optional (default True) Should we copy underlying parameters or not? :Returns: :class:`.IndividualParameters` An instance of the IndividualParameters object with the selected list of individuals :Raises: :exc:`.LeaspyIndividualParamsInputError` Raise an error if one of the index is not in the IndividualParameters .. rubric:: Examples >>> ip = IndividualParameters() >>> ip.add_individual_parameters('index-1', {"xi": 0.1, "tau": 70, "sources": [0.1, -0.3]}) >>> ip.add_individual_parameters('index-2', {"xi": 0.2, "tau": 73, "sources": [-0.4, -0.1]}) >>> ip.add_individual_parameters('index-3', {"xi": 0.3, "tau": 58, "sources": [-0.6, 0.2]}) >>> ip_sub = ip.subset(['index-1', 'index-3']) .. !! processed by numpydoc !! .. py:method:: get_aggregate(parameter, function) Returns the result of aggregation by `function` of parameter values across all patients :Parameters: **parameter** : :class:`~leaspy..utils.typing.ParamType` Name of the parameter **function** : :obj:`Callable` A function operating on iterables and supporting axis keyword, and outputing an iterable supporting the `tolist` method. :Returns: :obj:`list` Resulting value of the parameter :Raises: :exc:`.LeaspyIndividualParamsInputError` * If individual parameters are empty, * or if the parameter is not in the IndividualParameters. .. rubric:: Examples >>> ip = IndividualParameters.load("path/to/individual_parameters") >>> tau_median = ip.get_aggregate("tau", np.median) .. !! processed by numpydoc !! .. py:method:: get_mean(parameter) Returns the mean value of a parameter across all patients :Parameters: **parameter** : :class:`~leaspy.utils.typing.ParamType` Name of the parameter :Returns: :obj:`list` Mean value of the parameter :Raises: :exc:`.LeaspyIndividualParamsInputError` * If individual parameters are empty, * or if the parameter is not in the IndividualParameters. .. rubric:: Examples >>> ip = IndividualParameters.load("path/to/individual_parameters") >>> tau_mean = ip.get_mean("tau") .. !! processed by numpydoc !! .. py:method:: get_std(parameter) Returns the standard deviation of a parameter across all patients :Parameters: **parameter** : :class:`~leaspy.utils.typing.ParamType` Name of the parameter :Returns: :obj:`list` Standard-deviation value of the parameter :Raises: :exc:`.LeaspyIndividualParamsInputError` * If individual parameters are empty, * or if the parameter is not in the IndividualParameters. .. rubric:: Examples >>> ip = IndividualParameters.load("path/to/individual_parameters") >>> tau_std = ip.get_std("tau") .. !! processed by numpydoc !! .. py:method:: to_dataframe() Returns the dataframe of individual parameters :Returns: :class:`pandas.DataFrame` Each row corresponds to one individual. The index corresponds to the individual index ('ID'). The columns are the names of the parameters. .. rubric:: Examples Convert the individual parameters object into a dataframe >>> ip = IndividualParameters.load("path/to/individual_parameters") >>> ip_df = ip.to_dataframe() .. !! processed by numpydoc !! .. py:method:: from_dataframe(df) :staticmethod: Static method that returns an IndividualParameters object from the dataframe :Parameters: **df** : :class:`pandas.DataFrame` Dataframe of the individual parameters. Each row must correspond to one individual. The index corresponds to the individual index. The columns are the names of the parameters. :Returns: :class:`.IndividualParameters` An instance of IndividualParameters initialized from the DataFrame. .. rubric:: Examples >>> import pandas as pd >>> data = { >>> 'tau': [70, 73], >>> 'xi': [0.1, 0.2], >>> 'sources_0': [0.1, -0.4], >>> 'sources_1': [-0.3, -0.1] >>> } >>> df = pd.DataFrame(data, index=['id1', 'id2']) >>> ip = IndividualParameters.from_dataframe(df) .. !! processed by numpydoc !! .. py:method:: from_pytorch(indices, dict_pytorch) :staticmethod: Static method that returns an IndividualParameters object from the indices and pytorch dictionary :Parameters: **indices** : :obj:`list`[:class:`~leaspy.utils.typing.IDType`] List of the patients indices **dict_pytorch** : :class:`~leaspy.utils.typing.DictParmasTorch` Dictionary of the individual parameters :Returns: :class:`.IndividualParameters` An instance of IndividualParameters initialized from the pytorch dictionary. :Raises: :exc:`.LeaspyIndividualParamsInputError` .. .. rubric:: Examples >>> indices = ['index-1', 'index-2', 'index-3'] >>> ip_pytorch = { >>> "xi": torch.tensor([[0.1], [0.2], [0.3]], dtype=torch.float32), >>> "tau": torch.tensor([[70], [73], [58.]], dtype=torch.float32), >>> "sources": torch.tensor([[0.1, -0.3], [-0.4, 0.1], [-0.6, 0.2]], dtype=torch.float32) >>> } >>> ip_pytorch = IndividualParameters.from_pytorch(indices, ip_pytorch) .. !! processed by numpydoc !! .. py:method:: to_pytorch() Returns the indices and pytorch dictionary of individual parameters :Returns: indices: :obj:`list`[:class:`~leaspy.utils.typing.IDType`] List of patient indices pytorch_dict: :class:`~leaspy.utils.typing.DictParamsTorch` Dictionary of the individual parameters {parameter name: pytorch tensor of values across individuals} .. rubric:: Examples Convert the individual parameters object into a dataframe >>> ip = IndividualParameters.load("path/to/individual_parameters") >>> indices, ip_pytorch = ip.to_pytorch() .. !! processed by numpydoc !! .. py:method:: save(path, **kwargs) Saves the individual parameters (json or csv) at the path location TODO? save leaspy version as well for retro/future-compatibility issues? :Parameters: **path** : :obj:`str` Path and file name of the individual parameters. The extension can be json or csv. If no extension, default extension (csv) is used **\*\*kwargs** Additional keyword arguments to pass to either: * :meth:`pandas.DataFrame.to_csv` * :func:`json.dump` depending on saving format requested :Raises: :exc:`.LeaspyIndividualParamsInputError` * If extension not supported for saving * If individual parameters are empty .. warning:: Emits a warning if no file extension is provided and the default extension is used. .. rubric:: Examples >>> ip.save("params.csv", index=False) >>> ip.save("params.json", indent=4) .. !! processed by numpydoc !! .. py:method:: load(path) :classmethod: Static method that loads the individual parameters (json or csv) existing at the path location :Parameters: **path** : :obj:`str` Path and file name of the individual parameters. :Returns: :class:`.IndividualParameters` Individual parameters object load from the file :Raises: :exc:`.LeaspyIndividualParamsInputError` If the provided extension is not `csv` or not `json`. .. rubric:: Examples >>> ip = IndividualParameters.load('/path/to/individual_parameters_1.json') >>> ip2 = IndividualParameters.load('/path/to/individual_parameters_2.csv') .. !! processed by numpydoc !!