==========
Quickstart
==========

.. role:: python(code)
   :language: python

Simple Heat Flow and Anomaly Analysis
-------------------------------------

A quick analysis can be done using just a few commands. This assumes that
the heat flow data has already been loaded to the variables :python:`hf_x`,
:python:`hf_y`, and :python:`hf_mWm2`, where the former are the data point
coordinates in a map-projected coordinate system and the latter is an array
of the heat flow data (in :math:`\mathrm{mWm}^{-2}`). For instance, the data
could be loaded from the NGHF [L2019]_ using the :py:mod:`reheatfunq.data`
module. All arrays are assumed to be one-dimensional continuous numpy arrays.

First, perform the necessary imports:

.. code :: python

   import numpy as np
   import matplotlib.pyplot as plt
   from reheatfunq.regional import (default_prior,
                                    HeatFlowPredictive)
   from reheatfunq.anomaly import (HeatFlowAnomalyPosterior,
                                   AnomalyLS1980)

Obtain the default :py:class:`~reheatfunq.regional.GammaConjugatePrior` and
compute the predictive cumulative distribution function, that is, the estimate
of the regional aggregate heat flow distribution:

.. code :: python

   gcp = default_prior()
   predictive = HeatFlowPredictive(hf_mWm2, hf_x, hf_y, gcp,
                                   dmin=20e3)

   qplt = np.linspace(30, 90)
   cdf = predictive.cdf(qplt)

Now :python:`qplt` is a range of heat flow values from
:math:`30\,\mathrm{mWm}^{-2}` to :math:`90\,\mathrm{mWm}^{-2}`, and
:python:`cdf` holds the corresponding values of the estimated heat flow CDF.

Fault-generated heat flow anomaly
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Let's assume that the variable :python:`fault_trace` is a :python:`(N,2)`-shaped
NumPy array that holds the consecutive coordinates of a fault trace
:python:`[(x0,y0), ..., (xN,yN)]`. We would like to investigate the strength of
the potential heat flow anomaly generated by this fault. Let's assume
furthermore that we are content with approximating the heat conduction from that
fault by the :py:class:`~reheatfunq.anomaly.AnomalyLS1980` class (implying that
in the relevant vicinity of the data the fault is vertical and straight, and
heat transport conductive, and that heat production increases linearly with
depth). Finally, let :python:`D` be the uniform depth of the fault in meters.

Then we can use the following code to quantify the heat-generating power on the
fault through the heat flow anomaly strength:

.. code :: python

   anomaly = AnomalyLS1980(fault_trace, D)
   post = HeatFlowAnomalyPosterior(hf_mWm2, hf_x, hf_y, anomaly,
                                   gcp)

   P_H = np.linspace(0, post.PHmax, 200)
   pdf_P_H = post.pdf(P_H)
   tail_P_H = post.tail(P_H)

The parameter :python:`post.PHmax` is the maximum heat production power on the
fault, that is, for all greater powers the posterior has zero probability
density. The variables :python:`pdf_P_H` and :python:`tail_P_H` now hold the
marginal posterior density and tail distribution, respectively, of the heat
production power :math:`P_H`.

A readymade Jupyter notebook for this analysis can be found in
`jupyter/Quickstart.ipynb
<https://github.com/mjziebarth/REHEATFUNQ/blob/master/jupyter/Quickstart.ipynb>`_.


REHEATFUNQ Paper
----------------
To repeat the analysis performed in the REHEATFUNQ paper, you can use the
notebooks prefixed **01** to **06** in the
`jupyter/REHEATFUNQ/
<https://github.com/mjziebarth/REHEATFUNQ/blob/master/jupyter/REHEATFUNQ/>`_
folder.