search

GFDRR / rdl-standard

The Risk Data Library Standard (RDLS) is an open data standard to make it easier to work with disaster and climate risk data. It provides a common description of the data used and produced in risk assessments, including hazard, exposure, vulnerability, and modelled loss, or impact, data.
https://docs.riskdatalibrary.org/
Creative Commons Attribution Share Alike 4.0 International
13 stars 1 forks source link

[Proposal] Vulnerability function object #78

Closed odscrachel closed 1 year ago

odscrachel commented 1 year ago

What is your proposed change?

Create a function object to hold the function description fields within the vulnerability component. This object is unique to vulnerability. This will include creating codelists for all four of the fields in this object. Spreadsheet link

Title Field name Description Type Codelist
Vulnerability function function The details of the function used to calculate the impact of the hazard. object
Impact function type function.type The type of function used to calculate the impact of the hazard for the given exposure values. string fragility, vulnerability, damage-to-loss
Impact function approach function.approach The approach the impact function is based upon. string empirical, analytical, judgement, hybrid
Impact mathematical function function.mathematical The type of mathematical function used to calculate the impact values. string parametric, bespoke
Impact relationships type function.relationship The type of function relationships used to calculate the impact values. string mathematical function, discrete values
stufraser1 commented 1 year ago

Corrected function.approach codelist

stufraser1 commented 1 year ago

Following discussion at #83

We need to include information on fragility functions and damage-to-loss functions under the vulnerability object.

Options:

  1. Using THREE objects: vulnerability.function.vulnerability, vulnerability.function.damagetoloss and vulnerability.function.fragility, under which the distinct fields would sit, or
  2. Nesting the optional fields for vulnerability, fragility, and damage to loss function under vulnerability.function and using vulnerability.function.type to denote which is being used
stufraser1 commented 1 year ago

Proposal, where all fields sit under the vulnerability.function object:

Title Field name Description Type Codelist
Vulnerability function function The details of the function used to calculate the impact of the hazard. object
Impact function type function.type The type of function used to calculate the impact of the hazard for the given exposure values. string fragility, vulnerability, damage-to-loss, engineering demand parameter
Impact function approach function.approach The approach the impact function is based upon. string empirical, analytical, judgement, hybrid
Impact mathematical function function.mathematical The type of mathematical function used to calculate the impact values. string parametric, bespoke
Impact relationships type function.relationship The type of function relationships used to calculate the impact values. string mathematical function, discrete values
Damage Scale Name function.damage_scale_name Name of the damage scale used in the damage-to-loss function or fragility function. string e.g., Crowley et al 2004
Damage States Name function.damage_states_name Names of the damage states listed in a Damage Scale or used in a Fragility function. The number of damage states can be derived from this list. string E.g., minor damage; moderate damage; severe damage; collapse.
Engineering Demand Parameter Name function.edp_name The name of the engineering demand parameter string Park-Ang damage index, Peak floor acceleration, Roof drift ratio, Maximum inter-storey drift ratio, Interstorey drift ratio for storey i, Demand to capacity ratio.

Original documentation provided code lists for edp_name and damage_scale_name

Damage states and damage scale names can actually be used to describe the curves included in fragility functions, as well as in a damage-to-loss ratio. So in the end we're not adding many new fields.

EDP included for completeness, for analytical curves that focus on how structures respond to hazard parameter, as included in original schema.

Other fields included in the original schema are handled under the referencedBy and vulnerability.impact objects

matamadio commented 1 year ago

Proposal makes sense; if understood correctly, not all function.type relates to all other fields, e.g. function.damage_scale_name only applies when function.type = fragility or damage-to-loss.

This ambiguity could be solved creating (4) separate objects for each function.type, each having only its appropriate attributes.

stufraser1 commented 1 year ago

Proposal makes sense; if understood correctly, not all function.type relates to all other fields, e.g. function.damage_scale_name only applies when function.type = fragility or damage-to-loss.

Yes that's correct

This ambiguity could be solved creating (4) separate objects for each function.type, each having only its appropriate attributes.

But given I've only added three new fields, and I think this is all that is needed, perhaps its better to keep in one vulnerability.function object to prevent over-nesting. Over to you @odscjen !

johcarter commented 1 year ago

Just to check: can you have both a fragility function and a damage-to-loss function in the same vulnerability data object? I think they often come together.

stufraser1 commented 1 year ago

Yes they need to and would be possible in the proposed solutions

From: johcarter @.> Sent: Thursday, June 15, 2023 4:25:37 PM To: GFDRR/rdl-standard @.> Cc: Stuart Fraser @.>; Comment @.> Subject: Re: [GFDRR/rdl-standard] [Proposal] Vulnerability function object (Issue #78)

Just to check: can you have both a fragility function and a damage-to-loss function in the same vulnerability data object? I think they often come together.

— Reply to this email directly, view it on GitHubhttps://github.com/GFDRR/rdl-standard/issues/78#issuecomment-1593285687, or unsubscribehttps://github.com/notifications/unsubscribe-auth/AC7PNYTMFWZQTGKDDUWACJ3XLMSPDANCNFSM6AAAAAAYN3XJFI. You are receiving this because you commented.Message ID: @.***>

odscjen commented 1 year ago

sorry I commented on #83 before properly catching up on this issue.

Splitting into 3 separate objects made sense in #59 because you won't get an event that combines the 3 analysis types. In this case if more than one function type could be contained in the data then that might be unnecessary nesting and duplication of fields.

@stufraser1 could you clarify which fields are appropriate to which of the 3 function types? Or more importantly which fields are only appropriate to one of them?

stufraser1 commented 1 year ago

Revised proposal, where we have four objects under the vulnerability top level object:

Title Field name Description Type Codelist
Vulnerability function vulnerability.vulnerability_function An object to describe the details of a vulnerability function used to calculate the impact of the hazard. object
Impact function approach vulnerability.vulnerability_function.approach The approach the impact function is based upon. string empirical, analytical, judgement, hybrid
Impact mathematical function vulnerability.vulnerability_function.mathematical The type of mathematical function used to calculate the impact values. string parametric, bespoke
Impact relationships type vulnerability.vulnerability_function.relationship The type of function relationships used to calculate the impact values. string mathematical function, discrete values
Fragility function vulnerability.fragility_function An object to describe the details of a fragility function used to calculate the impact of the hazard. object
Impact function approach vulnerability.fragility_function.approach The approach the impact function is based upon. string empirical, analytical, judgement, hybrid
Impact mathematical function vulnerability.fragility_function.mathematical The type of mathematical function used to calculate the impact values. string parametric, bespoke
Impact relationships type vulnerability.fragility_function.relationship The type of function relationships used to calculate the impact values. string mathematical function, discrete values
Damage Scale Name vulnerability.fragility_function.damage_scale_name Name of the damage scale used in the damage-to-loss function or fragility function. string e.g., Crowley et al 2004
Damage States Name vulnerability.fragility_function.damage_states_name Names of the damage states listed in a Damage Scale or used in a Fragility function. The number of damage states can be derived from this list. string E.g., minor damage; moderate damage; severe damage; collapse.
Damage-to-loss function vulnerability.damagetoloss_function An object to describe the details of a damage-to-loss function (or damage-to-loss model) used to calculate the impact of the hazard in conjunction with a fragility function. object
Impact function approach vulnerability.damagetoloss_function.approach The approach the impact function is based upon. string empirical, analytical, judgement, hybrid
Impact mathematical function vulnerability.damagetoloss_function.mathematical The type of mathematical function used to calculate the impact values. string parametric, bespoke
Impact relationships type vulnerability.damagetoloss_function.relationship The type of function relationships used to calculate the impact values. string mathematical function, discrete values
Damage Scale Name vulnerability.damagetoloss_function.damage_scale_name Name of the damage scale used in the damage-to-loss function or fragility function. string e.g., Crowley et al 2004
Damage States Name vulnerability.damagetoloss_function.damage_states_name Names of the damage states listed in a Damage Scale or used in a Fragility function. The number of damage states can be derived from this list. string E.g., minor damage; moderate damage; severe damage; collapse.
Engineering demand function vulnerability.engdemand_function An object to describe the details of an engineering damand function used to calculate the impact of the hazard. object
Engineering Demand Parameter Name vulnerability.engdemand_function.edp_name The name of the engineering demand parameter string Park-Ang damage index, Peak floor acceleration, Roof drift ratio, Maximum inter-storey drift ratio, Interstorey drift ratio for storey i, Demand to capacity ratio.
Impact function approach vulnerability.engdemand_function.approach The approach the impact function is based upon. string empirical, analytical, judgement, hybrid
Impact mathematical function vulnerability.engdemand_function.mathematical The type of mathematical function used to calculate the impact values. string parametric, bespoke
Impact relationships type vulnerability.engdemand_function.relationship The type of function relationships used to calculate the impact values. string mathematical function, discrete values

Original documentation provided code lists for edp_name and damage_scale_name

Other fields included in the original schema are handled under the referencedBy and vulnerability.impact objects

Repeated .approach, .mathematical, and .relationship in each object, as we may have a dataset that uses >1 function, which could have been developed with different approaches.

Removed from previous proposal as this is described by the object(s) included: Title Field name Description Type Codelist
Impact function type function.type The type of function used to calculate the impact of the hazard for the given exposure values. string fragility, vulnerability, damage-to-loss, engineering demand parameter

Using separate damage-to-loss and fragility objects allows to include both relationships which may have been used together in the analysis - in which case, they would have matching damage scale name.

Suggestion -- could we combine two fields into one as below? Title Field name Description Type Codelist
Impact mathematical function function.xxx.mathematical The type of mathematical function used to calculate the impact values. string parametric, bespoke
Impact relationships type function.xxx.relationship The type of function relationships used to calculate the impact values. string mathematical function, discrete values

into one field, which houses the codelist to distinguish the mathematical function type?

Title Field name Description Type Codelist
Impact relationships type function.xxx.relationship The type of function relationships used to calculate the impact values. string mathematical function (parametric), mathematical function (bespoke), discrete values
odscjen commented 1 year ago

This makes sense and if more than one function type is possible then I think this proposal is the way to go.

Suggestion -- could we combine two fields into one as below?

Yes that works.

Just some minor suggestions to change some names to match the rough style we've been following:

Also rather than repeat _function in the names of the upper level objects we could nest them all within a functions object?

Original documentation provided code lists for edp_name and damage_scale_name

I'm assuming that table 4.17 Damage Scale Reference is what you're referring to as the code list for damange_scale_name? I couldn't see a clear codelist for edp_name other than a cell in table 4.20 which says "Possible entries include:... In both of these cases we'll need to decide if these are open or closed codelists and if they are sufficient?

stufraser1 commented 1 year ago

Revised proposal, after https://github.com/GFDRR/rdl-standard/issues/78#issuecomment-1598612121:

Title Field name Description Type Codelist
Functions object vulnerability.functions An object to describe the details of functions available under the top-level vulnerability object. object
Vulnerability function functions.vulnerability An object to describe the details of a vulnerability function used to calculate the impact of the hazard. object
Impact function approach functions.vulnerability.approach The approach the impact function is based upon. string empirical, analytical, judgement, hybrid
Impact relationships type functions.vulnerability.relationship The type of function relationships used to calculate the impact values. string mathematical function (parametric), mathematical function (bespoke), discrete values
Fragility function functions.fragility An object to describe the details of a fragility function used to calculate the impact of the hazard. object
Impact function approach functions.fragility.approach The approach the impact function is based upon. string empirical, analytical, judgement, hybrid
Impact relationships type functions.fragility.relationship The type of function relationships used to calculate the impact values. string mathematical function, discrete values
Damage Scale Name functions.fragility.damage_scale_name Name of the damage scale used in the damage-to-loss function or fragility function. string e.g., Crowley et al 2004
Damage States Name functions.fragility.damage_states_name Names of the damage states listed in a Damage Scale or used in a Fragility function. The number of damage states can be derived from this list. string E.g., minor damage; moderate damage; severe damage; collapse.
Damage-to-loss function functions.damage_to_loss An object to describe the details of a damage-to-loss function (or damage-to-loss model) used to calculate the impact of the hazard in conjunction with a fragility function. object
Impact function approach functions.damage_to_loss.approach The approach the impact function is based upon. string empirical, analytical, judgement, hybrid
Impact relationships type functions.damage_to_loss.relationship The type of function relationships used to calculate the impact values. string mathematical function (parametric), mathematical function (bespoke), discrete values
Damage Scale Name functions.damage_to_loss.damage_scale_name Name of the damage scale used in the damage-to-loss function or fragility function. string e.g., Crowley et al 2004
Damage States Name functions.damage_to_loss.damage_states_name Names of the damage states listed in a Damage Scale or used in a Fragility function. The number of damage states can be derived from this list. string E.g., minor damage; moderate damage; severe damage; collapse.
Engineering demand function functions.engineering_demand An object to describe the details of an engineering damand function used to calculate the impact of the hazard. object
Engineering Demand Parameter functions.engineering_demand.parameter The name of the engineering demand parameter string Park-Ang damage index, Peak floor acceleration, Roof drift ratio, Maximum inter-storey drift ratio, Interstorey drift ratio for storey i, Demand to capacity ratio.
Impact function approach functions.engineering_demand.approach The approach the impact function is based upon. string empirical, analytical, judgement, hybrid
Impact relationships type functions.engineering_demand.relationship The type of function relationships used to calculate the impact values. string mathematical function (parametric), mathematical function (bespoke), discrete values
stufraser1 commented 1 year ago

I'm assuming that table 4.17 Damage Scale Reference is what you're referring to as the code list for damage_scale_name?

Yes, but should be open codelist as there will be new scale names

I couldn't see a clear codelist for edp_name other than a cell in table 4.20 which says "Possible entries include:... In both of these cases we'll need to decide if these are open or closed codelists and if they are sufficient?

Yes, this should be open codelist

odscjen commented 1 year ago

Great, this sounds like it's ready then :)

odscjen commented 1 year ago

Just a couple of clarifications needed from you @stufraser1 now that I'm actually coding this up:

  1. for functions.damage_to_loss.damage_states_name - you've indicated 'string' as the type but the description reads as though multiple names can be provided. Should this be singular or a plural array?
  2. functions.fragility.relationship - the codes you've listed are "mathematical function, discrete values", is there a particular reason they can't be "mathematical function (parametric), mathematical function (bespoke), discrete values" as in the other relationship fields?
  3. functions.engineering_demand.parameter - is this a closed or open codelist, i.e. are the codes you've listed exhaustive?
stufraser1 commented 1 year ago
  1. Plural array
  2. This can be same as given in the other fields
  3. Open

    From: odscjen @.> Sent: Tuesday, June 27, 2023 2:45:24 PM To: GFDRR/rdl-standard @.> Cc: Stuart Fraser @.>; Mention @.> Subject: Re: [GFDRR/rdl-standard] [Proposal] Vulnerability function object (Issue #78)

Just a couple of clarifications needed from you @stufraser1https://github.com/stufraser1 now that I'm actually coding this up:

  1. for functions.damage_to_loss.damage_states_name - you've indicated 'string' as the type but the description reads as though multiple names can be provided. Should this be singular or a plural array?
  2. functions.fragility.relationship - the codes you've listed are "mathematical function, discrete values", is there a particular reason they can't be "mathematical function (parametric), mathematical function (bespoke), discrete values" as in the other relationship fields?
  3. functions.engineering_demand.parameter - is this a closed or open codelist, i.e. are the codes you've listed exhaustive?

— Reply to this email directly, view it on GitHubhttps://github.com/GFDRR/rdl-standard/issues/78#issuecomment-1609538326, or unsubscribehttps://github.com/notifications/unsubscribe-auth/AC7PNYQPUSPHZTEB23R24YDXNLPXJANCNFSM6AAAAAAYN3XJFI. You are receiving this because you were mentioned.Message ID: @.***>

stufraser1 commented 1 year ago

function_approach.csv

Code,Label,Definition empirical,Empirical survey,Data or function generated through regression analysis of historical loss data. analytical,Analytical,Data or function generated using numerical or computational models to simulate the response of a structure under increasing hazard intensities. judgement,Judgement,Data or function generated through the elicitation of expert opinion (heuristic). hybrid,Hybrid,Data or function generated using data gathered from the international literature.

stufraser1 commented 1 year ago

edp_name.csv

Code,Label,Definition PA_dmg_index,Park-Ang damage index,The Park-Ang damage index (Park et al., 1987) accounts for the effect of maximum deformation and cyclic loads. peak_floor_acc,Peak floor acceleration,The maximum acceleration at any floor within a structure during an earthquake. roof_drift,Roof drift ratio,The ratio of the peak lateral roof displacement to the building height. max_interstorey_drift_ratio,Maximum inter-storey drift ratio,"The maximum interstorey drift ratio across all floors." interstorey_drift_ratio_i,Interstorey drift ratio for storey i,"The peak (over time) interstorey drift ratio, and is calculated as the largest difference between the lateral displacements of two adjacent floors, divided by the height of the storey." demand_capacity_ratio,Demand to capacity ratio,"The ratio between the external actions applied to the structure (demand) over the ability of the structure to carry the imposed actions (capacity). A D/C ratio >1 indicates failure."

stufraser1 commented 1 year ago

relationship_type.csv

Code,Label,Definition math_param,Mathematical function (parametric),"A relationship between structural parameters and expected damage, often based on probabilistic models, such as log-normal or beta distribution. They can account for uncertainties and variability in both the seismic hazard and building attributes." math_bespoke,Mathematical function (bespoke),"A customized or tailored mathematical function that expresses the relationship between the characteristics of a particular type of structure and its vulnerability to hazard, derived through detailed analysis of that structural type." discrete,Discrete values,"A function that assigns discrete damage states to specific ranges or categories of parameters, such as construction material, structural system or building age. Each range or category is associated with a probability of exceeding a particular damage state."

stufraser1 commented 1 year ago

damage_scale_name.csv

Code,Label,Definition EMS-98,EMS-98 (Grünthal, 1998),"Scale for earthquake hazard, RC and Masonry construction, with 5 damage states." HAZUS-MH_MR4,HAZUS-MH MR4 (FEMA, 2003),"Scale for earthquake hazard, US building types, with 5 damage states." Vision_2000,Vision 2000 (SEAOC, 1995),"Scale for earthquake hazard, RC and Masonry construction, with 5 damage states." FEMA_356,FEMA 356 (FEMA, 2000),"Scale for earthquake hazard, RC and Masonry construction, with 4 damage states." Milutinovic_Trendafiloski_2003,Milutinovic and Trendafiloski (2003),"Scale for earthquake hazard, RC and Masonry construction, with 6 damage states." Blong_2003,Blong (2003),"Scale for earthquake hazard, RC and Masonry construction, with 6 damage states." HRC,HRC (Rossetto and Elnashai, 2003),"Scale for earthquake hazard, RC construction, with 7 damage states." Crowley_2004,Crowley et al (2004),"Scale for earthquake and landslide hazards, RC construction, with 4 damage states." Lang_Bachmann_2004,Lang and Bachmann (2004),"Scale for earthquake and landslide hazards, masonry construction, with 6 damage states." GNDT_2010,GNDT 2010,"Scale for earthquake hazard, Italian building types, with 4 damage states." JapanCO_2013,Japan Cabinet Office (2013),"Scale for tsunami hazard, RC masonry and timber construction, with 6 damage states."
EEFIT_2006,EEFIT (2006),"Scale for tsunami hazard, RC construction, with 5 damage states." Fraser_2013,Fraser et al. (2013),"Scale for tsunami hazard, RC masonry and timber construction, with 5 damage states."