Merge pull request #2 from zsarnoczay/master

azs - extend docs
NHERI-SimCenter · Nov 6, 2018 · 3f12d95 · 3f12d95
2 parents 2e5eca8 + 2c0d147
commit 3f12d95
Show file tree

Hide file tree

Showing 9 changed files with 186 additions and 15 deletions.
diff --git a/README.md b/README.md
@@ -8,24 +8,54 @@ Probabilistic Estimation of Losses, Injuries, and Community resilience Under Nat
 
 ## What is it?
 
-Detailed documentation is available at http://pelicun.readthedocs.io
+`pelicun` is a Python package that provides tools for assessment of damage and losses due to natural hazards. It uses a stochastic damage and loss model that is based on the methodology described in FEMA P58 (FEMA, 2012). While FEMA P58 aims to assess the seismic performance of a building, with `pelicun` we want to provide a more versatile, hazard-agnostic tool that will eventually provide loss estimates for other types of assets (e.g. bridges, facilities, pipelines) and lifelines. The underlying loss model was designed with these objectives in mind and it will be gradually extended to have such functionality.
+
+Currently, the scenario assessment from the FEMA P58 methodology is built-in the tool. Detailed documentation of the available methods and their use is available at http://pelicun.readthedocs.io
 
 ## What can I use it for?
 
+The current version of `pelicun` can be used to quantifiy lossess from an earthquake scenario in the form of *decision variables*. This functionality is typically utilized for performance based engineering or seismic risk assessment. There are several steps of seismic performance assessment that `pelcicun` can help with:
+
+- **Describe the joint distribution of seismic response.** The response of a structure or other type of asset to an earthquake is typically described by so-called *engineering demand parameters* (EDPs). `pelicun` provides methods that take a finite number of EDP vectors and find a multivarite distribution that describes the joint distribution of EDP data well.
+
+- **Define the damage and loss model of a building.** The component damage and loss data from FEMA P58 is provided with `pelicun`. This makes it easy to define building components without having to provide all the data manually. The stochastic damage and loss model is designed to facilitate modeling correlations between several parameters of the damage and loss model.
+
+- **Estimate component damages.** Given a damage and loss model and the joint distribution of EDPs, `pelicun` provides methods to estimate the quantity of damaged components and collapses.
+
+- **Estimate consequences.** Using information about collapses and component damages, the following consequences can be estimated with the loss model: reconstruction cost and time, unsafe placarding (red tag), injuries and fatalities. 
+
 ## Why should I use it?
 
+1. It is free and it always will be. 
+2. It is open source. You can always see what is happening under the hood.
+3. It is efficient. The loss assessment calculations in `pelicun` use `numpy` and `scipy` libraries to efficiently propagate uncertainties and provide detailed results quickly.
+4. You can trust it. Every function in `pelicun` is tested after every commit. See the Travis-CI and Coveralls badges at the top for more info. 
+5. You can extend it. If you have other methods that you consider better than the ones we already offer, we encourage you to fork the repo, and extend `pelicun` with your approach. You do not need to share your extended version with the community, but if you are interested in doing so, contact us and we are more than happy to merge your version with the official release.
+
 ## Requirements
 
+The following packages are required for `pelicun`:
+
+- `numpy` >= 1.15.1
+
+- `scipy` >= 1.1
+
+- `pandas` >= 0.20
+
+We recommend installing the Anaconda Python distribution because these packages and many other useful ones are available there.
+
 ## Installation
 
+`pelicun` is available for Python 2.7 and Python 3.5+ at the Python Package Index (PyPI). You can simply install it using `pip` as follows:
+
 ```
 pip install pelicun
 ```
 
 ## License
 
-pelicun is distributed under the BSD 3-Clause license, see LICENSE.
+`pelicun` is distributed under the BSD 3-Clause license, see LICENSE.
 
 ## Contact
 
-* Adam Zsarnóczay, NHERI SimCenter, Stanford University, [email protected]
+Adam Zsarnóczay, NHERI SimCenter, Stanford University, [email protected]
diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
@@ -0,0 +1,3 @@
+td {
+	white-space: normal !important;
+}
diff --git a/docs/conf.py b/docs/conf.py
@@ -31,9 +31,9 @@
 author = 'Adam Zsarnoczay'
 
 # The short X.Y version
-version = '0.1'
+version = '1.0.0'
 # The full version, including alpha/beta/rc tags
-release = '0.1'
+release = '1.0.0'
 
 
 # -- General configuration ---------------------------------------------------
@@ -200,4 +200,5 @@ def setup(app):
             #'url_resolver': lambda url: github_doc_root + url,
             'auto_toc_tree_section': 'Contents',
             }, True)
-    app.add_transform(AutoStructify)
+    app.add_transform(AutoStructify)
+    app.add_stylesheet('css/custom.css')
diff --git a/docs/features.rst b/docs/features.rst
@@ -0,0 +1,95 @@
+Features
+============
+
+The following table outlines the features that are currently available in the tool and the requirements that will drive future development. We welcome suggestions for useful features that are missing from the list below. The priority column provides information about the relative importance of features planned for a given release: **M** - mandatory, **D** - desirable, **O** - optional, **P** - possible.
+
+.. table:: List of features
+    :widths: 1, 50, 1, 1, 1
+    :class: tight-table
+
+    ==== ========================================================================================= ========= ========== ========
+    ID   description                                                                               priority  available  planned 
+    ==== ========================================================================================= ========= ========== ========
+    1    **Assessment Methods**                                                          
+    1.1  Perform component-based (e.g. FEMA-P58 style) loss assessment for earthquake scenarios.   M         1.0               
+    1.2  Perform component-group-based (e.g HAZUS style) loss assessment for earthquake scenarios. D                    1.1
+    1.3  Perform loss assessment for hurricane scenarios based on the HAZUS hurricane methodology. D                    1.2
+    1.4  Perform downtime estimation using the ARUP's REDi methodology.                            D                    1.2
+    1.5  Perform time-based assessment for seismic hazard.                                         M                    1.3
+
+    2    **Control**       
+    2.1  Specify number of realizations.                                                           M         1.0
+    2.2  Specify log-standard deviation increase to consider additional sources of uncertainty.    M         1.0
+    2.3  Pick the decision variables to calculate.                                                 D         1.0
+    2.4  Specify the number of inhabitants on each floor and their temporal distribution.          D         1.0
+    2.5  Specify the basic boundary conditions of repairability.                                   D         1.0
+    2.6  Control collapse through EDP limits.                                                      D         1.0
+    2.7  Specify the replacement cost and time for the asset.                                      M         1.0
+    2.8  Specify EDP boundaries that define the domain with reliable simulation results.           D         1.0
+    2.9  Specify collapse modes and characterize the corresponding likelihood of injuries.         D         1.0
+
+    3    **Component DL information**
+    3.1  Make the component damage and loss data from FEMA P58 (1st ed.) available in the tool.    M         1.0
+    3.2  Facilitate the use of custom components for loss assessment.                              D         1.0
+    3.3  Enable different component quantities for each floor in each direction.                   D         1.0
+    3.4  Enable fine control over quantities of identical groups of components within a PG.        D         1.0
+    3.5  Create a generic JSON data format to store component DL data.                             D                    1.1
+    3.6  Convert FEMA P58 and HAZUS component DL data to the new JSON format.                      D                    1.1
+    3.7  Extend the list of available decision variables with those from HAZUS                     D                    1.2
+    3.8  Extend the list of available decision variables with those from REDi                      D                    1.2
+
+    4    **Stochastic loss model**
+    4.1  Enable control of basic dependencies between logically similar parts of the model.        D         1.0
+    4.2  Enable control of basic dependencies between reconstruction cost and reconstruction time. D         1.0
+    4.3  Enable control of basic dependencies between different levels of injuries.                D         1.0
+    4.4  Extend the model to include the description of the hazard (earthquake and hurricane).     D                    1.3
+    4.5  Enable finer control of dependencies through intermediate levels of correlation.          D                    1.3 
+
+    5    **Response estimation**
+    5.1  Fit a multivariate random distribution to samples of EDPs from response simulation.       M         1.0
+    5.2  Allow estimation of EDPs using empirical functions instead of simulation results.         D                    1.2
+    5.3  Perform EDP estimation using the empirical functions in the HAZUS earthquake method       D                    1.2 
+    ==== ========================================================================================= ========= ========== ========
+
+Releases
+--------
+
+Minor releases are planned to follow quarterly cycles while major releases are planned at the end of the third quarter every year:
+
+.. table:: Release schedule
+    :class: tight-table
+
+    ======== =====================
+    version  planned release date
+    ======== =====================
+    1.0      Oct 2018
+    1.1      Dec 2018
+    1.2      March 2019
+    1.3      June 2019
+    2.0      Sept 2019
+    ======== =====================
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/index.rst b/docs/index.rst
@@ -7,16 +7,30 @@
 	:scale: 50%
 	:alt: logo
 
-Probabilistic Estimation of Losses, Injuries, and Community resilience Under Natural disasters 
+Probabilistic Estimation of Losses, Injuries, and Community resilience Under Natural disasters
+
+*pelicun* is a Python package that provides tools for assessment of damage and losses due to natural hazards. It uses a stochastic damage and loss model that is based on the methodology described in FEMA P58 (FEMA, 2012). While FEMA P58 aims to assess the seismic performance of a building, with *pelicun* we want to develop a more versatile, hazard-agnostic tool that will eventually provide loss estimates for other types of assets (e.g. bridges, facilities, pipelines) and lifelines. The underlying loss model was designed with these objectives in mind and it will be gradually extended to have such functionality.
+
+Currently, the scenario assessment from the FEMA P58 methodology is built-in the tool. Detailed documentation of the available methods and their use is available at http://pelicun.readthedocs.io
 
 .. toctree::
    :maxdepth: 1
 
    overview
    installation
+   features
    license
    API documentation <source/pelicun>
 
+License
+=======
+
+*pelicun* is distributed under the BSD 3-Clause license, see LICENSE.
+
+Contact
+=======
+Adam Zsarnóczay, NHERI SimCenter, Stanford University, [email protected]
+
 
 Indices and tables
 ==================

diff --git a/docs/installation.rst b/docs/installation.rst
@@ -1,4 +1,23 @@
 Installation
 ============
 
-pelicun can be installed as a Python package using standard open source software tools.
+*pelicun* is available for Python 2.7 and Python 3.5+ at the Python Package Index (PyPI). You can simply install it using ``pip`` as follows::
+
+	pip install pelicun
+
+
+Requirements
+------------
+The following packages are required for *pelicun*:
+
++---------+-----------------+
+| package | minimum version |
++=========+=================+
+| numpy   | 1.15.1          |
++---------+-----------------+
+| scipy   | 1.1             |
++---------+-----------------+
+| pandas  | 0.20            |
++---------+-----------------+
+
+We recommend installing the Anaconda Python distribution because these packages and many other useful ones are available there.
diff --git a/docs/license.rst b/docs/license.rst
@@ -1,7 +1,7 @@
 
 Copyright and license
 ================================
-The pelicun Python package is copyright through Leland Stanford Junior 
+The *pelicun* Python package is copyright through Leland Stanford Junior 
 University and The Regents of the University of California.
 
 The software is distributed under the BSD 3-Clause License.

diff --git a/docs/overview.rst b/docs/overview.rst
@@ -1,3 +1,12 @@
 Overview
 ========
 
+The current version of *pelicun* can be used to quantifiy lossess from an earthquake scenario in the form of *decision variables*. This functionality is typically utilized for performance based engineering or seismic risk assessment. There are several steps of seismic performance assessment that *pelcicun* can help with:
+
+* **Describe the joint distribution of seismic response.** The response of a structure or other type of asset to an earthquake is typically described by so-called *engineering demand parameters* (EDPs). *pelicun* provides methods that take a finite number of EDP vectors and find a multivarite distribution that describes the joint distribution of EDP data well.
+
+* **Define the damage and loss model of a building.** The component damage and loss data from FEMA P58 is provided with *pelicun*. This makes it easy to define building components without having to provide all the data manually. The stochastic damage and loss model is designed to facilitate modeling correlations between several parameters of the damage and loss model.
+
+* **Estimate component damages.** Given a damage and loss model and the joint distribution of EDPs, *pelicun* provides methods to estimate the quantity of damaged components and collapses.
+
+* **Estimate consequences.** Using information about collapses and component damages, the following consequences can be estimated with the loss model: reconstruction cost and time, unsafe placarding (red tag), injuries and fatalities. 
diff --git a/docs/source/pelicun.rst b/docs/source/pelicun.rst
@@ -9,15 +9,15 @@ API documentation:
     :show-inheritance:
 
 Modules
------------
+-------
 
 .. toctree::
 	:maxdepth: 1
 
-	pelicun.base
-	pelicun.control
-	pelicun.file_io
-	pelicun.model
-	pelicun.uq
+	base <pelicun.base>
+	control <pelicun.control>
+	file_io <pelicun.file_io>
+	model <pelicun.model>
+	uq <pelicun.uq>