<commit_before>In this Chapter we provide a desciption of the main commands available for
running hazard with the \gls{acr:oqe} and the file formats used to represent
the results of the analyses.

A general introduction on the use of the \glsdesc{acr:oqe} is provided in
Chapter~\ref{chap:intro} at page~\pageref{chap:intro}. The
reader is invited to consult this part before diving into the following
sections.


% -----------------------------------------------------------------------------
\section{Running OpenQuake-engine for hazard calculations}
\label{sec:running_hazard_calculations}
\index{Running OpenQuake!hazard}

The execution of a hazard analysis using the OpenQuake-engine is
straightforward. Below we provide an example of the simplest command that can be
used to launch a hazard calculation. It consists in the invocation of \texttt
{oq engine} together with the \texttt{-{}-run} option,
and the name of a configuration file (in the example below it
corresponds to \texttt{job.ini}):

\begin{minted}[firstline=1,linenos=false,firstnumber=1,fontsize=\footnotesize,frame=single,bgcolor=lightgray]{bash}
user@ubuntu:$ oq engine --run job.ini
\end{minted}

The amount of information prompted during the execution of the analysis can be
controlled through the \texttt{-{}-log-level} flag as shown in the example below:

\begin{minted}[firstline=1,linenos=false,firstnumber=1,fontsize=\footnotesize,frame=single,bgcolor=lightgray]{bash}
user@ubuntu:$ oq engine --run job.ini --log-level debug
\end{minted}

In this example we ask the engine to provide an extensive amount of information
(usually not justified for a standard analysis). Alternative options are:
\texttt{debug}, \texttt{info}, \texttt{warn}, \texttt{error},
\texttt{critical}.


% -----------------------------------------------------------------------------
\section{Exporting results from a hazard calculation}
\label{sec:exporting_hazard_results}

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

The first option is defined at the OpenQuake-engine invocation through the flag \texttt{--exports xml}, as shown in the example below:

\begin{minted}[firstline=1,linenos=false,firstnumber=1,fontsize=\footnotesize,frame=single,bgcolor=lightgray]{bash}
user@ubuntu:~$ oq engine --run job.ini --exports xml
\end{minted}

This will export the results to the \verb=results= directory specified in the \verb=job.ini= file. 

The second option allows the user to export the computed results or just a subset of them whenever they want. In order to obtain the list of results of the hazard calculations stored in the \gls{acr:oqe} database the user can utilize the \texttt{-{}-lhc} command (`list hazard calculations') to list the hazard calculations:

\begin{minted}[firstline=1,linenos=false,firstnumber=1,fontsize=\footnotesize,frame=single,bgcolor=lightgray]{bash}
user@ubuntu:~$ oq engine --lhc
\end{minted}

The execution of this command will produce a list similar to the one provided
below (the numbers in red are the calculations IDs):

\input{oqum/hazard/verbatim/output_list_hazard_calcs}

Subsequently the user can get the list of result stored for a specific hazard
analysis by using the \texttt{-{}-list-outputs}, or \texttt{-{}-lo}, command, as in the example below (note that the number in blue emphasizes the
result ID):

\begin{Verbatim}[frame=single, commandchars=\\\{\}, fontsize=\small]
user@ubuntu:~$ oq engine --lo <calc_id>
id | name
\textcolor{blue}{3} | hcurves
\end{Verbatim}

and finally extract an xml file for a specific hazard result:

\begin{Verbatim}[frame=single, commandchars=\\\{\}, fontsize=\small]
user@ubuntu:~$ oq engine --export-outputs <result_id> <output_folder>
\end{Verbatim}


% -----------------------------------------------------------------------------
\section{Description of hazard outputs}
\label{sec:hazard_outputs}

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 matrices, 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 specific command for that, `oq extract hazard/all`.
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.

\subsection{Outputs from Classical PSHA}
\label{subsec:output_classical_psha}
\input{oqum/hazard/02a_output_classical.tex}

\subsection{Outputs from Hazard Disaggregation}
\label{subsec:output_hazard_disaggregation}
\input{oqum/hazard/02b_output_disaggregation.tex}

\subsection{Outputs from Event Based PSHA}
\label{subsec:output_event_based_psha}
\input{oqum/hazard/02c_output_event_based.tex}

\subsection{Outputs from Scenario Hazard Analysis}
\label{subsec:output_scenario_hazard}
\input{oqum/hazard/02d_output_scenario.tex}<commit_msg>Added a note on the computation of quantiles<commit_after>In this Chapter we provide a desciption of the main commands available for
running hazard with the \gls{acr:oqe} and the file formats used to represent
the results of the analyses.

A general introduction on the use of the \glsdesc{acr:oqe} is provided in
Chapter~\ref{chap:intro} at page~\pageref{chap:intro}. The
reader is invited to consult this part before diving into the following
sections.


% -----------------------------------------------------------------------------
\section{Running OpenQuake-engine for hazard calculations}
\label{sec:running_hazard_calculations}
\index{Running OpenQuake!hazard}

The execution of a hazard analysis using the OpenQuake-engine is
straightforward. Below we provide an example of the simplest command that can be
used to launch a hazard calculation. It consists in the invocation of \texttt
{oq engine} together with the \texttt{-{}-run} option,
and the name of a configuration file (in the example below it
corresponds to \texttt{job.ini}):

\begin{minted}[firstline=1,linenos=false,firstnumber=1,fontsize=\footnotesize,frame=single,bgcolor=lightgray]{bash}
user@ubuntu:$ oq engine --run job.ini
\end{minted}

The amount of information prompted during the execution of the analysis can be
controlled through the \texttt{-{}-log-level} flag as shown in the example below:

\begin{minted}[firstline=1,linenos=false,firstnumber=1,fontsize=\footnotesize,frame=single,bgcolor=lightgray]{bash}
user@ubuntu:$ oq engine --run job.ini --log-level debug
\end{minted}

In this example we ask the engine to provide an extensive amount of information
(usually not justified for a standard analysis). Alternative options are:
\texttt{debug}, \texttt{info}, \texttt{warn}, \texttt{error},
\texttt{critical}.


% -----------------------------------------------------------------------------
\section{Exporting results from a hazard calculation}
\label{sec:exporting_hazard_results}

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

The first option is defined at the OpenQuake-engine invocation through the flag \texttt{--exports xml}, as shown in the example below:

\begin{minted}[firstline=1,linenos=false,firstnumber=1,fontsize=\footnotesize,frame=single,bgcolor=lightgray]{bash}
user@ubuntu:~$ oq engine --run job.ini --exports xml
\end{minted}

This will export the results to the \verb=results= directory specified in the \verb=job.ini= file. 

The second option allows the user to export the computed results or just a subset of them whenever they want. In order to obtain the list of results of the hazard calculations stored in the \gls{acr:oqe} database the user can utilize the \texttt{-{}-lhc} command (`list hazard calculations') to list the hazard calculations:

\begin{minted}[firstline=1,linenos=false,firstnumber=1,fontsize=\footnotesize,frame=single,bgcolor=lightgray]{bash}
user@ubuntu:~$ oq engine --lhc
\end{minted}

The execution of this command will produce a list similar to the one provided
below (the numbers in red are the calculations IDs):

\input{oqum/hazard/verbatim/output_list_hazard_calcs}

Subsequently the user can get the list of result stored for a specific hazard
analysis by using the \texttt{-{}-list-outputs}, or \texttt{-{}-lo}, command, as in the example below (note that the number in blue emphasizes the
result ID):

\begin{Verbatim}[frame=single, commandchars=\\\{\}, fontsize=\small]
user@ubuntu:~$ oq engine --lo <calc_id>
id | name
\textcolor{blue}{3} | hcurves
\end{Verbatim}

and finally extract an xml file for a specific hazard result:

\begin{Verbatim}[frame=single, commandchars=\\\{\}, fontsize=\small]
user@ubuntu:~$ oq engine --export-outputs <result_id> <output_folder>
\end{Verbatim}


% -----------------------------------------------------------------------------
\section{Description of hazard outputs}
\label{sec:hazard_outputs}

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 matrices, 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 specific command for that, `oq extract hazard/all`.
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.

NB: 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:

\href{https://github.com/gem/oq-engine/tree/master/openquake/hazardlib/stats.py}{https://github.com/gem/oq-engine/tree/master/openquake/hazardlib/stats.py}

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

\subsection{Outputs from Classical PSHA}
\label{subsec:output_classical_psha}
\input{oqum/hazard/02a_output_classical.tex}

\subsection{Outputs from Hazard Disaggregation}
\label{subsec:output_hazard_disaggregation}
\input{oqum/hazard/02b_output_disaggregation.tex}

\subsection{Outputs from Event Based PSHA}
\label{subsec:output_event_based_psha}
\input{oqum/hazard/02c_output_event_based.tex}

\subsection{Outputs from Scenario Hazard Analysis}
\label{subsec:output_scenario_hazard}
\input{oqum/hazard/02d_output_scenario.tex}
{'fraction_non_alphanumeric': 0.11606048222313037, 'fraction_numerical': 0.0029423784225582348, 'mean_word_length': 4.416555998229305, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 6}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '958667', 'n_tokens_mistral': 3524, 'n_tokens_neox': 3336, 'n_words': 1372}