=============================== Using the |project_name| Plugin =============================== This document describes the useage of the |project_name| 'dock panel' - which is the main interface for running risk scenarios within the Quantum GIS environment. .. note:: In order to use the |project_name| tool effectively, you should probably also read the :doc:`keywords` and :doc:`impact_functions` documentation before you get started. The |project_name| Dock panel is the main way to interact with the tools that are provided in |project_name|. After you have installed the |project_name| plugin, the dock panel will automatically load in QGIS, appearing on the left hand side of the screen. .. figure:: ../static/inasafe-dock-panel.jpeg :align: center You can drag and drop the dock panel to reposition it in the user interface. For example, dragging the panel towards the right margin of the QGIS application will dock it to the right side of the screen. .. figure:: ../static/docked-right.jpeg :align: center There are 3 main areas to the panel: * the :guilabel:`Questions` area * the :guilabel:`Results` area * the buttons area At any time you can obtain help in |project_name| by clicking on the :guilabel:`help` buttons provided on each dock and dialog. The Questions Area ------------------ The intention of InaSAFE is to make it really simple and easy to perform your impact analysis. The question area provides a simple way for you to formulate what it is you want to find out? All questions are formulated in the form: If [**hazard**] how many [**exposure**] might [**impact**]. For example: If **there is a flood** how many **schools** might **be closed**. In order to answer such questions, the |project_name| developers have built a number of **impact functions** that cover scenarios such as flood, tsunami, volcanic ash fall, earthquake and so on. You can read our impact function documentation to find out more information about the various :doc:`impact_functions` implemented. The formulation of these questions if carried out by loading layers into QGIS that represent either **hazard** or **exposure** scenarious. * A **hazard** (:guilabel:`In the event of`) may be represented as, for example, a raster layer in QGIS where each pixel in the raster represents the current flood depth following an inundation event. * An **exposure** (:guilabel:`How many`) layer could be represented, for example, as vector polygon data representing building outlines, or a raster outline where each pixel represents the number of people resident in that cell. The **impact function** (:guilabel:`Might`) will combine these two input layers in a mathematical model in order to postulate what the impacts of the hazard will be on the exposure infrastructure or people. By selecting a combination from the :guilabel:`In the event of` and :guilabel:`How many` combo boxes, an appropriate set of impact functions will be listed in the :guilabel:`Might` combo box. You may be wondering how the |project_name| plugin determines whether a layer should be listed in the :guilabel:`In the event of` or :guilabel:`How many` combo boxes? The plugin relies on simple keyword metadata to be associated with each layer. The keyword system is described in detail in :doc:`keywords`. Each layer that has a keyword allocating it's **category** to **hazard** will be listed in the :guilabel:`In the event of` combo. Similarly, a **category** of **exposure** in the keywords for a layer will result in it being listed under the :guilabel:`How many` combo. |project_name| uses the combination of **category**, **subcategory**, **units** and **datatype** keywords to determine which **impact functions** will be listed in the :guilabel:`Might` combo. The results area ---------------- The :guilabel:`Results` area is used to display various useful feedback items to the user. Once an impact scenario has been run (see next section below), a summary table will be shown. .. figure:: ../static/scenario-results.png :align: center If you select an **impact layer** (i.e. a layer that was produced using an |project_name| impact function), in the QGIS layers list, this summary will also be displayed in the results area. When you select a **hazard** or **exposure** layer in the QGIS layers list, the keywords for that layer will be shown in the :guilabel:`Results` area, making it easy to understand what metadata exists for that layer. .. figure:: ../static/keywords-for-active-layer.png :align: center The :guilabel:`Results` area is also used to display status information. For example, when a suitable combination of **hazard** (:guilabel:`In the event of`), **exposure** (:guilabel:`How many`) and **impact function** (:guilabel:`In the event of`) are selected, the results area will be updated to indicate that you can proceed to run the impact scenario calculation. .. figure:: ../static/status-ready.png :align: center While a scenario is being computed, the :guilabel:`Results` area displays the current progress of the analysis. .. figure:: ../static/calculation-progress.png :align: center Finally, the :guilabel:`Results` area is also used to display any error messages so that the user is informed as to what went wrong and why. .. figure:: ../static/error-display.png :align: center .. note:: At the bottom of error display you may see button like this: .. image:: ../../toggle-traceback.png If you click on this button, it will display a box which will contain useful diagnostic information which can be submitted as part of a bug report if you think the error was incorrect. The buttons area ---------------- The buttons area contains three buttons: * :guilabel:`Help` - click on this if you need context help, such as the document you are reading right now! * :guilabel:`Print...` - click on this if you wish to create a pdf of your impact scenarion project. An **impact layer** must be active before the :guilabel:`Print...` button will be enabled. * :guilabel:`Run` - if the combination of options in the :guilabel:`Questions` area's combo boxes will allow you to run a scenario, this button is enabled. Data conversions when running a scenario ---------------------------------------- When running a scenario, the data being used needs to be processed into a state where it is acceptible for use by the impact function. In particular it should be noted that: * Remote datasets will be copied locally before processing. * All datasets will be clipped to the intersection of the **hazard** layer, the **exposure** layer and the current view extents. * All clipped datasets will be converted (reprojected) to Geographic (EPSG:4326) coordinate reference system before analysis.