Quickstart
**********

Introduction
============

The nrt package provides near real-time disturbance monitoring algorithms for spatio-temporal datasets.

The following algorithms are implemented:

- EWMA (Brooks et al., 2013) [1]_
- CUSUM (Verbesselt et al., 2012) [2]_
- MOSUM (Verbesselt et al., 2012) [2]_
- CCDC (Zhu et al., 2012; 2014) [3]_ [4]_
- IQR

For more information on the basic function of each monitoring method see :ref:`classes`.

Installation
============

Install the package from pypi using:

.. code-block::

	pip install nrt

Workflow
========

In general a workflow with the `nrt` package can be divided into three parts: 
Instantiating, Fitting and Monitoring.

Instantiating
-------------

.. code-block:: python

    from nrt.monitor.ewma import EWMA
    from nrt import data

    # load example mask
    mask = (data.romania_forest_cover_percentage() > 20).astype('int')

    # Instantiate
    nrt_class = EWMA(
        mask=mask,
        trend=True,
        harmonic_order=3,
        sensitivity=2
    )

Here, the monitoring class ``EWMA`` is imported. Along with that a forest mask
is constructed. This mask is optional but must have the same shape as the data array which is
later supplied for fitting.

All available monitoring classes accept the parameters ``mask``, ``trend``, ``harmonic_order``
and ``sensitivity``. Some monitoring classes also accept additional parameters.
For more information see :ref:`classes`.

.. note::
    ``sensitivity`` takes different values depending on the monitoring class.
    For example larger ``sensitivity`` values mean higher sensitivity for ``EWMA``,
    but lower sensitivity for ``MoSum``.



Fitting
-------------

.. code-block:: python
    
    # load example xarray
    s2_cube = data.romania_20m()
    history = s2_cube.B03.sel(time=slice(None, '2019-01-01'))
    monitor = s2_cube.B03.sel(time=slice('2019-01-01', None))

    # Fitting
    nrt_class.fit(dataarray=history)

    # Dump model
    nrt_class.to_netcdf('model.nc')

In this example some sample data is created first, which is used for fitting and 
later for monitoring. 
``.fit()`` has only one non optional parameter ``dataarray`` which expects an 
``xarray.DataArray``. During fitting there are other optional parameters which can be set. 
See :ref:`fitting` for more detail.

If the next observation is not immediately available, the model can be dumped
to a NetCDF file which can then be loaded once the next observation is available.

Monitoring
-------------

.. code-block:: python
    
    # Load dumped model
    nrt_class = EWMA.from_netcdf('model.nc')

    # Monitor new observations
    for array, date in zip(monitor.values, monitor.time.values.astype('datetime64[s]').tolist()):
        nrt_class.monitor(array=array, date=date)

    # Report results
    nrt_class.report('report.tif')

If the model was dumped to a NetCDF it can be read from disk with ``from_netcdf()``.
Monitoring happens with ``.monitor()``. This only takes an numpy array and a date of class
``datetime.date``. 

At any time during monitoring a report can be generated by calling 
``.report()``. This report returns a GeoTIFF with two bands, one showing the status 
of all pixels (e.g. not monitored, disturbed, etc.) and another band showing the date when 
a disturbance was detected in days since 1970-01-01.

References
==========

.. [1] Brooks, E.B., Wynne, R.H., Thomas, V.A., Blinn, C.E. and Coulston, J.W., 2013.
       On-the-fly massively multitemporal change detection using statistical quality control charts and Landsat data.
       IEEE Transactions on Geoscience and Remote Sensing, 52(6), pp.3316-3332.
       https://doi.org/10.1109/TGRS.2013.2272545

.. [2] Verbesselt, J., Zeileis, A. and Herold, M., 2012.
       Near real-time disturbance detection using satellite image time series.
       Remote Sensing of Environment, 123, pp.98-108.
       https://doi.org/10.1016/j.rse.2012.02.022

.. [3] Zhu, Z., Woodcock, C.E. and Olofsson, P., 2012.
       Continuous monitoring of forest disturbance using all available Landsat imagery.
       Remote sensing of environment, 122, pp.75-91.
       https://doi.org/10.1016/j.rse.2011.10.030

.. [4] Zhu, Z. and Woodcock, C.E., 2014.
       Continuous change detection and classification of land cover using all available Landsat data.
       Remote sensing of Environment, 144, pp.152-171.
       https://doi.org/10.1016/j.rse.2014.01.011