# CLI Reference

fordead - Remote sensing time series processing to detect forest anomalies

The usual workflow is : masked_vi --> train_model --> dieback_detection --> forest_mask --> export_results

Usage:

fordead [OPTIONS] COMMAND [ARGS]...


Options:

  --help  Show this message and exit.


Detects anomalies by comparing the vegetation index and its prediction from the model. Detects pixels suffering from dieback when there are 3 successive anomalies. If pixels detected as suffering from dieback have 3 successive dates without anomalies, they are considered healthy again. If stress_index_mode parameter is given, Those periods between detection and return to normal are saved, with the date of first anomaly, date of return to normal, number of dates, and an associated stress index. Anomalies and dieback data are written in the data_directory See details here : https://fordead.gitlab.io/fordead_package/docs/user_guides/english/03_dieback_detection/

Usage:

fordead dieback_detection [OPTIONS]


Options:

  -o, --data_directory TEXT       Path of the output directory
-s, --threshold_anomaly FLOAT   Minimum threshold for anomaly detection
[default: 0.16]
--max_nb_stress_periods INTEGER
Maximum number of stress periods  [default:
5]
--stress_index_mode TEXT        Chosen stress index, if 'mean', the index is
the mean of the difference between the
vegetation index and the predicted
vegetation index for all unmasked dates
after the first anomaly subsequently
confirmed. If 'weighted_mean', the index is
a weighted mean, where for each date used,
the weight corresponds to the number of the
date (1, 2, 3, etc...) from the first
anomaly. If None, the stress periods are not
detected, and no informations are saved.
--vi TEXT                       Chosen vegetation index, only useful if
step1 was skipped
--path_dict_vi TEXT             Path of text file to add vegetation index
formula, only useful if step1 was skipped
--help                          Show this message and exit.


Export results to a vectorized shapefile format.

Usage:

fordead export_results [OPTIONS]


Options:

  -o, --data_directory TEXT       Path of the output directory
--start_date TEXT               Start date for exporting results  [default:
2015-06-23]
--end_date TEXT                 End date for exporting results  [default:
2025-01-02]
--frequency TEXT                Frequency used to aggregate results, if
value is 'sentinel', then periods correspond
to the period between sentinel dates used in
the detection, or it can be the frequency as
used in pandas.date_range. e.g. 'M'
(monthly), '3M' (three months), '15D'
(fifteen days)  [default: M]
--multiple_files                If True, one shapefile is exported for each
period containing the areas in dieback at
the end of the period. Else, a single
shapefile is exported containing diebackd
areas associated with the period of dieback
-t, --conf_threshold_list FLOAT
List of thresholds used as bins to
discretize the confidence index into several
classes
-c, --conf_classes_list TEXT    List of classes names, if
conf_threshold_list has n values,
conf_classes_list must have n+1 values
--help                          Show this message and exit.


Extracts reflectance from Sentinel-2 data using a vector file containing points, exports the data to a csv file. If new acquisitions are added to the Sentinel-2 directory, new data is extracted and added to the existing csv file.

Usage:

fordead extract_reflectance [OPTIONS]


Options:

  --obs_path TEXT              Path to a vector file containing observation
points, must have an ID column corresponding to
name_column parameter, an 'area_name' column
with the name of the Sentinel-2 tile from which
to extract reflectance, and a 'espg' column
containing the espg integer corresponding to
the CRS of the Sentinel-2 tile.
--sentinel_dir TEXT          Path of the directory containing Sentinel-2
data.
--export_path TEXT           Path to write csv file with extracted
reflectance
--name_column TEXT           Name of the ID column  [default: id]
-b, --bands_to_extract LIST  Bands to extract ex : -b B2 -b  B3 -b B11
[default: B2, B3, B4, B5, B6, B7, B8, B8A, B11,
--help                       Show this message and exit.


Usage:

fordead forest_mask [OPTIONS]


Options:

  -o, --data_directory TEXT      Path of the output directory
-f, --forest_mask_source TEXT  Source of the forest mask, can be 'vector' to
use a vector file at vector_path, or the path
to a binary raster of 10m resolution with the
value 1 on the pixels of interest, 'BDFORET'
to use the BD Foret of the IGN, 'OSO' to use
the CESBIO's land use map, or None to not use
a forest mask and to extend the area of
interest to all pixels
--dep_path TEXT                Path to shapefile containg departements with
code insee. Optionnal, only used if
--bdforet_dirpath TEXT         Path to directory containing BD FORET.
equals 'BDFORET'
--list_forest_type TEXT        List of forest types to be kept in the forest
mask, corresponds to the CODE_TFV of the BD
FORET. Optionnal, only used if
[default: FF2-00-00, FF2-90-90, FF2-91-91,
FF2G61-61]
--path_oso TEXT                Path to soil occupation raster, only used if
--list_code_oso INTEGER        List of values used to filter the soil
occupation raster. Only used if
--vector_path TEXT             path of shapefile whose polygons will be
rasterized as a binary raster with
resolution, extent and crs of the raster at
path_example_raster. Only used if
--path_example_raster TEXT     Path to raster from which to copy the extent,
resolution, CRS...
--help                         Show this message and exit.


From previously computed results, graphs the results for specific pixels showing the vegetation index for each dates, the model and the detection. By specifying 'shape_path' and 'name_column' parameters, it can be used with a shapefile containing points with a column containing a unique ID used to name the exported image. By specifying 'x' and 'y' parameters, it can be used with coordinates in the Sentinel-2 data CRS. If neither shape_path or x and y parameters are specified, the user will be prompted to give coordinates in the system of projection of the tile. Graphs can also be plotted for random pixels inside the forest mask. The user can also choose to specify pixels by their indices from the top left hand corner of the computed area (If only a small region of interest was computed (for example by using extent_shape_path parameter in the step 01_compute_masked_vegetationindex (https://fordead.gitlab.io/fordead_package/docs/user_guides/english/01_compute_masked_vegetationindex/)), then create a timelapse on this whole region of interest (https://fordead.gitlab.io/fordead_package/docs/user_guides/Results_visualization/#creer-des-timelapses), then these indices correspond to the indices in the timelapse) The graphs are exported in the data_directory/TimeSeries directory as png files. See details here : https://fordead.gitlab.io/fordead_package/docs/user_guides/Results_visualization/

## Parameters

data_directory x y shape_path name_column ymin ymax chunks

## Returns

Usage:

fordead graph_series [OPTIONS]


Options:

  -o, --data_directory TEXT  Path of the directory containing results from the
region of interest
-x, --x FLOAT              x coordinate in the Sentinel-2 data CRS of the
pixel of interest. Not used if shape_path
parameter is used.
-y, --y FLOAT              y coordinate in the Sentinel-2 data CRS of the
pixel of interest. Not used if shape_path
parameter is used.
--shape_path TEXT          Path to shapefile containing points whose data
will be plotted. If None, indexes or coordinates
for x and y can be given
--name_column TEXT         Name of the column containing the name of the
point, used to name the exported image. Not used
if pixel is selected from indexes or coordinates
--ymin FLOAT               ymin limit of graph
--ymax FLOAT               ymax limit of graph
--chunks INTEGER           Chunk length to import data as dask arrays and
save RAM, advised if computed area in
data_directory is large
--help                     Show this message and exit.


Usage:

fordead masked_vi [OPTIONS]


Options:

  -i, --input_directory TEXT     Path of the directory with Sentinel dates
-o, --data_directory TEXT      Path of the output directory
-n, --lim_perc_cloud FLOAT     Maximum cloudiness at the tile scale, used to
filter used SENTINEL dates. Set parameter as
-1 to not filter based on cloudiness
[default: 0.4]
--interpolation_order INTEGER  interpolation order for bands at 20m
resolution : 0 = nearest neighbour, 1 =
linear, 2 = bilinéaire, 3 = cubique
[default: 0]
--sentinel_source TEXT         Source of data, can be 'THEIA' et 'Scihub' et
'PEPS'  [default: THEIA]
supplier
--soil_detection               If True, bare ground is detected and used as
mask, but the process has not been tested on
other data than THEIA data in France (see htt
is applied.
--formula_mask TEXT            formula whose result would be binary, as
pute_vegetation_index. Is only used if
soil_detection is False.  [default: (B2 >=
700)]
--vi TEXT                      Chosen vegetation index  [default: CRSWIR]
--compress_vi                  Stores the vegetation index as low-resolution
floating-point data as small integers in a
netCDF file. Uses less disk space but can
lead to very small difference in results as
the vegetation is rounded to three decimal
places
--ignored_period LIST          Period whose Sentinel dates to ignore (format
'MM-DD', ex : --ignored_period 11-01
--ignored_period 05-01
--extent_shape_path TEXT       Path of shapefile used as extent of
detection, if None, the whole tile is used
--path_dict_vi TEXT            Path of text file to add vegetation index
formula, if None, only built-in vegetation
indices can be used (CRSWIR, NDVI)
--help                         Show this message and exit.


Attributes intersecting Sentinel-2 tiles to observation points or polygons, adding their epsg and name. If polygons are used, they are converted to grid points located at the centroid of Sentinel-2 pixels. If points or polygons intersect several Sentinel-2 tiles, they are duplicated for each of them. If some intersect no Sentinel-2 tiles, they are removed and their IDs are printed.

Usage:

fordead obs_to_s2_grid [OPTIONS]


Options:

  --obs_path TEXT      Path to a vector file containing observation points or
polygons, must have an ID column corresponding to
name_column parameter
--sentinel_dir TEXT  Path of the directory containing Sentinel-2 data
--export_path TEXT   Path used to write resulting vector file, with added
'epsg','area_name' and 'id_pixel' columns
--name_column TEXT   Name of the ID column  [default: id]
--overwrite          Overwrites file at obs_path
--help               Show this message and exit.


Used as a preprocessing function for a vector file containing observation points or polygons. Can add an ID column if one does not already exist, and can also apply a buffer to erode or dilate observations.

Usage:

fordead preprocess_obs [OPTIONS]


Options:

  --obs_path TEXT     Path of vector file containing observation points or
polygons to preprocess
--export_path TEXT  Path used to export the resulting preprocessed
observation points or polygons
--buffer INTEGER    Length in meters of the buffer used to dilate (positive
integer) or erode (negative integer) the observations.
If None, no buffer is applied. Some observations may
disappear completely if a negative buffer is applied
--name_column TEXT  Name of the column used to identify observations. If the
between 1 and the number of observations  [default: id]
--help              Show this message and exit.


Prints parameters, all dates used and last anomaly date computed to the console

## Parameters

data_directory : str Path of the output directory containing the saved TileInfo object Returns

Usage:

fordead read_tileinfo [OPTIONS]


Options:

  -o, --data_directory TEXT  Path of the output directory containing the saved
TileInfo object
--help                     Show this message and exit.


Automatically downloads all Sentinel-2 data from THEIA between two dates under a cloudiness threshold. Then this data is unzipped, keeping only chosen bands from Flat REflectance data, and zip files can be emptied as a way to save storage space. Finally, if two Sentinel-2 directories come from the same acquisition date, they are merged by replacing no data pixels from one directory with pixels with data in the other, before removing the latter directory.

Usage:

fordead theia_preprocess [OPTIONS]


Options:

  -i, --zipped_directory TEXT     Path of the directory with zipped theia data
-o, --unzipped_directory TEXT   Path of the output directory
-t, --tiles TEXT                Name of the tiles to be downloaded (format :
T31UFQ)
--level [LEVEL1C|LEVEL2A|LEVEL3A]
Product level for reflectance products
[default: LEVEL2A]
--start_date TEXT               start date, fmt('2015-12-22')  [default:
2015-06-23]
--end_date TEXT                 end date, fmt('2015-12-22')  [default:
2023-06-23]
-n, --lim_perc_cloud INTEGER    Maximum cloudiness in SENTINEL dates
-b, --bands TEXT                List of bands to extracted (B2, B3, B4, B5,
B6, B7, B8, B8A, B11, B12, as well as CLMR2,
CLMR2, EDGR1, EDGR2, SATR1, SATR2 for
LEVEL2A data, and DTS1, DTS2, FLG1, FLG2,
WGT1, WGT2 for LEVEL3A)  [default: B2, B3,
B4, B5, B6, B7, B8, B8A, B11, B12, CLMR2]
--correction_type [SRE|FRE|FRC]
Chosen correction type (SRE or FRE for
LEVEL2A data, FRC for LEVEL3A)  [default:
FRE]
--empty_zip                     If True, the zip files are emptied as a way
to save space.
--help                          Show this message and exit.


Create timelapse allowing navigation through Sentinel-2 dates with detection results superimposed. By specifying 'shape_path' and 'name_column' parameters, it can be used with a shapefile containing one or multiple polygons or points with a column containing a unique ID used to name the export. By specifying 'x' and 'y' parameters, it can be used by specifying coordinates in the system of projection of the tile. The timelapse is exported in the data_directory/Timelapses directory as an html file. See details https://fordead.gitlab.io/fordead_package/docs/user_guides/Results_visualization/

## Parameters

data_directory shape_path name_column x y buffer vector_display_path hover_column_list max_date show_confidence_class zip_results

Usage:

fordead timelapse [OPTIONS]


Options:

  -o, --data_directory TEXT   Path of the directory containing results from
the region of interest
--shape_path TEXT           Path of the shapefile of the area, or points, to
convert to timelapse. Not used if timelapse made
from x and y coordinates
--name_column TEXT          Name of the column containing the name of the
export. Not used if timelapse made from x and y
coordinates  [default: id]
-x, --x INTEGER             Coordinate x in the crs of the Sentinel-2 tile.
Not used if timelapse is made using a shapefile
-y, --y INTEGER             Coordinate y in the crs of the Sentinel-2 tile.
Not used if timelapse is made using a shapefile
--buffer INTEGER            Buffer around polygons or points for the extent
of the timelapse  [default: 100]
--vector_display_path TEXT  Path of the shapefile with ground observations
--hover_column_list TEXT    List of columns to display when hovering mouse
over vectors of vector_display_path
--max_date TEXT             Last date used in the timelapse
--show_confidence_class     If True, detected dieback is shown with the
confidence class at the last date used, as
vectorized in the step [05_export_results](https
uides/english/05_export_results/)
--zip_results               If True, puts timelapses in a zip file
--help                      Show this message and exit.


Uses first SENTINEL dates to train a periodic vegetation index model capable of predicting the vegetation index at any date. If there aren't nb_min_date at min_last_date_training, later dates between min_last_date_training and max_last_date_training can be used. See details here : https://fordead.gitlab.io/fordead_package/docs/user_guides/english/02_train_model/

Usage:

fordead train_model [OPTIONS]


Options:

  -o, --data_directory TEXT      Path of the output directory
--nb_min_date INTEGER          Minimum number of valid dates to compute a
vegetation index model for the pixel
[default: 10]
--min_last_date_training TEXT  First date that can be used for detection
[default: 2018-01-01]
--max_last_date_training TEXT  Last date that can be used for training
[default: 2018-06-01]
--correct_vi                   If True, corrects vi using large scale median
vi
--path_vi TEXT                 Path of directory containing vegetation
indices for each date. If None, the
information has to be saved from a previous
step