PWFDF-R Data Spec v1.0.0
========================

This is a permanent record of version 1.0.0 of the PWFDF-R data specification.

The PWFDF-R Collection conforms to the `PWFDF v1.0 data specification <https://ghsc.code-pages.usgs.gov/lhp/ocelote/data-spec/archive/1.0.0/index.html>`_ with the modifications described on this page. Refer to the `PWFDF v1.0 data specification <https://ghsc.code-pages.usgs.gov/lhp/ocelote/data-spec/archive/1.0.0/index.html>`_ for elements of the data specification not documented here.


ScienceBase Collection
----------------------

Child Items
+++++++++++

The `PWFDF-R Collection <https://www.sciencebase.gov/catalog/item/6851e986d4be027dac17f0ae>`_ is hosted on the USGS's `ScienceBase data catalog <https://www.sciencebase.gov/catalog/>`_ as catalog item ``6851e986d4be027dac17f0ae``. The collection consists of multiple child items, with one item per version of each hazard assessment. Child items follow a similar naming scheme as the `PWFDF Collection <https://doi.org/10.5066/P14EWYME>`_. The naming scheme is ``<fire> <YYYY-MM-DD> v<X.Y> postfire debris-flow runout hazard assessment``, with the following substitutions:

.. list-table::
    :header-rows: 1

    * - Substitution
      - Description
    * - ``<fire>``
      - The name of the fire event.
    * - ``<YYYY-MM-DD>``
      - An ISO 8601 date string indicating the start date of the fire event.
    * - ``<X.Y>``
      - The version number of the assessment.


Version Naming
++++++++++++++
In some cases, a short descriptive identifier may be used instead of the ``vX.Y.Z`` format for the `Assessment Version <https://ghsc.code-pages.usgs.gov/lhp/ocelote/data-spec/archive/1.0.0/sciencebase.html#assessment-versions>`_. For example, if alternative cases are described by a paper the version text may refer to the name of the case as described in the paper.


Assessment Files
----------------

Each assessment includes the following items:

.. list-table::
    :header-rows: 1

    * - File
      - Description
    * - ``Shapefile.zip``
      - A zip archive holding assessment results, formatted as Shapefiles.
    * - ``GeoJSON.zip``
      - A zip archive holding assessment results, formatted as GeoJSON.
    * - ``metadata.json``
      - `JSON <https://www.json.org/json-en.html>`_ metadata file with information on the fire event and implementation of the assessment.
    * - ``version.txt``
      - Text file documenting the version of `ursa <https://ghsc.code-pages.usgs.gov/lhp/ursa/>`_ used for the hazard assessment. This file is programatically generated. 
    * - ``user-input.zip``
      - A zip archive holding user-provided datasets used as inputs for the hazard assessment.
    * - ``configuration.yml``
      - Configuration settings used to implement the assessment via the `ursa package <https://ghsc.code-pages.usgs.gov/lhp/ursa/>`_.
    * - ``<fire>_<YYYY-MM-DD>_v<X-Y>_postfire_debris-flow_runout_hazard_assessment.xml``
      - FGDC-compliant XML metadata describing the assessment for the ScienceBase interface.


Assessment Results
++++++++++++++++++

Both the ``Shapefile.zip`` and ``GeoJSON.zip`` archives hold the same assessment results, albeit formatted as Shapefiles and GeoJSON, respectively. When extracted, each archive consists of the following data layers:

.. list-table::
    :header-rows: 1

    * - Layer
      - Geometry
      - Description
    * - ``basins``
      - Polygon
      - Holds assessment results for the catchment basins of the stream segment network. See the `PWFDF Data Spec <https://ghsc.code-pages.usgs.gov/lhp/ocelote/data-spec/archive/1.0.0/data-fields.html>`_ for an explanation of the data fields.
    * - ``I15_<RR>-simulation_index``
      - Polygon
      - The location of runout for each considered debris-flow simulation index generated using a 15-minute rainfall intensity of ``RR``, in mm/hr. Data fields are documented below.


In addition, a text file ``readme.txt`` is provided inside of the ``.zip`` files containing the standard ursa :ref:`disclaimer <limitations>`. Suggestions for cartographic depiction of the assessment results, including recommended colors, are provided in ``cartography.txt`` within each of the ``.zip`` files. 


Assessment Data Fields
----------------------

runout
++++++

Runout information for each 15-minute rainfall intensity scenario is provided in an individual file. The following two column names are provided in each file.


.. list-table::
    :header-rows: 1

    * - Field
      - Units or Range
      - Description
    * - ``I15``
      - Number greater than zero
      - The peak 15-minute rainfall intensity used as a design storm in mm/hour.
    * - ``dfsi_thr``
      - Number between zero and one
      - The threshold debris-flow simulation index (dfsi) value used to calculate the runout extent.


metadata.json
-------------

The ``metadata.json`` file contains one additional element in the ``assessment.models`` block to documente the implementation of the runout hazard assesment.


``models``
++++++++++

The ``assessment.models`` object documents the models used to estimate debris-flow hazards.

.. list-table::
    :header-rows: 1

    * - Field
      - Type
      - Description
    * - ``runout``
      - Object
      - Documents the model used to estimate debris-flow runout.


Each model object will contains the same fields as the `PWFDF v1.0 Data Spec <https://ghsc.code-pages.usgs.gov/lhp/ocelote/data-spec/archive/1.0.0/metadata.html#models>`_. The ``assessment.models.runout.parameters`` object contains the following values:



A given ``parameters`` object may include the following fields:

.. list-table::
    :header-rows: 1

    * - Field
      - Type
      - Description
    * - ``I15``
      - [Number, ...]
      - The list of peak 15-minute rainfall intensities used as design storms.
    * - ``I15_SE``
      - [Number, ...]
      - The confidence interval, as a list of standar errors computed for potential sediment volumes.
    * - ``probability``
      - Number
      - The debris-flow likelihood used to include or exclude basins from further analysis.
    * - ``kr``
      - [Number, ...]
      - The list of debris permeability values used to reflect varation in debris-flow travel distance.