.. _outputs:

Outputs
=======

There are two alternative ways to get results from the OpenQuake-engine: directly through the calculation or by 
exporting them from the internal OpenQuake engine database once a calculation is completed.

To export outputs directly through the calculation, it is possible to use the flag ``–exports xml``, 
as shown in the example below::

	user@ubuntu:~$ oq engine --run job.ini --exports xml

This will export the results to the ``results`` directory specified in the ``job.ini`` file.

.. _export-hazard-results:

Exporting results from a hazard calculation
-------------------------------------------

To obtain a list of all hazard calculations that have been previously run (successfully or
unsuccessfully), or that are currently running, the following command can be employed:

.. code:: shell-session

   user@ubuntu:~$ oq engine --list-hazard-calculations

or simply:

.. code:: shell-session

   user@ubuntu:~$ oq engine --lhc

Which will display a list of hazard calculations as presented below.

.. code:: shell-session

	user@ubuntu:~$ oq engine --lhc
	job_id | status | start_time | description
	1 | failed | 2013-03-01 09:49:34 | Classical PSHA
	2 | successful | 2013-03-01 09:49:56 | Classical PSHA
	3 | failed | 2013-03-01 10:24:04 | Classical PSHA
	4 | failed | 2013-03-01 10:28:16 | Classical PSHA
	5 | failed | 2013-03-01 10:30:04 | Classical PSHA
	6 | successful | 2013-03-01 10:31:53 | Classical PSHA
	7 | failed | 2013-03-09 08:15:14 | Classical PSHA
	8 | successful | 2013-03-09 08:18:04 | Classical PSHA

*******************************************
Notes on outputs from hazard calculation
*******************************************

The results generated by the OpenQuake-engine are fundamentally of two distinct typologies differentiated by the 
presence (or absence) of epistemic uncertainty in the PSHA input model.

When epistemic uncertainty is incorporated into the calculation, the OpenQuake-engine calculators (e.g. Classical PSHA, 
Event Based PSHA, Disaggregation, UHS) produce a set of results (i.e. hazard curves, ground motion fields, 
disaggregation outputs, UHS, for each logic-tree realisation) which reflects epistemic uncertainties introduced in the 
PSHA input model. For each logic tree sample, results are computed and stored. Calculation of results statistics (mean, 
standard deviation, quantiles) are supported by all the calculators.

By default, OpenQuake will export only the statistical results, i.e. mean curves and quantiles. If the user requires 
the complete results for all realizations, there is a flag to specify, please see the :ref:`FAQ <faq>`.
Beware that if the logic tree contains a large number of end branches the process of exporting the results from each end 
Branch can add a significant amount of time - possibly longer than the computation time - and result in a large volume 
of disk spaced being used. In this case it is best to postprocess the data programmatically. Please contact us and we 
will be happy to give directions on how to do that in Python.

*NOTE:* in the literature there are different algorithms for the computation of the quantiles. The OpenQuake engine uses an 
algorithm based on interpolation which is implemented here:

`gem/oq-engine <https://github.com/gem/oq-engine/tree/engine-3.23/openquake/hazardlib/stats.py>`_

In particular, the median is computed as the q=0.5 quantile.


.. _export-risk-results:

Exporting results from a risk calculation 
-----------------------------------------

To obtain a list of all risk calculations that have been previously run (successfully or
unsuccessfully), or that are currently running, the following command
can be employed:

.. code:: shell-session

   user@ubuntu:~$ oq engine --list-risk-calculations

or simply:

.. code:: shell-session

   user@ubuntu:~$ oq engine --lrc

Which will display a list of risk calculations as presented below.

.. code:: shell-session

   job_id |     status |          start_time |     description
        1 |   complete | 2015-12-02 08:50:30 | Scenario damage example
        2 |     failed | 2015-12-03 09:56:17 | Scenario risk example
        3 |   complete | 2015-12-04 10:45:32 | Scenario risk example
        4 |   complete | 2015-12-04 10:48:33 | Classical risk example
        5 |   complete | 2020-07-09 13:47:45 | Event based risk aggregation example

.. _export-results:

Display list of outputs
-----------------------

To display a list of the outputs from a given job which has completed successfully, 
the following command can be used:

.. code:: shell-session

   user@ubuntu:~$ oq engine --list-outputs <calculation_id>

or simply:

.. code:: shell-session

   user@ubuntu:~$ oq engine --lo <calculation_id>

which will display a list of outputs for the calculation requested, as presented below:

.. code:: shell-session

   Calculation 5 results:
     id | name
     11 | Aggregate Event Losses
      1 | Aggregate Loss Curves
      2 | Aggregate Loss Curves Statistics
      3 | Aggregate Losses
      4 | Aggregate Losses Statistics
      5 | Average Asset Losses Statistics
     13 | Earthquake Ruptures
      6 | Events
      7 | Full Report
     10 | Input Files
     12 | Realizations
     14 | Source Loss Table
     15 | Total Loss Curves
     16 | Total Loss Curves Statistics
     17 | Total Losses
     18 | Total Losses Statistics


Exporting the outputs
---------------------

To export all of the calculation outputs in the default file format 
(csv for most outputs), the following command can be used:

.. code:: shell-session

   user@ubuntu:~$ oq engine --export-outputs <calculation_id> <output_directory>

or simply:

.. code:: shell-session

   user@ubuntu:~$ oq engine --eos <calculation_id> <output_directory>

If, instead of exporting all of the outputs from a particular calculation, 
only particular output files need to be exported, this can be achieved by using the 
``--export-output`` option and providing the id of the required output:

.. code:: shell-session

   user@ubuntu:~$ oq engine --export-output <output_id> <output_directory>

or simply:

.. code:: shell-session

   user@ubuntu:~$ oq engine --eo <output_id> <output_directory>



.. toctree::
   :maxdepth: 2
   :caption: Hazard Outputs:

   classical-psha-outputs
   scenario-analysis-outputs
   event-based-psha-outputs
   disaggregation-outputs

.. toctree::
   :maxdepth: 2
   :caption: Risk Outputs:

   scenario-damage-outputs
   scenario-risk-outputs
   probabilistic-damage-outputs
   probabilistic-risk-outputs
   event-based-risk-outputs
   benefit-cost-ratio-outputs
   infrastructure-risk-outputs
   reinsurance-loss-outputs

.. toctree::
   :maxdepth: 2
   :caption: Secondary Peril Outputs:

   secondary-perils-outputs