8.1.5.3. pelicun.model.demand_model

DemandModel object and associated methods.

Classes

DemandModel(assessment)

Manages demand information used in assessments.

class pelicun.model.demand_model.DemandModel(assessment: AssessmentBase)[source]

Manages demand information used in assessments.

Parameters:

marginal_params: DataFrame: Available after the model has been calibrated or calibration data has been imported. Defines the marginal distribution of each demand variable.
correlation: DataFrame: Available after the model has been calibrated or calibration data has been imported. Defines the correlation between the demand variables in standard normal space. That is, the variables are sampled in standard normal space and then transformed into the space of their respective distributions and the correlation matrix corresponds to the space where they are sampled.
empirical_data: DataFrame: Available after the model has been calibrated or calibration data has been imported. It provides an empirical dataset for the demand variables that are modeled with an empirical distribution.
sample: DataFrame: Available after a sample has been generated. Demand variables are listed in columns and each row provides an independent realization of the joint demand distribution.
units: Series: Available after any demand data has been loaded. The index identifies the demand variables and the values provide the unit for each variable.
calibrated: bool: Signifies whether the DemandModel object has been calibrated.

calibrate_model(config: dict) → None[source]

Calibrate a demand model to describe the raw demand data.

The raw data shall be parsed first to ensure that it follows the schema expected by this method. The calibration settings define the characteristics of the multivariate distribution that is fit to the raw data.

Parameters:

config: dict: A dictionary, typically read from a JSON file, that specifies the distribution family, truncation and censoring limits, and other settings for the calibration.

clone_demands(demand_cloning: dict) → None[source]

Clone demands.

Copies over columns of the original demand sample and assigns given names to them. The columns to be copied over and the names to be assigned to the copies are defined as the keys and values of the demand_cloning dictionary. The method modifies sample inplace.

Parameters:

demand_cloning: dict: Keys correspond to the columns of the original sample to be copied over and the values correspond to the intended names for the copies. Caution: It’s possible to define a dictionary with duplicate keys, and Python will just keep the last entry without warning. Users need to be careful enough to avoid duplicate keys, because we can’t validate them. E.g.: x = {‘1’: 1.00, ‘1’: 2.00} results in x={‘1’: 2.00}.

Raises:

ValueError: In multiple instances of invalid demand_cloning entries.

estimate_RID(demands: DataFrame | Series, params: dict, method: str = 'FEMA P58') → DataFrame[source]

Estimate residual inter-story drift (RID).

Estimates residual inter-story drift (RID) realizations based on peak inter-story drift (PID) and other demand parameters using specified methods.

This method calculates RID based on the peak inter-story drift provided in the demands DataFrame and parameters such as yield drift specified in the params dictionary. The calculation adheres to the FEMA P-58 methodology, which includes conditions for different ranges of drift.

Parameters:

demands: DataFrame: A DataFrame containing samples of demands, specifically peak inter-story drift (PID) values for various location-direction pairs required for the estimation method.
params: dict: A dictionary containing parameters required for the estimation method, such as ‘yield_drift’, which is the drift at which yielding is expected to occur.
method: str, optional: The method used to estimate the RID values. Currently, only ‘FEMA P58’ is implemented. Defaults to ‘FEMA P58’.

Returns:

DataFrame: A DataFrame containing the estimated residual inter-story drift (RID) realizations, indexed and structured similarly to the input demands DataFrame.

Raises:

ValueError: Raises a ValueError if an unrecognized method is provided or required parameters are missing in the params dictionary.

Notes

The FEMA P-58 estimation approach divides the drift into three domains, with different transformation rules for each. Additional stochastic variation is introduced to nonzero RID values to model the inherent uncertainty. The method ensures that the RID values do not exceed the corresponding PID values.

estimate_RID_and_adjust_sample(params: dict, method: str = 'FEMA P58') → None[source]

Estimate residual inter-story drift (RID) and modifies sample.

Uses self.estimate_RID and adjusts the demand sample. See the docstring of the estimate_RID method for details.

Parameters:

params: dict: A dictionary containing parameters required for the estimation method, such as ‘yield_drift’, which is the drift at which yielding is expected to occur.
method: str, optional: The method used to estimate the RID values. Currently, only ‘FEMA P58’ is implemented. Defaults to ‘FEMA P58’.

Raises:

ValueError: If the method is called before a sample is generated.

expand_sample(label: str, value: float | ndarray, unit: str, location: str = '0', direction: str = '1') → None[source]

Add an extra column to the demand sample.

The column contains repeated instances of value, is accessed via the multi-index (label-location-direction), and has units of unit.

Parameters:

label: str: Label to use to extend the MultiIndex of the demand sample.
value: float | np.ndarray: Values to add to the rows of the additional column.
unit: str: Unit that corresponds to the additional column.
location: str, optional: Optional location, defaults to 0.
direction: str, optional: Optional direction, defaults to 1.

Raises:

ValueError: If the method is called before a sample is generated.
ValueError: If value is a numpy array of incorrect shape.

generate_sample(config: dict) → None[source]

Generate the demand sample.

Generates a sample of random variables (RVs) based on the specified configuration for demand modeling.

This method utilizes the current settings for marginal distribution parameters to generate a sample of demand variables. The configuration can specify details such as the sample size, whether to preserve the order of raw data, and whether to apply demand cloning. The generated sample is stored internally and can be used for subsequent analysis.

Parameters:

config: dict: A dictionary containing configuration options for the sample generation. Key options include: * ‘SampleSize’: The number of samples to generate. * ‘PreserveRawOrder’: Boolean indicating whether to preserve the order of the raw data. Defaults to False. * ‘DemandCloning’: Specifies if and how demand cloning should be applied. Can be a boolean or a detailed configuration.

Raises:

ValueError: If model parameters are not loaded or specified before attempting to generate a sample.

Notes

The function is responsible for the creation of random variables based on the distribution parameters specified in marginal_params. It ensures that the sample is properly indexed and sorted according to type, location, and direction. It also handles the configuration of demand cloning if specified, which is a method to artificially augment the variability in the sample based on existing realizations.

Examples

>>> config = {
        'SampleSize': 1000,
        'PreserveRawOrder': True,
        'DemandCloning': False
    }
>>> model.generate_sample(config)
# This will generate 1000 realizations of demand variables
# with the specified configuration.

load_model(data_source: str | dict) → None[source]

Load the model that describes demands on the asset.

Parameters:

data_source: string or dict: If string, the data_source is a file prefix (<prefix> in the following description) that identifies the following files: <prefix>_marginals.csv, <prefix>_empirical.csv, <prefix>_correlation.csv. If dict, the data source is a dictionary with the following optional keys: ‘marginals’, ‘empirical’, and ‘correlation’. The value under each key shall be a DataFrame.

Raises:

TypeError: If the data source type is invalid.

load_sample(filepath: str | DataFrame) → None[source]

Load demand sample data and parse it.

Besides parsing the sample, the method also reads and saves the units specified for each demand variable. If no units are specified, base units are assumed.

Parameters:

filepath: string or DataFrame: Location of the file with the demand sample.

save_model(file_prefix: str) → None[source]: Save parameters of the demand model to a set of csv files.

save_sample(filepath: None = None, *, save_units: bool = False) → tuple[DataFrame, Series] | DataFrame[source]

save_sample(filepath: str, *, save_units: bool = False) → None

Save demand sample to a csv file or return it in a DataFrame.

Returns:

None or tuple: If filepath is specified, the function saves the demand sample to a CSV file and returns None. If filepath is not specified, it returns the DataFrame containing the demand sample. If save_units is True, it returns a tuple of the DataFrame and a Series containing the units.