leaspy.io.outputs.result module

class Result(data: Data, individual_parameters: Dict[str, Tensor], noise_std=None)

Bases: object

Result object class. Used as logs by personalize algorithms & simulation algorithm.

Parameters:

dataData: Object containing the idx, time-points and observations of the patients
individual_parametersdict [str, torch.Tensor]: Contains log-acceleration ‘xi’, time-shifts ‘tau’ & ‘sources’
noise_stdfloat or torch.FloatTensor, optional (default None): Desired noise standard deviation level

Attributes:

dataData: Object containing the idx, time-points and observations of the patients.
individual_parametersdict [str, torch.Tensor]: Contains log-acceleration ‘xi’, time-shifts ‘tau’ & ‘sources’ (dictionary of torch.Tensor).
ID_to_idxdict: 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_stdfloat or torch.FloatTensor: Desired noise standard deviation level.

Methods

`get_cofactor_distribution`(cofactor)	Deprecated since version 1.0.
`get_cofactor_states`(cofactors)	Deprecated since version 1.0.
`get_dataframe_individual_parameters`([cofactors])	Return the dataframe of the individual parameters.
`get_error_distribution_dataframe`(model[, ...])	Get signed residual distribution per patient, per sub-score & per visit.
`get_parameter_distribution`(parameter[, cofactor])	Deprecated since version 1.0.
`get_patient_individual_parameters`(idx)	Deprecated since version 1.0.
`get_torch_individual_parameters`([ID])	Getter function for the individual parameters.
`load_individual_parameters`(path_or_df, **kwargs)	Load individual parameters from a `pandas.DataFrame`, a csv, a json file or a torch file.
`load_individual_parameters_from_csv`(path, *)	Load individual parameters from a csv.
`load_individual_parameters_from_dataframe`(df)	Load individual parameters from a `pandas.DataFrame`.
`load_individual_parameters_from_json`(path, *)	Load individual parameters from a json file.
`load_individual_parameters_from_torch`(path, *)	Load individual parameters from a torch file.
`load_result`(data, individual_parameters, *)	Load a Result class object from two file - one for the individual data & one for the individual parameters.
`save_individual_parameters_csv`(path[, idx, ...])	Save the individual parameters in a csv format.
`save_individual_parameters_json`(path[, idx, ...])	Save the individual parameters in a json format.
`save_individual_parameters_torch`(path[, idx])	Save the individual parameters in a torch format.

get_cofactor_distribution(cofactor: str)

Deprecated since version 1.0.

Get the list of the cofactor’s distribution.

Parameters:

cofactorstr: Cofactor’s name

Returns:

list: Cofactor’s distribution.

static get_cofactor_states(cofactors: List) → List

Deprecated since version 1.0.

Given a list of string return the list of unique elements.

Parameters:

cofactorslist[str]: Distribution list of the cofactors.

Returns:

list: Unique occurrences of the input vector.

get_dataframe_individual_parameters(cofactors: str | List[str] | None = None) → DataFrame

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:

cofactorsstr or list[str], optional (default None): Contains the cofactor(s) to join to the logs dataframe.

Returns:

pandas.DataFrame: Contains for each patient his ID & his individual parameters (optional and his cofactors states)

Notes

The cofactors must be present in the leaspy data object stored into the .data attribute of the result instance. See the example.

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 import AlgorithmSettings, Data, Leaspy, 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

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:

modelAbstractModel
cofactorsstr, 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_dataframepandas.DataFrame with index [‘ID’, ‘TIME’]

Examples

Get mean absolute error per feature:

>>> from leaspy import AlgorithmSettings, Data, Leaspy
>>> 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()

get_parameter_distribution(parameter: str, cofactor=None)

Deprecated since version 1.0.

Return the wanted parameter distribution (one distribution per covariate state).

Parameters:

parameterstr: 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.
cofactorstr, optional (default None): The wanted cofactor’s name.

Returns:

list[float] or dict[str, Any]

Raises:

LeaspyIndividualParamsInputError: if unsupported individual parameters
LeaspyInputError: if unknown cofactor

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’: {…}, …}

get_patient_individual_parameters(idx: str)

Deprecated since version 1.0.

Get the dictionary of the wanted patient’s individual parameters

Parameters:

idxstr: ID of the wanted patient

Returns:

dict[param_name:str, torch.Tensor]: Patient’s individual parameters

get_torch_individual_parameters(ID: str | List[str] | None = None) → Dict[str, Tensor]

Getter function for the individual parameters.

Parameters:

IDstr or list[str], optional (default None): Contains the identifiers of the wanted subject.

Returns:

dict [str, torch.Tensor]: Contains the individual parameters.

classmethod load_individual_parameters(path_or_df, **kwargs)

Load individual parameters from a pandas.DataFrame, a csv, a json file or a torch file.

Parameters:

path_or_dfstr or 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:

dict [str, torch.Tensor]: A dictionary of torch.tensor which contains the individual parameters.

Raises:

FileNotFoundError: if path is invalid

classmethod load_individual_parameters_from_csv(path: str, *, verbose=True, **kwargs)

Load individual parameters from a csv.

Parameters:

pathstr: 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].
verbosebool (default True): Whether to have verbose output or not
**kwargs: Parameters to pass to pandas.read_csv().

Returns:

dict [str, torch.Tensor]: A dictionary of torch.tensor which contains the individual parameters.

Examples

Load an individual parameters dictionary from a saved file.

>>> from leaspy import Result
>>> path = 'outputs/logistic_seed0-mode_real_seed0-individual_parameter.csv'
>>> individual_parameters = Result.load_individual_parameters_from_csv(path)

static load_individual_parameters_from_dataframe(df: DataFrame)

Load individual parameters from a pandas.DataFrame.

Parameters:

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

dict [str, torch.Tensor]: A dictionary of torch.tensor which contains the individual parameters.

static load_individual_parameters_from_json(path: str, *, verbose=True, **kwargs)

Load individual parameters from a json file.

Deprecated : also load torch files.

Parameters:

pathstr: The file’s path.
verbosebool (default True): Whether to have verbose output or not
**kwargs: Parameters to pass to json.load().

Returns:

dict [str, torch.Tensor]: A dictionary of torch.Tensor which contains the individual parameters.

Examples

Load an individual parameters dictionary from a saved file.

>>> from leaspy import Result
>>> path = 'outputs/logistic_seed0-mode_real_seed0-individual_parameter.json'
>>> individual_parameters = Result.load_individual_parameters_from_json(path)

static load_individual_parameters_from_torch(path: str, *, verbose=True, **kwargs)

Load individual parameters from a torch file.

Parameters:

pathstr: The file’s path.
verbosebool (default True): Whether to have verbose output or not
**kwargs: Parameters to pass to torch.load().

Returns:

dict [str, torch.Tensor]: A dictionary of torch.Tensor which contains the individual parameters.

Examples

Load an individual parameters dictionary from a saved file.

>>> from leaspy import Result
>>> path = 'outputs/logistic_seed0-mode_real_seed0-individual_parameter.pt'
>>> individual_parameters = Result.load_individual_parameters_from_torch(path)

classmethod load_result(data, individual_parameters, *, cofactors=None, **kwargs)

Load a Result class object from two file - one for the individual data & one for the individual parameters.

Parameters:

datastr or pandas.DataFrame or Data: The file’s path or a DataFrame containing the features’ scores.
individual_parametersstr or pandas.DataFrame: The file’s path or a DataFrame containing the individual parameters.
cofactorsstr or 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:

Result: A Result class object which contains the individual parameters and the individual data.

Examples

Launch an individual parameters estimation, save it and reload it.

>>> from leaspy import AlgorithmSettings, Data, Leaspy, Result
>>> 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)

save_individual_parameters_csv(path: str, idx: List[str] | None = None, cofactors=None, **args)

Save the individual parameters in a csv format.

Parameters:

pathstr: The logs’ path.
idxlist [str], optional (default None): Contain the IDs of the selected subjects. If None, all the subjects are selected.
cofactorsstr or list [str], optional (default None): Contains the cofactor(s) to join to the logs dataframe.
**args: Parameters to pass to pandas.DataFrame.to_csv().

Notes

The cofactors must be present in the leaspy data object stored into the data attribute of the result instance. See the example.

Examples

Save the individual parameters of the twenty first subjects.

>>> from leaspy import AlgorithmSettings, Data, Leaspy
>>> 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')

save_individual_parameters_json(path: str, idx: List[str] | None = None, human_readable=None, **args)

Save the individual parameters in a json format.

Parameters:

pathstr

The logs’ path.

idxlist [str], optional (default None)

Contain the IDs of the selected subjects. If None, all the subjects are selected.

human_readableAny, optional (default None) –> TODO change to bool

Deprecated since version 1.0:

If None (default): save as json file
If not None: call save_individual_parameters_torch().

**args

Arguments to pass to json.dump. Default to: dict(indent=2)

Raises:

NotADirectoryError: if parent directory of path does not exist.

Examples

Save the individual parameters of the twenty first subjects.

>>> from leaspy import AlgorithmSettings, Data, Leaspy
>>> 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)

save_individual_parameters_torch(path: str, idx: List[str] | None = None, **args)

Save the individual parameters in a torch format.

Parameters:

pathstr: The logs’ path.
idxlist [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:

NotADirectoryError: if parent directory of path does not exist.

Examples

Save the individual parameters of the twenty first subjects.

>>> from leaspy import AlgorithmSettings, Data, Leaspy
>>> 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)