Damage Probability Analysis#

The damage probability analysis module provides functionality for analyzing damage probabilities through fragility and vulnerability calculations.

Class Diagram#

classDiagram
    class BaseDamageProbabilityAnalysis {
        +prob_ds_file_path: str
        +wind_scale_lines: List[int]
        +prob_damage_states: dict
        +wind_speed: np.ndarray
        +flood_depth: np.ndarray
        +damage_state: np.ndarray
        +datasets_loaded: bool
        +load_prob_damage_states()
        +load_wind_speed()
        +load_flood_depth()
        +load_damage_state()
    }

    class VulnerabilityCalculator {
        +building_type: int
        +resistance_type: int
        +expected_damage_ratio: np.ndarray
        +vulnerability_curve: Dict
        +calculate_vulnerability_curve()
        +plot_vulnerability_curve()
    }

    class FragilityCalculator {
        +fragility_curves: Dict
        +ds_thresholds: List[float]
        +line_styles: List[str]
        +calculate_fragility_curves()
        +plot_fragility_curves()
    }

    class DamageProbabilityAnalysis {
        +output_dir: str
        +generate_analysis()
        +save_analysis_results()
        +plot_analysis_results()
    }

    BaseDamageProbabilityAnalysis <|-- VulnerabilityCalculator
    VulnerabilityCalculator <|-- FragilityCalculator
    FragilityCalculator <|-- DamageProbabilityAnalysis

Base Classes#

base #

Classes:

Name	Description
`BaseDamageProbabilityAnalysis`	A class used as the base for damage probability analysis.

BaseDamageProbabilityAnalysis `dataclass` #

BaseDamageProbabilityAnalysis(
    prob_ds_file_path: str = join(
        OUTPUTS_PATH,
        f"ProbDS_wfd_dictMaxIter{NUM_OF_ITERATIONS}_aggregated.pkl",
    ),
    wind_scale_lines: List[int] = (
        lambda: [74, 95, 110, 130, 157]
    )(),
    datasets_loaded: bool = False,
)

A class used as the base for damage probability analysis.

Attributes:

Name	Type	Description
`prob_damage_states`	`ndarray`	Probability of damage states, loaded from file
`wind_speed`	`ndarray`	Wind speed table
`flood_depth`	`ndarray`	Flood depth table
`damage_state`	`ndarray`	Damage state definitions

Methods:

Name	Description
`load_damage_state`	Load damage state definitions
`load_flood_depth`	Load flood depth table
`load_prob_damage_states`	Load probability of damage states from the provided file path
`load_wind_speed`	Load wind speed table

load_damage_state #

load_damage_state(path: str = 'Inputs/DamageState.json')

Load damage state definitions

Parameters:

Name	Type	Description	Default
`path`	`str`	Path to the damage state definitions file	`'Inputs/DamageState.json'`

load_flood_depth #

load_flood_depth(path: str = 'Inputs/FloodDepth.json')

Load flood depth table

Parameters:

Name	Type	Description	Default
`path`	`str`	Path to the flood depth table file	`'Inputs/FloodDepth.json'`

load_prob_damage_states #

load_prob_damage_states()

Load probability of damage states from the provided file path

load_wind_speed #

load_wind_speed(path: str = 'Inputs/WindSpeed.json')

Load wind speed table

Parameters:

Name	Type	Description	Default
`path`	`str`	Path to the wind speed table file	`'Inputs/WindSpeed.json'`

Fragility Calculator#

fragility_calculator #

Classes:

Name	Description
`FragilityCalculator`	Class for calculating fragility curves based on damage probability data.

FragilityCalculator `dataclass` #

FragilityCalculator(
    prob_ds_file_path: str = join(
        OUTPUTS_PATH,
        f"ProbDS_wfd_dictMaxIter{NUM_OF_ITERATIONS}_aggregated.pkl",
    ),
    wind_scale_lines: List[int] = (
        lambda: [74, 95, 110, 130, 157]
    )(),
    datasets_loaded: bool = False,
    building_type: int = 1,
    resistance_type: int = 1,
    vulnerability_curve: Dict[str, ndarray] = dict(),
    fragility_curves: Dict[str, ndarray] = dict(),
    ds_thresholds: List[float] = (
        lambda: [0.03, 0.09, 0.22, 0.46]
    )(),
    line_styles: List[str] = (
        lambda: [
            "--",
            "-o",
            "-+",
            "-*",
            "-x",
            "-s",
            "-d",
            "-^",
            "-v",
            "-p",
            "-h",
        ]
    )(),
)

Bases: VulnerabilityCalculator

Class for calculating fragility curves based on damage probability data.

Methods:

Name	Description
`calculate_fragility_curves`	Calculate fragility curves for different damage states
`plot_fragility_curves`	Plot the fragility curves

calculate_fragility_curves #

calculate_fragility_curves() -> Dict[str, ndarray]

Calculate fragility curves for different damage states.

Fragility curves represent the probability of exceeding a certain damage state given a specific wind speed.

KNOWN DISCREPANCY (documented, not yet changed -- fix in a future release): The values returned here are NOT exceedance probabilities. For each damage state this method averages the cumulative distribution across the band of damage-ratio bins between two thresholds and subtracts the result from one, whereas P(delta >= t) is one minus the CDF evaluated at the single bin just below t. The two agree only when the CDF is nearly constant across the band.

For a concentrated distribution they diverge badly. Example, library
ProbDS_cwfd_MaxIter3000_V2 at (m=4, c=1): at the deepest flood bin the damage
ratio is a point mass at 0.72, so P(delta >= 0.46) = 1.0, but this method
returns 0.25 -- the terminal band spans 24 bins of which 17 sit above the mass.
On the wind margin of the same pair the error reaches 0.56 in absolute
probability at 185 mph for the >=46% state.

The correct form is simply the mass at or above the threshold:
    exceedance = prob[:, ratios >= threshold].sum(axis=1)
Callers needing exceedance probabilities should use that directly; see
`Loss Estimates/figure_reproduction/make_fragility_curves.py`, which generates
the published fragility figure.

Outputs

None beyond the returned value.

Returns:

Type	Description
`Dict[str, ndarray]`	Dict[str, np.ndarray]: Fragility curve arrays keyed by wind speed and damage state.

plot_fragility_curves #

plot_fragility_curves(
    save_path: Optional[str] = None,
) -> Figure

Plot the fragility curves

Parameters:

Name	Type	Description	Default
`save_path`	`str`	Path to save the plot	`None`

Outputs

Creates a matplotlib figure and optionally writes it to save_path.

Returns:

Type	Description
`Figure`	plt.Figure: The generated fragility curve figure.

Main Analysis#

main #

Classes:

Name	Description
`DamageProbabilityAnalysis`	Main class for damage probability analysis. Combines vulnerability and fragility calculations.