This page provides documentation for our command line tools.
fordead - Remote sensing time series processing to detect forest anomalies
The usual workflow is : masked_vi --> train_model --> dieback_detection --> forest_mask --> export_results
fordead [OPTIONS] COMMAND [ARGS]...
--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/
fordead dieback_detection [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.
fordead export_results [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: 2022-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 [default: False] -t, --conf_threshold_list LIST List of thresholds used as bins to discretize the confidence index into several classes -c, --conf_classes_list LIST 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.
Compute forest mask from IGN's BDFORET or CESBIO's OSO map See details here : https://fordead.gitlab.io/fordead_package/docs/user_guides/english/04_compute_forest_mask/
fordead forest_mask [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 forest_mask_source equals 'BDFORET' --bdforet_dirpath TEXT Path to directory containing BD FORET. Optionnal, only used if forest_mask_source 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 forest_mask_source equals 'BDFORET' [default: FF2-00-00, FF2-90-90, FF2-91-91, FF2G61-61] --path_oso TEXT Path to soil occupation raster, only used if forest_mask_source = 'OSO' --list_code_oso INTEGER List of values used to filter the soil occupation raster. Only used if forest_mask_source = 'OSO' [default: 17] --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 forest_mask_source = 'vector' --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/
fordead graph_series [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.
Computes masks and masked vegetation index for each SENTINEL date under a cloudiness threshold. The mask includes pixels ouside satellite swath, some shadows, and the mask from SENTINEL data provider if the option is chosen. Also, if soil detection is activated, the mask includes bare ground detection and cloud detection, but the process might only be adapted to THEIA data in France's coniferous forests. If it is not activated, then the user can choose a mask of his own using the formula_mask parameter. Results are written in the chosen directory. See details here : https://fordead.gitlab.io/fordead_package/docs/user_guides/english/01_compute_masked_vegetationindex/
fordead masked_vi [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] --apply_source_mask If True, applies the mask from SENTINEL-data supplier [default: False] --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 ps://fordead.gitlab.io/fordead_package/docs/u ser_guides/english/01_compute_masked_vegetati onindex/). If False, mask from formula_mask is applied. [default: False] --formula_mask TEXT formula whose result would be binary, as described here https://fordead.gitlab.io/ford ead_package/reference/fordead/masking_vi/#com pute_vegetation_index. Is only used if soil_detection is False. [default: (B2 >= 700)] --vi TEXT Chosen vegetation index [default: CRSWIR] --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.
Prints parameters, all dates used and last anomaly date computed to the console
fordead read_tileinfo [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.
fordead theia_preprocess [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) --login_theia TEXT Login of your theia account --password_theia TEXT Password of your theia account --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 downloaded (%) [default: 50] -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. [default: False] --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/
fordead timelapse [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 ://fordead.gitlab.io/fordead_package/docs/user_g uides/english/05_export_results/) [default: False] --zip_results If True, puts timelapses in a zip file [default: False] --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/
fordead train_model [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 [default: False] --path_vi TEXT Path of directory containing vegetation indices for each date. If None, the information has to be saved from a previous step --path_masks TEXT Path of directory containing masks for each date. If None, the information has to be saved from a previous step --help Show this message and exit.