# Hazard Disaggregation#

The OpenQuake engine outputs for a disaggregation analysis correspond to projections of the multidimensional probability matrix containing the results of the disaggregation. The currently available projections are 11:

Mag

Dist

Mag_Dist

Mag_Dist_Eps

Lon_Lat

Mag_Lon_Lat

TRT

TRT_Mag

TRT_Lon_Lat

TRT_Mag_Dist

TRT_Mag_Dist_Eps

The user can specify the desired projects in the job.ini file by
setting the parameter disagg_outputs. In the disaggregation demo the
parameter is not set, so all possible outputs are generated.
The demo specifies the parameter individual_rlzs = true, therefore
the results are available for each realization. This is fine for
the demo, where there are only 2 realizations, but in general
specifying individual_rlzs is a *bad* idea, since most models have
thousands of realizations and you would end up exporting a huge
amount of data, with the risk of running out of memory.

By default the engine only export the mean disaggregation. However,
when interested to a specific realization, the user can specify the
realization on which to perform the disaggregation by setting the
`rlz_index`

parameter in the `job.ini`

file.

NB: before version 3.17 the default algorithm used was different: only the realization closest to the mean hazard curve was selected and used perform the disaggregation. This was a choice forced by performance limitations that do not apply to recent versions of the disaggregation calculator, which instead is able to compute all realizations and then perform a weighted mean of the probabilities.

For the disaggregation demo the list of outputs are the following:

```
user@ubuntu:~$ oq engine --lo <calc_id>
id | name
1156 | Disaggregation Outputs Per Realization
1157 | Statistical Disaggregation Outputs
1158 | Full Report
1159 | Hazard Curves
1160 | Realizations
```

Running `--export-output`

to export the disaggregation results will
produce individual files for each site. Since the demo considers 2 sites
you will get 2 x 11 = 22 files for the statistical outputs:

Dist-mean-0_<calc_id>.csv

Dist-mean-1_<calc_id>.csv

Lon_Lat-mean-0_<calc_id>.csv

Lon_Lat-mean-1_<calc_id>.csv

Mag-mean-0_<calc_id>.csv

Mag-mean-1_<calc_id>.csv

Mag_Dist-mean-0_<calc_id>.csv

Mag_Dist-mean-1_<calc_id>.csv

Mag_Dist_Eps-mean-0_<calc_id>.csv

Mag_Dist_Eps-mean-1_<calc_id>.csv

Mag_Lon_Lat-mean-0_<calc_id>.csv

Mag_Lon_Lat-mean-1_<calc_id>.csv

TRT-mean-0_<calc_id>.csv

TRT-mean-1_<calc_id>.csv

TRT_Lon_Lat-mean-0_<calc_id>.csv

TRT_Lon_Lat-mean-1_<calc_id>.csv

TRT_Mag-mean-0_<calc_id>.csv

TRT_Mag-mean-1_<calc_id>.csv

TRT_Mag_Dist-mean-0_<calc_id>.csv

TRT_Mag_Dist-mean-1_<calc_id>.csv

TRT_Mag_Dist_Eps-mean-0_<calc_id>.csv

TRT_Mag_Dist_Eps-mean-1_<calc_id>.csv

Alternatively, you can use the commands

```
user@ubuntu:~$ oq export disagg-rlzs <calc_id>
user@ubuntu:~$ oq export disagg-stats <calc_id>
```

which will produce the same files as the usual `--export-outputs`

.
For instance the disaggregation by magnitude will produce files
like the following for the realizations:

```
#,,,,,"generated_by='OpenQuake engine 3.20.0-git41d16a6e0a'...
imt,iml,poe,mag,rlz1,rlz0
PGA,2.22492E-01,1.00000E-01,5.50000E+00,4.30692E-02,4.30692E-02
PGA,2.22492E-01,1.00000E-01,6.50000E+00,5.97611E-02,5.98033E-02
PGA,2.22492E-01,1.00000E-01,7.50000E+00,2.44507E-04,4.68981E-04
PGA,1.69922E-01,2.00000E-01,5.50000E+00,1.05186E-01,1.05186E-01
PGA,1.69922E-01,2.00000E-01,6.50000E+00,1.06652E-01,1.06838E-01
PGA,1.69922E-01,2.00000E-01,7.50000E+00,7.87177E-04,1.41027E-03
```

The demo contains 3 magnitude bins and `poes_disagg = 0.1 0.2`

, so there
are 6 lines in the CSV. There is a column for each realization but they
are not ordered.

The statistical exporter will produce the following for the means:

```
,,,,"generated_by='OpenQuake engine 3.20.0-git41d16a6e0a'...
imt,iml,poe,mag,mean
PGA,2.22492E-01,1.00000E-01,5.50000E+00,4.30692E-02
PGA,2.22492E-01,1.00000E-01,6.50000E+00,5.97864E-02
PGA,2.22492E-01,1.00000E-01,7.50000E+00,3.79197E-04
PGA,1.69922E-01,2.00000E-01,5.50000E+00,1.05186E-01
PGA,1.69922E-01,2.00000E-01,6.50000E+00,1.06764E-01
PGA,1.69922E-01,2.00000E-01,7.50000E+00,1.16108E-03
```

Most users will expect the disaggregation results to be in the traditional form of Bazzurro and Cornell, 1999. However, the engine does not follow that tradition, as explained in the science manual. Still, we provide a command to export the disaggregation results in the traditional form. Simply write

```
user@ubuntu:~$ oq export disagg-rlzs-traditional <calc_id>
user@ubuntu:~$ oq export disagg-stats-traditional <calc_id>
```

For instance for the realization magnitude output you will get

```
#,,,,,"generated_by='OpenQuake engine 3.20.0-git41d16a6e0a'...
imt,iml,poe,mag,rlz1,rlz0
PGA,2.22492E-01,1.00000E-01,5.50000E+00,4.15754E-01,4.14699E-01
PGA,2.22492E-01,1.00000E-01,6.50000E+00,5.81937E-01,5.80882E-01
PGA,2.22492E-01,1.00000E-01,7.50000E+00,2.30935E-03,4.41874E-03
PGA,1.69922E-01,2.00000E-01,5.50000E+00,4.94599E-01,4.92775E-01
PGA,1.69922E-01,2.00000E-01,6.50000E+00,5.01897E-01,5.00967E-01
PGA,1.69922E-01,2.00000E-01,7.50000E+00,3.50451E-03,6.25733E-03
```

In the traditional format the probabilities compose to 1.0 while in
the engine format the probabilities compose to the PoE listed
in `poes_disagg`

.