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)

  • CUSUM (Verbesselt et al., 2012)

  • MOSUM (Verbesselt et al., 2012)

  • CCDC (Zhu et al., 2014)

  • IQR

For more information on the basic function of each monitoring method see Monitoring Classes.

Installation

Install the package from pypi using:

pip install nrt

Workflow

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

Instantiating

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 Monitoring 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

# load example xarray
s2_cube = data.romania_20m()
history = s2_cube.B3.sel(slice(None, '2019-01-01'))
monitor = s2_cube.B3.sel(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 Fitting & Outlier Screening 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

# 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.