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.