How-To
######

.. Contents::

This tutorial shows how to use VG in an ipython shell. The data used for the examples is provided in the ``sample.met`` file. Everything here should work without any changes to the ``config_template.py`` file.

Another tutorial shows how to configure VG to use other data.

Initialization
**************

.. ipython::
    :okwarning:
    :okexcept:

    In [1]: from varwg import VarWG

    In [2]: my_vg = VarWG(("theta", "Qsw", "ILWR", "rh", "u", "v"))

Initialization involves converting the input to stationary, standard- normal distributed variables via day-of-year-specific quantile-quantile transform. As this is time-consuming, the fitting results are cached on the hard-drive (in the ``conf.cache_dir`` to be exact).

More information on all the initialization parameters: :func:`varwg.VarWG.__init__`.

The :class:`varwg.VarWG` class provides a number of methods for plotting various results. To see the input time series one can use :func:`varwg.VarWG.plot_timehists`:

.. ipython::
    :okwarning:
    :okexcept:

    @savefig meteogram.png
    In [3]: figs, axes = my_vg.plot_meteogram_daily(figsize=(8, 6))

The fitting of the daily seasonal distribution can be visualized with :func:`varwg.VarWG.plot_daily_fit`:

.. ipython::
    :okwarning:
    :okexcept:

    # the plot_quantiles and plot_fourier parameters can be omitted in order to
    # get more information on the fitting.
    @savefig seasonal_fit_theta.png
    In [3]: my_vg.plot_daily_fit("theta", plot_quantiles=False, plot_fourier=False)

    # if the fit is good, the histogram of the quantiles should be roughly
    # uniformly distributed
    @savefig seasonal_fit_theta_quantiles.png
    In [4]: my_vg.plot_daily_fit("theta", plot_fourier=False)

If you are not satisfied with the conversion, adjust the settings in ``config.py`` and initialize VG again with the ``refit``-parameter:

.. ipython::
    :okwarning:
    :okexcept:

    In [3]: my_vg = VarWG(("theta", "Qsw", "ILWR", "rh", "u", "v"), refit="ILWR", verbose=False)
    
    # you can also supply multiple variables to refit
    In [4]: my_vg = VarWG(("theta", "Qsw", "ILWR", "rh", "u", "v"), refit=("ILWR", "rh"), verbose=False) 

Fitting
*******

Calling :func:`varwg.VarWG.fit` fits the stochastic process to the transformed data. When called without parameters, an order selection is performed to find a good compromise between the fit and the number of parameters. Per default, the moving average part is neglected (``q=0``).

.. ipython::
    :okwarning:
    :okexcept:

    In [3]: my_vg.fit()

    # the autoregressive order can be fixed like this
    In [7]: my_vg.fit(3)

Simulation
**********

Without parameters, :func:`varwg.VarWG.simulate` generates time series similar to the input data.

.. ipython::
    :okwarning:
    :okexcept:

    In [8]: times_out, sim_data = my_vg.simulate()

The output is also stored in the ``out_dir`` (specified in ``config.py``) as text file.

At this point it can be assessed whether the order selection was successful. :func:`varwg.VarWG.plot_autocorr` provides a shortcut to plot the autocorrelations of residuals, measured (continuous line) and simulated (dashed line) data (in the "real" and the "transformed" domain)

.. ipython::
    :okwarning:
    :okexcept:

    # in a real ipython shell one call to plot_autocorr suffices. here i have
    # to hack to get all figures
    @savefig autocorr_stale_1.png
    In [9]: figs = my_vg.plot_autocorr()

    @savefig autocorr_stale_2.png
    In [9]: varwg.plt.figure(5)
    
Would the fit have been less good, one could consider calling :func:`varwg.VarWG.fit` again with a higher ``p``.

Scenarios
=========

Scenarios are implemented through changes based on the primary variable (default: air temperature). The primary variable can be specified by the parameter ``primary_var`` in :func:`varwg.VarWG.simulate`.

Increased mean (``theta_incr``)
-------------------------------

.. ipython::
    :okwarning:
    :okexcept:

    In [9]: times_out, sim_data = my_vg.simulate(theta_incr=4)

    # we can display the result like we did above with the input data
    @savefig meteogram_sim_theta.png
    In [10]: figs, axes = my_vg.plot_meteogram_daily()

Another way to visualize the simulation is offered by the method :func:`varwg.VarWG.plot_doy_scatter`:

.. ipython::
    :okwarning:
    :okexcept:

    @savefig doy_scatter_theta.png
    In [12]: my_vg.plot_doy_scatter("theta", figsize=(8, 4))


Increased variability via enhanced episodes (``mean_arrival`` and ``disturbance_std``)
--------------------------------------------------------------------------------------

For increased variability, a Poisson-process is used to set the theoretical mean of the autoregressive process. Durations of episodes are drawn from an exponential distribution with the mean specified as ``mean_arrival``. For each episode, a disturbance is drawn from a normal distribution with the standard deviation of ``disturbance_std``.

.. ipython::
    :okwarning:
    :okexcept:

    In [11]: times_out, sim_data = my_vg.simulate(mean_arrival=7, disturbance_std=4)


Providing a climate signal (``climate_signal``)
-----------------------------------------------

VG can be made to follow a specific signal by passing an array with the ``climate_signal`` parameter.

Output
======

:func:`varwg.VarWG.simulate` dumps the generated time series in the ``out_dir`` (specified in ``config.py``) as an ascii file. The filename is chosen by the fitting parameters (Example: ``VARMA_p3_q0_sim.dat``)

Disaggregation
**************

See :func:`varwg.VarWG.disaggregate`

.. ipython::
    :okwarning:
    :okexcept:

    In [12]: times_dis, sim_dis = my_vg.disaggregate(("Qsw", "u", "v"))

Disaggregation also regenerates the seasonal changes in daily cycle.

.. ipython::
    :okwarning:
    :okexcept:

    @savefig daily_cycles.png
    In [13]: fig, axes = my_vg.plot_daily_cycles("Qsw")

Tips
****

- Caching: Once you change anything in the met_file you have to empty the cache! To empty the cache, simply delete everything in the ``cache_dir`` (specified in ``config.py``) or call the function :func:`varwg.delete_cache`