diff --git a/.gitignore b/.gitignore index 6cedde4..d372f08 100644 --- a/.gitignore +++ b/.gitignore @@ -69,7 +69,7 @@ instance/ .scrapy # Sphinx documentation -docs/_build/ +docs/build/ # PyBuilder target/ diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..9138a7f --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,13 @@ +version: "2" + +build: + os: "ubuntu-22.04" + tools: + python: "3.10" + +python: + install: + - requirements: docs/requirements.txt + +sphinx: + configuration: docs/source/conf.py diff --git a/cancurve/bldgs/cc_bldgs_dialog.ui b/cancurve/bldgs/cc_bldgs_dialog.ui index d85cdfc..d524bdd 100644 --- a/cancurve/bldgs/cc_bldgs_dialog.ui +++ b/cancurve/bldgs/cc_bldgs_dialog.ui @@ -7,7 +7,7 @@ 0 0 800 - 800 + 819 @@ -140,14 +140,14 @@ QTabBar::tab:selected { /* Style for selected tabs */ <html><head><meta name="qrichtext" content="1" /><style type="text/css"> p, li { white-space: pre-wrap; } </style></head><body style=" font-family:'MS Shell Dlg 2'; font-size:14px; font-weight:400; font-style:normal;"> -<p style=" margin-top:12px; margin-bottom:12px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px;"><span style=" font-size:12pt;">Welcome to the CanCurve </span><span style=" font-size:12pt; font-style:italic;">Buildings</span><span style=" font-size:12pt;"> tool! This tool is designed to create </span><span style=" font-size:12pt; font-style:italic;">Depth Damage Functions</span><span style=" font-size:12pt;"> (DDF) for Canadian buildings.</span></p> +<p style=" margin-top:12px; margin-bottom:12px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px;"><span style=" font-size:12pt;">Welcome to the CanCurve </span><span style=" font-size:12pt; font-weight:600;">Buildings Tool.</span><span style=" font-size:12pt;"> This tool is designed to create </span><span style=" font-size:12pt; font-style:italic;">Depth Damage Functions</span><span style=" font-size:12pt;"> (DDF) for Canadian buildings.</span></p> <p align="center" style=" margin-top:12px; margin-bottom:12px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px;"><img src=":/plugins/cancurve/img/icon.png" /></p> <p align="center" style="-qt-paragraph-type:empty; margin-top:12px; margin-bottom:12px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px;"><br /></p> <p style=" margin-top:12px; margin-bottom:12px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px;"><span style=" font-size:12pt;">The following inputs are required:</span></p> -<p style=" margin-top:12px; margin-bottom:12px; margin-left:16px; margin-right:0px; -qt-block-indent:0; text-indent:0px;"><span style=" font-size:12pt; font-weight:600;">Building Metadata</span><span style=" font-size:12pt;">: These standard flood-related building properties are specified on the </span><span style=" font-size:12pt; font-style:italic;">Building Metadata</span><span style=" font-size:12pt;"> tab. This metadata will be used to populate the metadata of your DDF. Some of the fields are also used in the calculation process.</span></p> -<p style=" margin-top:12px; margin-bottom:12px; margin-left:16px; margin-right:0px; -qt-block-indent:0; text-indent:0px;"><span style=" font-size:12pt; font-weight:600;">Cost Information: </span><span style=" font-size:12pt;">This restoration item and cost data is specifed as a CSV file on the </span><span style=" font-size:12pt; font-style:italic;">Data Input</span><span style=" font-size:12pt;"> tab. Click </span><a href="https://github.com/NRCan/CanCurve/blob/main/tests/data/bldgs/case1/R_1-L-BD-CU_ABCA.csv"><span style=" font-size:12pt; text-decoration: underline; color:#0000ff;">here</span></a><span style=" font-size:12pt;"> for an example. </span><span style=" font-size:14px;"><br /></span></p> +<p style=" margin-top:12px; margin-bottom:12px; margin-left:16px; margin-right:0px; -qt-block-indent:0; text-indent:0px;"><span style=" font-size:12pt; font-weight:600;">Metadata</span><span style=" font-size:12pt;">: These standard flood-related building properties are specified on the </span><span style=" font-size:12pt; font-style:italic;">Metadata</span><span style=" font-size:12pt;"> tab. This metadata will be used to populate the metadata of your DDF. Some of the fields are also used in the calculation process.</span></p> +<p style=" margin-top:12px; margin-bottom:12px; margin-left:16px; margin-right:0px; -qt-block-indent:0; text-indent:0px;"><span style=" font-size:12pt; font-weight:600;">Cost-Item Table: </span><span style=" font-size:12pt;">This table of restoration items and their costs is specifed as a CSV file on the </span><span style=" font-size:12pt; font-style:italic;">Data Input</span><span style=" font-size:12pt;"> tab. Click </span><a href="https://github.com/NRCan/CanCurve/blob/main/tests/data/bldgs/case1/R_1-L-BD-CU_ABCA.csv"><span style=" font-size:12pt; text-decoration: underline; color:#0000ff;">here</span></a><span style=" font-size:12pt;"> for an example. </span><span style=" font-size:14px;"><br /></span></p> <p style=" margin-top:12px; margin-bottom:12px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px;"><span style=" font-size:12pt;">The following inputs are optional:</span></p> -<p style=" margin-top:12px; margin-bottom:12px; margin-left:16px; margin-right:0px; -qt-block-indent:0; text-indent:0px;"><span style=" font-size:12pt; font-weight:600;">Depth-Replacement-Factor (DRF) dataset</span><span style=" font-size:12pt;">: This dataset relates flood depth to the percentage loss or damage of a restoration item and is specified on the </span><span style=" font-size:12pt; font-style:italic;">Data Input</span><span style=" font-size:12pt;"> tab. By default, the DRF dataset shipped with CanCurve will be used.</span></p> +<p style=" margin-top:12px; margin-bottom:12px; margin-left:16px; margin-right:0px; -qt-block-indent:0; text-indent:0px;"><span style=" font-size:12pt; font-weight:600;">Depth Replacement-Factor (DRF) dataset</span><span style=" font-size:12pt;">: This dataset relates flood depth to the percentage loss or damage of a restoration item and is specified on the </span><span style=" font-size:12pt; font-style:italic;">Data Input</span><span style=" font-size:12pt;"> tab. By default, the DRF dataset shipped with CanCurve will be used.</span></p> <p style="-qt-paragraph-type:empty; margin-top:12px; margin-bottom:12px; margin-left:16px; margin-right:0px; -qt-block-indent:0; text-indent:0px; font-size:12pt;"><br /></p> <p style=" margin-top:12px; margin-bottom:12px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px;"><span style=" font-size:12pt;">Navigate through the tabs at the top of the window from left-to-right to create your own DDF.</span></p></body></html> @@ -201,7 +201,7 @@ p, li { white-space: pre-wrap; } - Building Metadata + Metadata @@ -220,7 +220,7 @@ p, li { white-space: pre-wrap; } 0 - -317 + 0 745 976 @@ -364,7 +364,7 @@ QGroupBox { - Building Layout + Building Layout* @@ -413,7 +413,7 @@ QGroupBox { - Basement height (value) + Basement height (value)* @@ -505,14 +505,14 @@ QGroupBox { This value is used when 'RCV/Area' is selected to scale the replacement costs (e.g., to footprint area) - Area (value) + Structure area (value)* - Quality of Building Materials + Quality of building materials @@ -726,7 +726,7 @@ QGroupBox { - On this page, you'll load the data needed for CanCurve to create the depth-damage function + Specify the settings and datasets for your project @@ -797,7 +797,7 @@ QGroupBox { - Cost-Item File: + Cost-Item Table: @@ -948,7 +948,7 @@ QGroupBox { - Depth-Replacement-Fraction File + Depth Replacement-Factor (DRF) Database: @@ -1403,6 +1403,9 @@ QLabel { 0 + + build project SQLite database and load data into it + Run @@ -1511,6 +1514,9 @@ QLabel { 0 + + Join DRF to CI then multiply through to create fractional restoration costs + Run @@ -1600,6 +1606,9 @@ QLabel { 0 + + group by story and assemble DDF + Run @@ -1948,7 +1957,7 @@ QLabel { - + diff --git a/cancurve/bldgs/core.py b/cancurve/bldgs/core.py index 33a8f45..f16bfa8 100644 --- a/cancurve/bldgs/core.py +++ b/cancurve/bldgs/core.py @@ -642,7 +642,7 @@ def c00_setup_project( ): - """build project SQLite. load data into it + """build project SQLite database and load data into it Params @@ -923,7 +923,7 @@ def c00_setup_project( def c01_join_drf(proj_db_fp, log=None, ): - """Join DRF to CI then multiply through to create 'depth_rcv' table + """Join DRF to CI then multiply through to create fractional restoration costs Params diff --git a/dev_tools/docs_build.bat b/dev_tools/docs_build.bat new file mode 100644 index 0000000..120794f --- /dev/null +++ b/dev_tools/docs_build.bat @@ -0,0 +1,26 @@ +:: Building CanCurve sphinx documentation (w/o RTD) + + + +:: activate docs environment +call l:\09_REPOS\01_COMMON\sphinx\env\conda_activate.bat + +:: call the shpinx make script +:: call %~dp0..\docs\make.bat html +:: difficult to customize + + +:: change to documentation + +cd %~dp0..\docs + +:: call builder CLI +ECHO on + +sphinx-build -M html .\source .\build --jobs=4 --verbose --show-traceback --nitpicky --warning-file=.\build\sphinx_warnings.txt + + +:: launch it +call build\html\index.html + +cmd.exe \ No newline at end of file diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..b5dde4a --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,7 @@ +#CanCurve documentation + +CanCurve uses Sphinx and ReadTheDocs + +## build sphinx documentation locally +need a python environment w/ sphinx +call .\dev_tools\docs_build.bat \ No newline at end of file diff --git a/docs/cspell.json b/docs/cspell.json new file mode 100644 index 0000000..296f70f --- /dev/null +++ b/docs/cspell.json @@ -0,0 +1,32 @@ +{ + "language": "en-CA", + "dictionaries": ["en-CA"], + "dictionaryDefinitions": [ + { + "name": "en-CA", + "path": "l:\\09_REPOS\\01_COMMON\\sphinx\\env\\sphinx\\node_modules\\@cspell\\dict-en-ca\\en_CA.trie" + } + ], + "enableFiletypes": [ + "rst" + ], + "ignoreRegExpList": [ + "/<[^>]*>/g", // Ignore text within angle brackets + "/^\\../" // Ignore lines that begin with .. + ], + "ignorePaths": [ + "package-lock.json", + "node_modules", + "vscode-extension", + ".git/objects", + ".vscode", + ".vscode-insiders", + ".settings" + ], + "userWords": [ + "operationalize", + "QGIS", + "Xactimate", + "DDFP" + ] +} diff --git a/docs/source/01_getting-started.rst b/docs/source/01_getting-started.rst new file mode 100644 index 0000000..7e61711 --- /dev/null +++ b/docs/source/01_getting-started.rst @@ -0,0 +1,90 @@ +.. _sec01-gettingStarted: + +Getting Started +================== +The following sections will help you get started using CanCurve. +We suggest reading these sections first. + + +.. _sec01-install: + +Installation +------------ + +To install CanCurve, you first need to install QGIS, then you can install CanCurve from the Plugin Repository. + +For detailed instructions, refer to the `project README `_. +For best performance, ensure you have the specified version of QGIS installed. + + +.. _sec01-overview: + +Overviews +----------------------- +CanCurve is a collection of tools for generating Depth Damage Functions (DDF) used by platforms like `CanFlood `_ to create flood risk models. +CanCurve's :ref:`Buildings Tool ` for example facilitates the creation of DDFs from detailed restoration cost data for archetypal buildings. +This tool joins a table of restoration activities (e.g., repair dry-wall for $1000), called the :ref:`Cost-Item Table `, to a database of information on the flood vulnerability of those items, called the :ref:`Depth-Replacement-Factor (DRF) Database `. +After identifying the target building or archetype for which a user would like to construct a DDF, typically a :ref:`Cost-Item Table ` is prepared using local pricing tables and expert knowledge on the restoration of the building. +For the :ref:`DRF Database `, either the version shipped with CanCurve can be used (default), or an alternate file can be specified. +Once these inputs and the building metadata are prepared and entered into the Buildings Tool, the four :ref:`Curve Creation ` steps can be run to create and export a DDF in :ref:`CanFlood format `. + + + + + +.. _sec01-quick: + +Quick-Start +----------------------- +After installation of the plugin, the |CanCurve_icon| icon should appear on your plugins toolbar. +If you don't see the icon, first ensure the plugin is checked on the **Installed** tab of the **Manage and Install Plugins..** dialog; then ensure the **plugins toolbar** is enabled by right-clicking the QGIS toolbar. + +.. |CanCurve_icon| image:: /assets/icon_solid.png + :align: middle + :width: 14 + +To start working with CanCurve, click the |CanCurve_icon| to open the :ref:`Buildings Tool ` dialog. + + +.. _fig01-dialog-welcome: + +.. figure:: /assets/01-dialog-welcome.png + :alt: Welcome Tab + :align: center + :width: 900px + + Welcome tab of the Buildings Tool. + + +To use the tool to create a DDF from data for your archetypal building, first populate the **Metadata** tab with whatever information is available (see the :ref:`Tutorials ` section for example data). +Note only fields marked with an asterisk (*) are required, but the more information you provide, the more complete your DDF will be. +To specify settings, the :ref:`Cost-Item Table `, the :ref:`Depth-Replacement Factor (DRF) Database `, and the :ref:`Fixed Costs ` data, complete the **Data Input** tab. +Finally, the four curve creation steps can be executed from the **Create Curve** tab, ending in an export of your DDF in :ref:`CanFlood format `. + + +See the :ref:`User Guide ` and the :ref:`Tutorials ` section to learn more. + + +.. _sec01-faq: + +Frequently Asked Questions +-------------------------- + +**Where can I find Cost-Item data for my archetype?** + Typically this information is obtained from cost restoration experts using specialized software like Xactimate and a detailed model of the structure. + +**How can I add entries to my Depth-Replacement-Factor (DRF) Database** + You'll need to use some software that allows editing of SQLite databases. We recommend `DB Browser for SQLite `_. + +**Where can I go to get help?** + The best place to get help is the `CanCurve GitHub Issues `_ page where you can read through questions posted by others or ask your own. + + +**Do I really need to install an old version of QGIS to use CanCurve** + No, but we recommend it for best performance. If you have a newer version of QGIS installed, you can try CanCurve with it, but you may experience issues. + + + + + + diff --git a/docs/source/02_user-guide.rst b/docs/source/02_user-guide.rst new file mode 100644 index 0000000..4c86dfb --- /dev/null +++ b/docs/source/02_user-guide.rst @@ -0,0 +1,213 @@ +.. _sec02-userGuide: + + +User Guide: Buildings Tool +========================== + +.. _sec02-bldgs: + + +The CanCurve **Buildings Tool** is designed to create Depth Damage Functions (DDF) for an archetypal Canadian building from detailed restoration cost data. +Basically, the tool joins this cost data to a database of item vulnerability then groups the data by depth to create a simple function for *flood damage* against *flood depth* (with some additional features of course). + +Introduction +------------- +The devastation of the 2013 Southern Alberta and Toronto Floods triggered a transition in Canada from the traditional standards-based approach, where flood protection is designed for a single level-of-safety, towards a risk-based approach. +This new risk-based approach recognizes that robust planning must consider vulnerability and a range of floods that may harm a community, rather than focusing on a single design event. +The foundation of this new approach are *flood risk models*: a collection of procedures, algorithms, and mathematical functions used to simplify, study, and quantify the components of our world that relate to flood risk. +At the core of most flood risk models are a set of flood damage functions. + +Depth Damage Functions (DDF) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Flood damage functions are a mathematical relationship between hazard and vulnerability variables against the estimated damages from flooding (e.g., building repair costs) for an individual asset. +The most basic functions directly relate flood depth to damage --- the so-called depth-damage curves or functions (DDF) widely attributed to Gilbert White [#1]_. +Damage functions are typically categorized based on the model's focus or objective, such as the sector (residential vs. non-residential), tangibility (tangible vs. intangible), damage mechanism (indirect vs. direct), and uncertainty treatment (deterministic vs. probabilistic) [#2]_. +Further classification considers the function structure such as continuity (discrete vs. continuous) and for tangible economic functions the asset total value relation (relative vs. absolute). +While depth-damage functions are still common, research in the past two decades has advanced the understanding of flood damage processes and, along with new data and techniques, has led to more sophisticated and accurate multi-variate models [#3]_. +CanCurve currently supports discrete, tangible, absolute, single-variable, depth-damage functions. + + +Flood Risk Modelling in Canada +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Natural Resources Canada (NRCan) develops and maintains flood risk software and data tools to support disaster resilience in Canada. +In particular, NRCan maintains `CanFlood `_, a QGIS plugin for building and running flood risk models. +A major input or component of CanFlood models are DDFs. +Traditionally, CanFlood users struggled to obtain DDFs from past projects or public repositories, leading to inefficient and inaccurate risk modelling. +To address this gap, in 2023 NRCan commissioned the Arcadis company to develop a system for constructing local DDFs in Canada. +This resulted in a formal process for constructing DDFs called *Program for the Development of Flood Damage (Vulnerability) Curves for buildings in Canada* (a.k.a. the DDF Program or DDFP). +To operationalize this, NRCan initiated the CanCurve project. + +.. _sec02-dataRequirements: + +Data Requirements +----------------- +The **Buildings Tool** requires three types of data about the archetypal building in order to generate a DDF, as summarized in the following sections. +See :ref:`Tutorials ` for data examples. + +Building Metadata +~~~~~~~~~~~~~~~~~ +Building metadata is simple information relevant to estimating the flood vulnerability of an archetype, like the year of construction, the date associated with the cost estimate, the person preparing the estimate, etc. +This information is used by the Buildings Tool to populate metadata fields on output DDFs and, in some cases, to assemble the DDF. +Metadata is specified on the **Metadata** tab and stored in the **c00_bldg_meta** table of the :ref:`Project Database ` +The user is expected to obtain this information from expert knowledge and documentation on the archetype. +To assemble the DDF, the following metadata is required: + + - **Building Layout** (``bldg_layout``): Corresponds to categories in the DRF dataset. + - **Basement height value** (``basement_height_m``): The height of the basement in meters, used to concatenate the cost values between storys. + - **Structure area value** (``scale_value``): The area of the structure in square meters used to scale the cost values for :ref:`Area-based ` cost basis. + +It is good practice to specify additional metadata fields, which the Buildings Tool propagates onto the output DDFs. + +.. _sec02-costItem: + +Cost-Item Table +~~~~~~~~~~~~~~~~ + +This restoration item and cost data is specified as a CSV file on the **Data Input** tab. +Typically this information is obtained from cost restoration experts using specialized software like Xactimate and a detailed model of the structure. + + +.. _sec02-DRF: + +Depth Replacement-Factor (DRF) Database +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This database relates flood depth to the percentage loss or damage of a restoration item and is specified on the **Data Input** tab. +The DRF database is a SQLite database with three tables: + + - **cost_item_meta**: lookup and description fields for each cost-item with key fields ``cat``, ``sel``, and ``bldg_layout``. + - **drf**: the depth-replacement-factor for each cost-item with key fields ``cat``, ``sel``, and ``bldg_layout``. + - **meta**: metadata for the database. + +By default, the DRF database shipped with CanCurve will be used, which is installed into the `./db` directory of the CanCurve plugin. +This database was constructed by the DDFP project in consultation with cost-restoration specialists and reflects the vulnerability of a typical Canadian building to stillwater flooding. +:numref:`fig01-conceptual-diagram` provides a diagram of how the remote, local, and project datasets are related. + +.. _fig01-conceptual-diagram: + +.. figure:: /assets/01-conceptual-diagram.png + :alt: Conceptual Diagram + :align: center + :width: 900px + + Conceptual diagram of the CanCurve Buildings Tool. + +.. _sec02-fixedCosts: + +Fixed Costs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This simple dataset has two values: the fixed costs for the restoration of the basement and the mainfloor. +This represents the sum of all depth-invariant cost items for each floor i.e., restoration costs that would be incurred regardless of flood depth. +For example, mobilization costs or permit fees. +This dataset is specified on the **Data Input** tab and stored in the **c00_fixed_costs** table of the Project Database. + + +Key Concepts +----------------- +The **Buildings Tool** is composed of the Graphical User Interface (GUI) front-end and a collection of python scripts for performing the data operations in the back-end, called the ``core`` which contains four :ref:`Curve Creation ` steps. +A typical workflow starts by preparing the :ref:`Input Data `, populating the fields in the GUI, then executing the :ref:`Curve Creation Steps `. + + + +.. _sec02-Core: + +Core: Curve Creation Steps +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +At the core of the Buildings Tool are four curve creation steps that are executed in sequence to generate a DDF. +These are controlled from the **Create Curve** tab and can be executed individually or all at once: + +1. **Setup project**: + Construct the :ref:`Project Database ` and load data into it from the GUI. + +2. **Data join and multiply costs**: + Join :ref:`DRF Database ` to the :ref:`Cost-Item table `, then multiply through to create fractional restoration costs. + +3. **Data group and concat stories**: + Group restoration costs by story and concatenate them into a single table. + +4. **Export result in CanFlood format**: + Export the DDF in the :ref:`CanFlood format `. + +To pass information between these steps and to save the user's progress to disk, all of these steps read or write to a :ref:`Project Database `. + +.. _sec02-projectDatabase: + +Project Database +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The **Project Database** is a SQLite database that the Buildings Tool creates for each project, then uses to store the data and metadata for the project. +For most workflows, the Project Database is hidden in the background; however, knowledge of the project database can be useful for debugging and understanding the tool's operation. +The database is composed of several tables, each of which is used by one or more of the :ref:`curve creation steps `, as shown in the table below. + +.. _tab02-ProjectDatabase: + +.. table:: Project Database tables and corresponding Curve Creation Steps + :widths: auto + + +------------------+--------------------------------------------+------+ + | Table Name | Description | Step | + +==================+============================================+======+ + | c00_bldg_meta | Building metadata | 1 | + +------------------+--------------------------------------------+------+ + | c00_cost_items | Cost-Item table | 1 | + +------------------+--------------------------------------------+------+ + | c00_drf | DRF database [#4]_ | 1 | + +------------------+--------------------------------------------+------+ + | c00_fixed_costs | Fixed costs | 1 | + +------------------+--------------------------------------------+------+ + | c01_depth_rcv | Fractional item cost for each depth | 2 | + +------------------+--------------------------------------------+------+ + | c02_ddf | DDF for each story | 3 | + +------------------+--------------------------------------------+------+ + | project_meta | Metadata tracking operations on the db | all | + +------------------+--------------------------------------------+------+ + | project_settings | Project settings | 1 | + +------------------+--------------------------------------------+------+ + +To view and manipulate the project database, the user can use a SQLite database viewer like `DB Browser for SQLite `_. + + +.. _sec02-CanFloodFormat: + +CanFlood Format DDF +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Currently, the buildings tool supports exporting DDFs in the CanFlood format. +The `CanFlood `_ program expects DDFs to be in a certain format, namely an XLSX file with two columns divided into two sections. +The first section contains the metadata in key-value pairs while the second section contains the exposure-impact series. +CanFlood requires three keys in the metadata section: + + - ``tag``: used for linking the curve to the inventory. + - ``impact_units``: used for indicating what units the impact values are in (e.g., $CAD) on plots and reports. + - ``exposure``: used to indicate the transition between the metadata and the exposure-impact sections. + +It is good practice to include additional metadata (e.g., location); however, these are not strictly required by CanFlood. +Below is a minimum example CanFlood format DDF. + +.. _fig02-CanCurve-format: + +.. figure:: /assets/02-CanCurve-format.png + :alt: CanCurve format + :align: center + :width: 900px + + CanFlood format DDF minimum example. + +.. _sec02-costBasis: + +Cost Basis +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +CanCurve supports two cost bases: + + - **Total** ($/structure): The resulting DDF will reflect the total restoration costs for the archetype as a function of depth. This can be useful for debugging and for risk models with very similar structures. For DDFs of this type, the calculated impacts should not be scaled. + - **Area-based** ($/area): The resulting DDF will reflect the restoration costs per area of the structure as a function of depth. The units of the DDF impact values can be $/ft^2 or $/m^2 depending on what was specified in the **Structure area** field on the **Metadata** tab. This basis is useful for adapting the resulting archetypal DDF to other structures by scaling the impact values by the area of the structure. Most CanFlood models use this cost basis. + + + + +.. [#1] White, G. F.: Human Adjustment to Floods. A Geographical Approach to the Flood Problem in the United States, The University of Chicago, Chicago, 1945. + +.. [#2] Merz, B., Kreibich, H., Schwarze, R., and Thieken, A.: Review article “Assessment of economic flood damage,” Nat. Hazards Earth Syst. Sci., 10, 1697–1724, https://doi.org/10.5194/nhess-10-1697-2010, 2010. + +.. [#3] Schröter, K., Kreibich, H., Vogel, K., Riggelsen, C., Scherbaum, F., and Merz, B.: How useful are complex flood damage models?, Water Resources Research, 50, 3378–3395, https://doi.org/10.1002/2013WR014396, 2014. + +.. [#4] Only those DRF entries intersecting with the c00_cost_items table are included. + diff --git a/docs/source/03_tutorials.rst b/docs/source/03_tutorials.rst new file mode 100644 index 0000000..3ec981b --- /dev/null +++ b/docs/source/03_tutorials.rst @@ -0,0 +1,77 @@ +.. _sec03-tutorials: + +Tutorials +========================== + +This section contains a collection of tutorials with example data and results. +Be sure to read and follow the :ref:`Getting Started Section ` before attempting these tutorials. + +.. _sec03-tut01: + +Tutorial 1: Single-Story Residential +------------------------------------- + +This tutorial will demonstrate how to create a :ref:`CanFlood format DDF ` from a :ref:`Cost-Item Table ` and some default values for a single-story residential building using the :ref:`Buildings Tool `. + +Step 1: Download the example Cost-Item Table +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +From the project repository, download the `example Cost-Item Table `_ somewhere easy to find. + +Step 2: Enter Metadata +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Open the :ref:`Buildings Tool `, navigate to the **Metadata** tab, and populate the fields as shown below: + + +.. figure:: /assets/03_01_meta01.PNG + :alt: Metadata Tab + :align: center + :width: 900px + +.. figure:: /assets/03_01_meta02.PNG + :alt: Metadata Tab + :align: center + :width: 900px + + Metadata for Tutorial 1 + +Step 3: Data Input +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Navigate to the **Data Input** tab and, using the below image for reference, populate the following fields: + + - **Working Directory**: choose your own path or use the default + - **Project Name**: choose your own name or use the name shown + - **Cost-Item Table**: browse to the downloaded example Cost-Item Table .csv file from Step 1. + - **Fixed Costs**: enter the two values shown below. + - **Cost Basis**: For this tutorial we will use :ref:`Area Based `. + - **DRF Database**: By default, the field should be populated with the filepath to the DRF Database that ships with CanCurve. + +.. figure:: /assets/03_01_dataInput.PNG + :alt: Data Input Tab + :align: center + :width: 900px + + Data Input page for Tutorial 1 + +Step 4: Create Curve +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Navigate to the **Create Curve** tab. +In the **Run Control** box, select **All**, then click **Run**. +You should see the progress of each of the four :ref:`Curve Creation Steps ` along with a message in the bottom window informing you that the DDF has been output to the **Working Directory** you specified in Step 3, similar to what is shown below. + +.. figure:: /assets/03_01_cc.PNG + :alt: Curve Creation Tab + :align: center + :width: 900px + + Curve Creation page for Tutorial 1 + +For additional log messages, you can return to the main QGIS window, open the log panel (View>Panels>Log Messages), and select the **CanCurve** tab. +Scrolling up, you should see diagnostic messages for each of the four steps you just ran. +This is the end of a typical workflow; however, the **Buildings Tool** provides for some additional functionality and output control that you may wish to explore. +For example, selecting the **Individual Steps** radio button will allow you to specify your own project database and generate some diagnostic plots for each step. +Similarly, expanding the **Output Control** box shows some additional options for controlling the output of the tool. + + + + diff --git a/docs/source/assets/01-conceptual-diagram.png b/docs/source/assets/01-conceptual-diagram.png new file mode 100644 index 0000000..ee36b24 Binary files /dev/null and b/docs/source/assets/01-conceptual-diagram.png differ diff --git a/docs/source/assets/01-dialog-welcome.png b/docs/source/assets/01-dialog-welcome.png new file mode 100644 index 0000000..707f54c Binary files /dev/null and b/docs/source/assets/01-dialog-welcome.png differ diff --git a/docs/source/assets/02-CanCurve-format.png b/docs/source/assets/02-CanCurve-format.png new file mode 100644 index 0000000..cb8866c Binary files /dev/null and b/docs/source/assets/02-CanCurve-format.png differ diff --git a/docs/source/assets/03_01_cc.PNG b/docs/source/assets/03_01_cc.PNG new file mode 100644 index 0000000..f815505 Binary files /dev/null and b/docs/source/assets/03_01_cc.PNG differ diff --git a/docs/source/assets/03_01_dataInput.PNG b/docs/source/assets/03_01_dataInput.PNG new file mode 100644 index 0000000..1a193b2 Binary files /dev/null and b/docs/source/assets/03_01_dataInput.PNG differ diff --git a/docs/source/assets/03_01_meta01.PNG b/docs/source/assets/03_01_meta01.PNG new file mode 100644 index 0000000..2549d59 Binary files /dev/null and b/docs/source/assets/03_01_meta01.PNG differ diff --git a/docs/source/assets/03_01_meta02.PNG b/docs/source/assets/03_01_meta02.PNG new file mode 100644 index 0000000..462c0f9 Binary files /dev/null and b/docs/source/assets/03_01_meta02.PNG differ diff --git a/docs/source/assets/icon_28x20.png b/docs/source/assets/icon_28x20.png new file mode 100644 index 0000000..ace2086 Binary files /dev/null and b/docs/source/assets/icon_28x20.png differ diff --git a/docs/source/assets/icon_solid.png b/docs/source/assets/icon_solid.png new file mode 100644 index 0000000..d6d6c0b Binary files /dev/null and b/docs/source/assets/icon_solid.png differ diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..a656ded --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,54 @@ +# Configuration file for the Sphinx documentation builder. + +# -- Project information + +project = 'CanCurve' +copyright = '2024, NRCan' +author = 'Seth Bryant' + +release = '0.1' +version = '0.1.0' + +# -- General configuration + +extensions = [ + 'sphinx.ext.duration', + 'sphinx.ext.doctest', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.intersphinx', + 'sphinx.ext.githubpages' +] + +intersphinx_mapping = { + 'python': ('https://docs.python.org/3/', None), + 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), +} +intersphinx_disabled_domains = ['std'] + +templates_path = ['_templates'] + +# -- Options for HTML output + +html_theme = 'sphinx_rtd_theme' + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +html_logo = 'assets/icon_solid.png' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = "en" + +# locale_dirs = ['locale/'] # path is example but recommended. +# gettext_uuid = True +# gettext_compact = False + + +# Enable numref +numfig = True + + diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..de7ec01 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,21 @@ +Welcome to CanCurve! +=================================== + + + + +.. note:: + + This project is under active development. + +Contents +-------- + +.. toctree:: + :maxdepth: 2 + + 01_getting-started + 02_user-guide + 03_tutorials + + diff --git a/tutorial/case1/R_1-L-BD-CU_ABCA.csv b/tutorial/01/R_1-L-BD-CU_ABCA.csv similarity index 100% rename from tutorial/case1/R_1-L-BD-CU_ABCA.csv rename to tutorial/01/R_1-L-BD-CU_ABCA.csv diff --git a/tutorial/01/c01/case1_c00.cancurve b/tutorial/01/c01/case1_c00.cancurve new file mode 100644 index 0000000..81f9f57 --- /dev/null +++ b/tutorial/01/c01/case1_c00.cancurve @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0cade17497567ebc323c29a8b8c3569d3e735dfd950874629b0db209928674a9 +size 159744 diff --git a/tutorial/01/c02/copy_case1_c00.cancurve b/tutorial/01/c02/copy_case1_c00.cancurve new file mode 100644 index 0000000..b8f981a --- /dev/null +++ b/tutorial/01/c02/copy_case1_c00.cancurve @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:33c51ed8db874559c734b0c780770be8e1c9c0301e20befda2e8088ca5b400e1 +size 311296 diff --git a/tutorial/01/c03/copy_copy_case1_c00.cancurve b/tutorial/01/c03/copy_copy_case1_c00.cancurve new file mode 100644 index 0000000..d32088f --- /dev/null +++ b/tutorial/01/c03/copy_copy_case1_c00.cancurve @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c52b7a24cf25c9c1197f3eb7fe14f7e96ccb54d10fb497a0e297468dc2f3acc0 +size 319488 diff --git a/tutorial/01/c04/copy_copy_copy_case1_c00.cancurve b/tutorial/01/c04/copy_copy_copy_case1_c00.cancurve new file mode 100644 index 0000000..d32088f --- /dev/null +++ b/tutorial/01/c04/copy_copy_copy_case1_c00.cancurve @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c52b7a24cf25c9c1197f3eb7fe14f7e96ccb54d10fb497a0e297468dc2f3acc0 +size 319488 diff --git a/tutorial/case1/metadata.txt b/tutorial/01/readme.md similarity index 82% rename from tutorial/case1/metadata.txt rename to tutorial/01/readme.md index ad62368..a116179 100644 --- a/tutorial/case1/metadata.txt +++ b/tutorial/01/readme.md @@ -1,3 +1,10 @@ +# Tutorial 1 data + +See documentation for instructions + + +# Metadata + username: cef date: 2024-04-16 script_name: port_estimate.py diff --git a/tutorial/case1/case1_result.cancurve b/tutorial/case1/case1_result.cancurve deleted file mode 100644 index 2d7c55d..0000000 --- a/tutorial/case1/case1_result.cancurve +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:15d0538b4570db4f7c7b9643b078acbdacf5faa33771cc6da8b2ece4a08cc15d -size 303104