leaspy.io.outputs.individual_parameters module

class IndividualParameters

Bases: object

Data container for individual parameters, contains IDs, timepoints and observations values. Output of the Leaspy.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:

_indiceslist: List of the patient indices
_individual_parametersdict: Individual indices (key) with their corresponding individual parameters {parameter name: parameter value}
_parameters_shapedict: Shape of each individual parameter
_default_saving_typestr: Default extension for saving when none is provided

Methods

`add_individual_parameters`(index, ...)	Add the individual parameter of an individual to the IndividualParameters object
`from_dataframe`(df)	Static method that returns an IndividualParameters object from the dataframe
`from_pytorch`(indices, dict_pytorch)	Static method that returns an IndividualParameters object from the indices and pytorch dictionary
`get_aggregate`(parameter, function)	Returns the result of aggregation by function of parameter values across all patients
`get_mean`(parameter)	Returns the mean value of a parameter across all patients
`get_std`(parameter)	Returns the standard deviation of a parameter across all patients
`items`()	Get items of dict `_individual_parameters`.
`load`(path)	Static method that loads the individual parameters (json or csv) existing at the path location
`save`(path, **kwargs)	Saves the individual parameters (json or csv) at the path location
`subset`(indices, *[, copy])	Returns IndividualParameters object with a subset of the initial individuals
`to_dataframe`()	Returns the dataframe of individual parameters
`to_pytorch`()	Returns the indices and pytorch dictionary of individual parameters

VALID_IO_EXTENSIONS = ['csv', 'json']

add_individual_parameters(index: str, individual_parameters: Dict[str, Any])

Add the individual parameter of an individual to the IndividualParameters object

Parameters:

indexstr: Index of the individual
individual_parametersdict: Individual parameters of the individual {name: value:}

Raises:

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.

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]})

static from_dataframe(df: DataFrame)

Static method that returns an IndividualParameters object from the dataframe

Parameters:

dfpandas.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:

IndividualParameters

static from_pytorch(indices: List[str], dict_pytorch: Dict[str, Tensor])

Static method that returns an IndividualParameters object from the indices and pytorch dictionary

Parameters:

indiceslist[ID]: List of the patients indices
dict_pytorchdict[parameter:str, torch.Tensor]: Dictionary of the individual parameters

Returns:

IndividualParameters

Raises:

LeaspyIndividualParamsInputError

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)

get_aggregate(parameter: str, function: Callable) → List

Returns the result of aggregation by function of parameter values across all patients

Parameters:

parameterstr: Name of the parameter
functioncallable: A function operating on iterables and supporting axis keyword, and outputing an iterable supporting the tolist method.

Returns:

list or float (depending on parameter shape): Resulting value of the parameter

Raises:

LeaspyIndividualParamsInputError

If individual parameters are empty,
or if the parameter is not in the IndividualParameters.

Examples

>>> ip = IndividualParameters.load("path/to/individual_parameters")
>>> tau_median = ip.get_aggregate("tau", np.median)

get_mean(parameter: str)

Returns the mean value of a parameter across all patients

Parameters:

parameterstr: Name of the parameter

Returns:

list or float (depending on parameter shape): Mean value of the parameter

Raises:

LeaspyIndividualParamsInputError

If individual parameters are empty,
or if the parameter is not in the IndividualParameters.

Examples

>>> ip = IndividualParameters.load("path/to/individual_parameters")
>>> tau_mean = ip.get_mean("tau")

get_std(parameter: str)

Returns the standard deviation of a parameter across all patients

Parameters:

parameterstr: Name of the parameter

Returns:

list or float (depending on parameter shape): Standard-deviation value of the parameter

Raises:

LeaspyIndividualParamsInputError

If individual parameters are empty,
or if the parameter is not in the IndividualParameters.

Examples

>>> ip = IndividualParameters.load("path/to/individual_parameters")
>>> tau_std = ip.get_std("tau")

items(): Get items of dict _individual_parameters.

classmethod load(path: str)

Static method that loads the individual parameters (json or csv) existing at the path location

Parameters:

pathstr: Path and file name of the individual parameters.

Returns:

IndividualParameters: Individual parameters object load from the file

Raises:

LeaspyIndividualParamsInputError: If the provided extension is not csv or not json.

Examples

>>> ip = IndividualParameters.load('/path/to/individual_parameters_1.json')
>>> ip2 = IndividualParameters.load('/path/to/individual_parameters_2.csv')

save(path: str, **kwargs)

Saves the individual parameters (json or csv) at the path location

TODO? save leaspy version as well for retro/future-compatibility issues?

Parameters:

pathstr: 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: * pandas.DataFrame.to_csv() * json.dump() depending on saving format requested

Raises:

LeaspyIndividualParamsInputError

If extension not supported for saving
If individual parameters are empty

subset(indices: Iterable[str], *, copy: bool = True)

Returns IndividualParameters object with a subset of the initial individuals

Parameters:

indiceslist[ID]: List of strings that corresponds to the indices of the individuals to return
copybool, optional (default True): Should we copy underlying parameters or not?

Returns:

IndividualParameters: An instance of the IndividualParameters object with the selected list of individuals

Raises:

LeaspyIndividualParamsInputError: Raise an error if one of the index is not in the IndividualParameters

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'])

to_dataframe() → DataFrame

Returns the dataframe of individual parameters

Returns:

pandas.DataFrame: Each row corresponds to one individual. The index corresponds to the individual index (‘ID’). The columns are the names of the parameters.

Examples

Convert the individual parameters object into a dataframe

>>> ip = IndividualParameters.load("path/to/individual_parameters")
>>> ip_df = ip.to_dataframe()

to_pytorch() → Tuple[List[str], Dict[str, Tensor]]

Returns the indices and pytorch dictionary of individual parameters

Returns:

indices: list[ID]: List of patient indices
pytorch_dict: dict[parameter:str, torch.Tensor]: Dictionary of the individual parameters {parameter name: pytorch tensor of values across individuals}

Examples

Convert the individual parameters object into a dataframe

>>> ip = IndividualParameters.load("path/to/individual_parameters")
>>> indices, ip_pytorch = ip.to_pytorch()