[Proposal] Vulnerability function object

[odscrachel]

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]

Corrected function.approach codelist

[stufraser1]

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]

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]

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]

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]

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]

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 GitHub<#78 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AC7PNYTMFWZQTGKDDUWACJ3XLMSPDANCNFSM6AAAAAAYN3XJFI>. You are receiving this because you commented.Message ID: ***@***.***>

[odscjen]

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]

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]

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:

• damagetoloss_function -> damage_to_loss_function
• engdemand_function -> engineering_demand_function
• edp_name -> parameter (it's already within the engineering_demand_function so we don't need to repeat the 'ed' part and the description will make it clear it's a name.

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]

Revised proposal, after #78 (comment):

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]

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]

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

[odscjen]

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]

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 @stufraser1<https://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 GitHub<#78 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AC7PNYQPUSPHZTEB23R24YDXNLPXJANCNFSM6AAAAAAYN3XJFI>. You are receiving this because you were mentioned.Message ID: ***@***.***>

[stufraser1]

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]

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]

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]

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."