Feature/update docs update formatting (#18)

* logo fix * updating documentation * update versioning for LTS only * updates methodologies * fix hyperlink * add Sampling Methodology to index * sampling method update * add toy model link for PLA * updating models * updating documentation * analysis settings schema link fix * Oasis Model section - absolute damage description added * add absolute damage section placeholder * update documatation for model links * update OasisLMF package section * update ODS_tools section * add pre-analysis geocode section * add geocoding section * update geocoding model link * update Oasis Ecosystem image * add gulpy documentation to pytools section * Fix Oasis Eval Fix platform use component table fix * update Oasis Evaluation description * correlation updates * update ecosystem figure * add gulmc documentation to pytools section --------- Co-authored-by: Joh Carter <[email protected]> Co-authored-by: Sam Gamble <[email protected]>
OasisLMF · Oct 12, 2023 · 0aef0f4 · 0aef0f4
1 parent 7127f88
commit 0aef0f4
Show file tree

Hide file tree

Showing 34 changed files with 1,710 additions and 712 deletions.
diff --git a/redoc/analysis_settings/description.md b/redoc/analysis_settings/description.md
@@ -2,6 +2,6 @@
 
 The run time settings for the analysis are controlled by the `analysis_settings.json` file which is a user supplied file detailing all of the options requested for the run (model to run, exposure set to use, number of samples, occurrence options, outputs required, etc.). In the MDK, the analysis settings file must be specified as part of the command line arguments (or in the oasislmf.json configuration file) and in the platform, it needs to be posted to the endpoint. A full json schema for the available options in the analysis settings file can be found here:
 
-https://github.com/OasisLMF/ODS_Tools/blob/develop/ods_tools/data/analysis_settings_schema.json
+https://github.com/OasisLMF/ODS_Tools/blob/main/ods_tools/data/analysis_settings_schema.json
 
 This is useful for more technical users who are looking to create their own UI or integrate Oasis with an existing system. The `analysis_settings` schema hierarchy is shown in `json` format in right column of the page. An interactive version of the schema, with descriptions and examples, can be found below:
diff --git a/redoc/analysis_settings/redoc_template.json b/redoc/analysis_settings/redoc_template.json
@@ -5,7 +5,7 @@
 		"description": "<TEXT HERE>",
 		"version": "<ODS_VERSION>",
 		"x-logo": {
-			"url": "https://oasislmf.github.io/_static/OASIS_LMF_COLOUR.png",
+			"url": "https://oasislmf.github.io/_images/OASIS_LMF_COLOUR.png",
 			"backgroundColor": "#FFFFFF",
 			"altText": "OasisLMF logo"
 		}

diff --git a/redoc/model_settings/redoc_template.json b/redoc/model_settings/redoc_template.json
@@ -5,7 +5,7 @@
 		"description": "<TEXT HERE>",
 		"version": "<ODS_VERSION>",
 		"x-logo": {
-			"url": "https://oasislmf.github.io/_static/OASIS_LMF_COLOUR.png",
+			"url": "https://oasislmf.github.io/_images/OASIS_LMF_COLOUR.png",
 			"backgroundColor": "#FFFFFF",
 			"altText": "OasisLMF logo"
 		}

diff --git a/src/_templates/page.html b/src/_templates/page.html
@@ -53,7 +53,7 @@
       <div class="sidebar-sticky">
         <div class="logo">
           <a href="https://github.com/OasisLMF">
-            <img src="https://oasislmf.github.io/_static/OASIS_LMF_COLOUR.png" alt="{{ 'Oasis Logo' }}" />
+            <img src="https://oasislmf.github.io/_images/OASIS_LMF_COLOUR.png" alt="{{ 'Oasis Logo' }}" />
           </a>
         </div>
         {%- for sidebar_section in sidebars %}

diff --git a/src/home/git-repo.rst b/src/home/git-repo.rst
@@ -91,10 +91,9 @@ OasisAzureDeployment can be used to manage, deploy, run, monitor, and configure
 
 * `OasisEvaluation <https://github.com/OasisLMF/OasisEvaluation>`_
 
-The Oasis Evalutaion repository can be use to spin up an Oasis enviroment to quickly and efficiently run and test models.
-The Oasis Platform release now includes a full API for operating catastrophe models and a general consolidation of the 
-platform architecture. Windows SQL server is no longer a strict requirement. The platform can be run via docker containers 
-on a single machine or, if required, scaled up to run on a cluster.
+The OasisEvaluation repository provides a streamlined way to run the Oasis stack in multi-container environment using 
+docker-compose. This is intended for locally testing the OasisPlatform 1 with a toy model example OasisPiWind, via the Web UI 
+OasisUI.
 
 ----
 

diff --git a/src/home/introduction.rst b/src/home/introduction.rst
@@ -19,7 +19,7 @@ Overview
 
 ----
 
-.. figure:: ../images/oasis_ecosystem.jpg
+.. figure:: ../images/oasis_ecosystem_new.png
     :alt: Oasis Ecosystem
 
     Oasis Ecosystem
@@ -59,44 +59,3 @@ It is designed with a model developer or academic user in mind, who are likely t
 
 **Oasis Model Library** is a hosted catalogue for Oasis models, hosted in AWS. 
 It allows regression of the models after updates to the Oasis Platform code, and validation of model operation and scalability within a hosted Oasis Platform.
-
-
-..
-    This doesn't really work - gets messy having an index inside of the same index
-..    
-    .. toctree::
-        :titlesonly:
-        :caption: Home:
-
-        introduction.rst
-        git-repo.rst
-        FAQs.rst
-
-    .. toctree::
-        :titlesonly:
-        :caption: Use Cases:
-
-        ../use_cases/model-developer
-        ../use_cases/model-users
-        ../use_cases/installing-deploying-Oasis
-
-    .. toctree::
-        :titlesonly:
-        :caption: Sections:
-
-        ../sections/API.rst
-        ../sections/deployment.rst
-        ../sections/errors.rst
-        ../sections/financial-module.rst
-        ../sections/keys-service.rst
-        ../sections/ktools-pytools.rst
-        ../sections/Oasis-evaluation.rst
-        ../sections/Oasis-model-data-formats.rst
-        ../sections/Oasis-models.rst
-        ../sections/Oasis-platform.rst
-        ../sections/Oasis-UI.rst
-        ../sections/Oasis-workflow.rst
-        ../sections/OasisLMF-package.rst
-        ../sections/OED.rst
-        ../sections/options.rst
-        ../ sections/results.rst
diff --git a/src/images/correlation1.png b/src/images/correlation1.png
diff --git a/src/images/correlation2.png b/src/images/correlation2.png
diff --git a/src/images/correlation3.png b/src/images/correlation3.png
diff --git a/src/images/correlation4.png b/src/images/correlation4.png
diff --git a/src/images/oasis_ecosystem_new.png b/src/images/oasis_ecosystem_new.png
diff --git a/src/images/plat2_arch.png b/src/images/plat2_arch.png
diff --git a/src/images/sampling1.png b/src/images/sampling1.png
diff --git a/src/images/sampling2.png b/src/images/sampling2.png
diff --git a/src/index.rst b/src/index.rst
@@ -19,7 +19,7 @@ Overview
 
 ----
 
-.. figure:: images/oasis_ecosystem.jpg
+.. figure:: images/oasis_ecosystem_new.png
     :alt: Oasis Ecosystem
 
     Oasis Ecosystem
@@ -82,13 +82,15 @@ It allows regression of the models after updates to the Oasis Platform code, and
     :titlesonly:
     :caption: Sections:
 
+    sections/absolute-damage.rst
     sections/analysis_settings
     sections/API.rst
     sections/camel.rst
     sections/correlation.rst
     sections/deployment.rst
     sections/disaggregation.rst
     sections/financial-module.rst
+    sections/geocoding.rst
     sections/keys-service.rst
     sections/ktools.rst
     sections/model-data-library.rst
@@ -111,12 +113,14 @@ It allows regression of the models after updates to the Oasis Platform code, and
     sections/platform_1
     sections/platform_2
     sections/post-loss-amplification.rst
+    sections/pre-analysis-adjustments.rst
     sections/pytools.rst
     sections/releases.rst
     sections/results.rst
     sections/SaaS-providers.rst
+    sections/sampling-methodology.rst
     sections/versioning.rst
 
 .. 
-  sections to be populated: sections/pre-analysis-adjustments.rst, sections/sampling-methodology.rst, sections/errors.rst
+  sections to be populated: sections/pre-analysis-adjustments.rst, sections/errors.rst, sections/complex-model.rst
 
diff --git a/src/sections/API.rst b/src/sections/API.rst
@@ -17,10 +17,9 @@ Introduction:
 
 ----
 
-Oasis has a full REST API for managing exposure data and operating modelling workflows. API Swagger documentation can be 
-found `here <http://api.oasislmfdev.org/swagger/>`_. An evaluation version of the Oasis platform and using can be deployed 
-using the `Oasis evaluation repository <https://github.com/OasisLMF/OasisEvaluation>`_. This includes a Jupyter notebook 
-that illustrates the basic operation of the API, using the Python API client.
+An evaluation version of the Oasis platform and using can be deployed using the `Oasis evaluation repository 
+<https://github.com/OasisLMF/OasisEvaluation>`_. This includes a Jupyter notebook that illustrates the basic 
+operation of the API, using the Python API client.
 
 The API schemas can be found here:
 

diff --git a/src/sections/ODS-tools.rst b/src/sections/ODS-tools.rst
@@ -23,8 +23,8 @@ ODS Tools is a Python package designed to manage :doc:`../../sections/ODS` data,
 :doc:`ODS <../../sections/ODS>` schema. It includes a range of tools for working with Oasis data files, including loading, 
 conversion, and validation. This package is in accordance with :doc:`ODS <../../sections/ODS>`. 
 
-As a separate service, the package include functionality to manage :doc:`../../sections/model-settings` and 
-:doc:`../../sections/analysis-settings` that are used to perform an analysis.
+As a separate service, the package include functionality to manage :doc:`../../sections/model_settings` and 
+:doc:`../../sections/analysis_settings` that are used to perform an analysis.
 
 ODS tools comprises primarily of two parts:
 
@@ -103,7 +103,7 @@ ODS Tools can be installed via pip by running the following command:
     pip install ods-tools
 |
 
-Once installed, ODS Tools can be used utilised via the command line interface to quickly convert oed files.
+Once installed, ODS Tools can be used via the command line interface to quickly convert oed files.
 
 Example :
 

diff --git a/src/sections/Oasis-evaluation.rst b/src/sections/Oasis-evaluation.rst
@@ -1,18 +1,63 @@
 Oasis Evaluation
 ================
 
-The Oasis Evalutaion repository can be use to spin up an Oasis enviroment to quickly and efficiently run and test models.
-The Oasis Platform release now includes a full API for operating catastrophe models and a general consolidation of the 
-platform architecture. Windows SQL server is no longer a strict requirement. The platform can be run via docker containers 
-on a single machine or, if required, scaled up to run on a cluster.
+The OasisEvaluation repository provides a streamlined way to run the Oasis stack in multi-container environment using docker-compose.
+This is intended for locally testing the `OasisPlatform 1 <https://github.com/OasisLMF/OasisPlatform/tree/main-platform1>`_ with a toy model example `OasisPiWind <https://github.com/OasisLMF/OasisPiWind>`_, via the Web UI `OasisUI <https://github.com/OasisLMF/OasisUI>`_.
+
+
+
+.. _installing_oasis:
+
+Installing Oasis
+****************
+
+1. Install prerequisites, ``docker``, ``docker-compose``, and ``git``
+2. (optional) Edit the software versions at the top of ``install.sh`` installation script, These control the oasis versions installed
+
+|
+.. code-block:: python
+
+    export VERS_API=1.28.0
+    export VERS_WORKER=1.28.0
+    export VERS_UI=1.11.6
+    export VERS_PIWIND='stable/1.28.x'
+|
+
+These control the oasis versions installed
+ - ``VERS_API``, OasisPlatform server version
+ - ``VERS_WORKER``, OasisPlatform worker version
+ - ``VERS_UI``, OasisUI container version
+ - ``VERS_PIWIND``, the PiWind branch to run.
+
+3. Run the installaion script
+
+|
+.. code-block:: python
+
+    ./install.sh
+|
+
+
+
+
+----
+
+Oasis Installation Guide: Windows 10 OS
+#######################################
+
+..  youtube:: SxRt5E-Y5Sw
+
+|
+Oasis Installation Guide: Linux based OS
+########################################
+
+..  youtube:: OFLTpGGEM10
+
 
-Docker support is the main requirement for running the platform. A Linux based installation is the main focus of this 
-example deployment. Running the install script from this repository automates install process of the OasisPlatform API v1, 
-User Interface and example PiWind model.
 
 GitHub repository:
 ------------------
 
 ----
 
-`Oasis Platform Evaluation <https://github.com/OasisLMF/OasisEvaluation#readme>`_.
+`Oasis Platform Evaluation <https://github.com/OasisLMF/OasisEvaluation#readme>`_.
diff --git a/src/sections/Oasis-models.rst b/src/sections/Oasis-models.rst
@@ -28,13 +28,17 @@ This is a single event model which allows users to apply deterministic losses to
 in the OED location file. It is similar to the ``exposure`` feature in the oasislmf package, but can be deployed as a model in 
 it's own right to model deterministic losses which can then be passed through the Oasis financial module.
 
+This model is availible to use `here <https://github.com/OasisLMF/OasisModels/tree/develop/DeterministicModel>`_.
+
 ----
 
 Paris Windstorm
 ****************
 
 This is very small, single peril model used for demonstration of how to build a simple model in Oasis.
 
+This model is availible to use `here <https://github.com/OasisLMF/OasisModels/tree/develop/ParisWindstorm>`_.
+
 ----
 
 PiWind
@@ -43,16 +47,33 @@ PiWind
 This is the original test model in Oasis and is an example of a multi-peril model implementation representing ficticious 
 events with wind and flood affecting the Town of Melton Mowbray in England.
 
+This model is availible to use `here <https://github.com/OasisLMF/OasisModels/tree/develop/PiWind>`_.
+
 More information on this model can be found here: :ref:`piwind_models`
 
 ----
 
+PiWind Absolute Damage
+**********************
+
+This model expands upon the PiWind model with the absolute damage option. This option allows model providers to include 
+absolute damage amounts rather than damage factors in the damage bin dictionary. If the damage factors are less than or 
+equal to 1 in the damage bin dictionary, the factor will be applied as normal during the loss calculation, by applying the 
+sampled damage factor to the TIV to give a simulated loss; but with absolute damage factors, where the factor is greater 
+than 1, the TIV is not used in the calculation at all, but rather the absolute damage is applied as the loss.
+
+This model is availible to use from `here <https://github.com/OasisLMF/OasisModels/tree/develop/PiWindAbsoluteDamage>`_.
+
+----
+
 PiWind Complex Model
 ********************
 
 This is a version of the PiWind model which uses the complex model integreation approach to generate ground up losses in a 
 custoim module, which then sits in the workflow and replaces the standard ground up loss calculation from Oasis.
 
+This model is availible to use from `here <https://github.com/OasisLMF/OasisModels/tree/develop/PiWindComplexModel>`_.
+
 ----
 
 PiWind Postcode
@@ -61,6 +82,32 @@ PiWind Postcode
 This is a variant of the original PiWind model designed for running exposures whose locations are known at postcode level 
 rather than by latitude and longitude. This model demonstrates the disaggregation features of Oasis.
 
+This model is availible to use `here <https://github.com/OasisLMF/OasisModels/tree/develop/PiWindPostcode>`_.
+
+----
+
+PiWind Post Loss Amplification
+******************************
+
+This is a version of the PiWind model with post loss amplification factors applied. Major catastrophic events can 
+give rise to inflated and/or deflated costs depending on that specific situation. To account for this, the ground up 
+losses produced by the GUL calculation component are multiplied by post loss amplification factors, by the component 
+plapy.
+
+This model is availible to use `here <https://github.com/OasisLMF/OasisModels/tree/develop/PiWindPostLossAmplification>`_.
+
+----
+
+PiWind Post Pre Analysis
+************************
+
+This model builds upon the original PiWind model with a pre-analysis adjustment hook. This step allows the user to modify input 
+files before they are processed in the analysis. This functionality is utilised by this model by implementing an external geocoder: 
+this checks the location data before it is analysed for any addresses that are missing OED location data. If an address is found t
+o be incomplete, it is geocoded to fill these gaps.
+
+This model is availible to use `here <https://github.com/OasisLMF/OasisModels/tree/develop/PiWindPreAnalysis>`_.
+
 ----
 
 PiWind Single Peril
@@ -69,14 +116,12 @@ PiWind Single Peril
 This is a simplified variant of the original PiWind model which has single peril (wind only) and would be a good basis for 
 a single peril model in Oasis.
 
-|
-
-.. note::
-    More information about these models can be found `here <https://github.com/OasisLMF/OasisModels/tree/develop>`_.
-
+This model is availible to use `here <https://github.com/OasisLMF/OasisModels/tree/develop/PiWindSinglePeril>`_.
 
 ----
 
+.. note::
+    More information about these models can be found `here <https://github.com/OasisLMF/OasisModels/tree/develop>`_.
 |
 
 .. _piwind_models:
@@ -87,8 +132,9 @@ PiWind - toy model
 ----
 
 Oasis has developed a toy model, PiWind, available `here <https://github.com/OasisLMF/OasisPiWind>`_. PiWind is a wind storm 
-model for a small area of the UK.The data is mocked up to illustrate the Oasis data formats and functionality, and is not 
-meant to be a usable risk model.
+model for a small area of the UK. The data is mocked up to illustrate the Oasis data formats and functionality, and is not 
+meant to be a usable risk model. The PiWind toy model is availible to use from `here <https://github.com/OasisLMF/
+OasisModels/tree/develop/PiWind>`_.
 
 There are three main components to a catastrophe risk model deployed in Oasis. A fuller discussion of the components of a 
 hazard model can be found in :doc:`modelling-methodology`.