Update schema reference #120

duncandewhurst · 2023-07-04T03:00:11Z

Related issues

[Docs update] Restructuring the docs #43

Description

This PR updates the reference documentation (formerly known as the data model section). The schema tables are now generated from the schema as part of the Sphinx build so they will always be up-to-date and manage.py includes a pre-commit script to update the sub-schema and codelist reference sections.

The diagrams, explanatory text and examples will need updating once the schema updates are done, but I don't think that should be a blocker to getting this PR merged.

I've temporarily commented out the code in manage.py that adds the lists of references to the sub-schema reference and codelist reference as this requires some more work due to the structure of the RDLS schema and I understand that finishing off the schema changes is the priority.

Merge checklist

Update the changelog (style guide)
Run ./manage.py pre-commit

duncandewhurst · 2023-07-04T06:20:21Z

Preview: https://rdl-standard.readthedocs.io/en/schema-reference/reference/

odscjen

I started correcting some language and then realised it was pointless as most of the component pages are going to need rewritten anyway as they are now incorrect and refer to fields etc that have been removed/renamed/resituated.

So other than that it all looks fine

odscjen · 2023-07-04T13:13:11Z

docs/reference/codelists.md

-### risk_data_type
+### hazard_type
+
+The RDLS offers a classification of hazards that are more often required in disaster risk assessments, based on the review and mapping of existing alternative definitions into one consistent framework.


Just a question about this bit, do we need to write explanations for all of the codelists and include them in this?

I don't think so since the codelist are linked from the schema tables, which provide the context of what they are used for. I just copied this text from the old hazard.md page in order to preserve it.

docs/reference/schema.md

odscjen · 2023-07-04T13:17:55Z

docs/reference/schema.md

+
+When the scenario modelled refers to a specific period of time, this can be specified in terms of dates, period span and reference year. For example, an observed flood event that occurred from 1.10.2009 (time start) to 3.10.2009 (time end), spanning over 3 days (time span). When precise time collocation is unknown or not applicable, a general reference date such as "2009" is used to identify events (time year). This is also useful to specify future scenario, e.g. time year: 2050.
+
+When instead the hazard scenario is represented in probabilistic terms, the occurrence probability (frequency distribution) of hazard can be expressed in different ways. The most common way to communicate this is the "return period", expressed as the number of years after which a given hazard intensity could occur again: RP 100 indicates that that event has a probability of once in 100 years. This attribute can indicate individual layer frequency (RP100) or a range of frequencies for a collection of layers (RP10-100) The probability of occurrence is usually calculated on the basis of a reference period that provides observations: this period can be specified by start date, end date and time span. For example, an analysis of earthquake frequency based on seismic observations from 1934 (occurrence time start) to 2001 (occurrence time end), for a total count of 66 years (occurrence time span).


This whole paragraph will need rewritten I think as the way occurence is modelled in the updated schema is very different

Agreed, but, as mentioned in the issue description, I think updating the text is best left until the schema updates are done.

docs/reference/schema.md

odscjen · 2023-07-04T13:21:32Z

docs/reference/schema.md

+      }
+```
+
+The main features of an exposure dataset are specified by the **exposure model** attributes.


This whole bit will also need rewritten as it no longer matches the updated data model

Agreed, but, as mentioned in the issue description, I think updating the text is best left until the schema updates are done.

Co-authored-by: odscjen <[email protected]>

duncandewhurst · 2023-07-04T22:33:17Z

I started correcting some language and then realised it was pointless as most of the component pages are going to need rewritten anyway as they are now incorrect and refer to fields etc that have been removed/renamed/resituated.

Yep, as I mentioned in PR description, the diagrams, explanatory text and examples will need updating once the schema updates are done, but I don't think that should be a blocker to getting this PR merged.

@matamadio @stufraser1, over to you to review. Per the above, there's no need to review the text on schema.md from line 13 onwards as I copy-pasted it from the old data model documentation pages. You can preview the built documentation here: https://rdl-standard.readthedocs.io/en/schema-reference/reference/

stufraser1

Acknowledging text needs to be updated per comments made already, we can accept this. The interactive browser version is helpful.

We also need to update the examples for each section to make a range of examples available with the JSON implementation of the metadata rather than tabulated values. This could include snippet of JSON in the documentation, or a link out to the metadata file if larger.

duncandewhurst · 2023-07-05T21:04:18Z

All sounds good. +1 to using JSON snippets and full files for examples. I'll merge the PR and copy your comment to #43.

duncandewhurst added 11 commits June 29, 2023 08:06

Schema reference docs initial draft

0b9f4fd

Merge branch 'dev' into schema-reference

d41f571

docs/data_model: Integrate content from general.md to schema.md

e58076a

docs/data_model: Move hazard.md content to schema.md and codelists.md

427c3b2

docs/data_model: Move exposure.md content to schema.md

d5c711d

docs/data_model" Move vulnerability.md content to schema.md

9d26184

docs/data_model: Move content from loss.md to schema.md

e0be582

docs/data_model: Refactor

d95a6ae

docs/data_model/schema.md: Add sub-schema reference, update pre-commit

00865c6

docs: Rename data_model to reference

8a50b12

manage.py: Remove reference lists, update schema URL

5332eb2

duncandewhurst mentioned this pull request Jul 4, 2023

[Docs update] Restructuring the docs #43

Closed

duncandewhurst added 3 commits July 4, 2023 18:09

Update changelog

5e4cb67

manage.py: Update pre-commit docstring

aae5181

Update pull request template

d3c5515

duncandewhurst requested a review from odscjen July 4, 2023 06:18

duncandewhurst marked this pull request as ready for review July 4, 2023 06:19

odscjen previously approved these changes Jul 4, 2023

View reviewed changes

Apply suggestions from code review

50b4683

Co-authored-by: odscjen <[email protected]>

duncandewhurst dismissed odscjen’s stale review via 50b4683 July 4, 2023 22:27

duncandewhurst requested review from stufraser1 and matamadio July 4, 2023 22:33

duncandewhurst added 2 commits July 5, 2023 10:34

Merge branch 'dev' into schema-reference

73cc0b7

schema/rdl_schema_0.1.json: Fix nesting of exposure object

eee32a7

stufraser1 approved these changes Jul 5, 2023

View reviewed changes

duncandewhurst merged commit cef894d into dev Jul 5, 2023

duncandewhurst deleted the schema-reference branch July 5, 2023 21:04

odscjen added a commit that referenced this pull request Jul 6, 2023

changing exposure and vulnerability anyOf references back to as in #120

5da0f78

duncandewhurst mentioned this pull request Jul 6, 2023

Update Vulnerability adding impact object, function objects and changing some field names and descriptions #124

Merged

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update schema reference #120

Update schema reference #120

duncandewhurst commented Jul 4, 2023 •

edited

Loading

duncandewhurst commented Jul 4, 2023

odscjen left a comment

odscjen Jul 4, 2023

duncandewhurst Jul 4, 2023

odscjen Jul 4, 2023

duncandewhurst Jul 4, 2023

odscjen Jul 4, 2023

duncandewhurst Jul 4, 2023

duncandewhurst commented Jul 4, 2023 •

edited

Loading

stufraser1 left a comment

duncandewhurst commented Jul 5, 2023


		When the scenario modelled refers to a specific period of time, this can be specified in terms of dates, period span and reference year. For example, an observed flood event that occurred from 1.10.2009 (time start) to 3.10.2009 (time end), spanning over 3 days (time span). When precise time collocation is unknown or not applicable, a general reference date such as "2009" is used to identify events (time year). This is also useful to specify future scenario, e.g. time year: 2050.

		When instead the hazard scenario is represented in probabilistic terms, the occurrence probability (frequency distribution) of hazard can be expressed in different ways. The most common way to communicate this is the "return period", expressed as the number of years after which a given hazard intensity could occur again: RP 100 indicates that that event has a probability of once in 100 years. This attribute can indicate individual layer frequency (RP100) or a range of frequencies for a collection of layers (RP10-100) The probability of occurrence is usually calculated on the basis of a reference period that provides observations: this period can be specified by start date, end date and time span. For example, an analysis of earthquake frequency based on seismic observations from 1934 (occurrence time start) to 2001 (occurrence time end), for a total count of 66 years (occurrence time span).

Update schema reference #120

Update schema reference #120

Conversation

duncandewhurst commented Jul 4, 2023 • edited Loading

duncandewhurst commented Jul 4, 2023

odscjen left a comment

Choose a reason for hiding this comment

odscjen Jul 4, 2023

Choose a reason for hiding this comment

duncandewhurst Jul 4, 2023

Choose a reason for hiding this comment

odscjen Jul 4, 2023

Choose a reason for hiding this comment

duncandewhurst Jul 4, 2023

Choose a reason for hiding this comment

odscjen Jul 4, 2023

Choose a reason for hiding this comment

duncandewhurst Jul 4, 2023

Choose a reason for hiding this comment

duncandewhurst commented Jul 4, 2023 • edited Loading

stufraser1 left a comment

Choose a reason for hiding this comment

duncandewhurst commented Jul 5, 2023

duncandewhurst commented Jul 4, 2023 •

edited

Loading

duncandewhurst commented Jul 4, 2023 •

edited

Loading