Create all possible graphical representations for a FATE simulation

This script is designed to produce a set of graphical representations for a FATE simulation. Graphics can be of three types : 1) representing an evolution through time (of abundance, light, soil) ; 2) visualizing the goodness of the modelisation (presence/absence, validation statistics) : 3) or representing a spatial distribution for a specific year (richness, abundance, light, soil).

POST_FATE.graphics(
  name.simulation,
  file.simulParam = NULL,
  years,
  no_years,
  opt.ras_habitat = NULL,
  doFunc.evolCov = TRUE,
  doFunc.evolPix = TRUE,
  doFunc.evolStab = TRUE,
  evolPix.cells_ID = NULL,
  evolStab.mw_size = 3,
  evolStab.mw_step = 1,
  evol.fixedScale = TRUE,
  doFunc.valid = TRUE,
  valid.mat.PFG.obs,
  doFunc.mapPFGvsHS = TRUE,
  doFunc.mapPFG = TRUE,
  mapPFGvsHS.stratum = "all",
  binMap.method,
  binMap.method1.threshold = 0.05,
  binMap.method2.cutoff = NULL,
  mapPFG.stratum_min = 1,
  mapPFG.stratum_max = 10,
  mapPFG.doBinary = TRUE,
  opt.doPlot = TRUE,
  opt.no_CPU = 1
)

Arguments

name.simulation

a string corresponding to the main directory or simulation name of the FATE simulation

file.simulParam

default NULL.
A string corresponding to the name of a parameter file that will be contained into the PARAM_SIMUL folder of the FATE simulation

years

an integer, or a vector of integer, corresponding to the simulation year(s) that will be used to extract PFG abundance maps (see POST_FATE.relativeAbund, POST_FATE.graphic_validationStatistics, POST_FATE.graphic_mapPFGvsHS)

no_years

an integer corresponding to the number of simulation years that will be used to extract PFG abundance / light / soil maps (see POST_FATE.temporalEvolution)

opt.ras_habitat

(optional) default NULL.
A string corresponding to the file name of a raster mask, with an integer value within each pixel, corresponding to a specific habitat (see POST_FATE.temporalEvolution, POST_FATE.graphic_validationStatistics)

doFunc.evolCov

default TRUE.
If TRUE, POST_FATE.graphic_evolutionCoverage function will be run.

doFunc.evolPix

default TRUE.
If TRUE, POST_FATE.graphic_evolutionPixels function will be run.

doFunc.evolStab

default TRUE.
If TRUE, POST_FATE.graphic_evolutionStability function will be run.

evolPix.cells_ID

(optional) default NULL.
The cells ID of the studied area for which PFG abundances will be extracted (see POST_FATE.graphic_evolutionPixels)

evolStab.mw_size

(optional) default NULL.
An integer corresponding to the size (in years) of the moving window that will be used to calculate metrics of habitat stability (see POST_FATE.graphic_evolutionStability)

evolStab.mw_step

(optional) default NULL.
An integer corresponding to the step (in years) of the moving window that will be used to calculate metrics of habitat stability (see POST_FATE.graphic_evolutionStability)

evol.fixedScale

(optional) default TRUE.
If FALSE, the ordinate scale will be adapted for each PFG for the graphical representation of the evolution of abundances through time (see POST_FATE.graphic_evolutionCoverage)

doFunc.valid

default TRUE.
If TRUE, POST_FATE.graphic_validationStatistics function will be run.

valid.mat.PFG.obs

a data.frame with 4 columns : PFG, X, Y, obs (see POST_FATE.graphic_validationStatistics)

doFunc.mapPFGvsHS

default TRUE.
If TRUE, POST_FATE.graphic_mapPFGvsHS function will be run.

doFunc.mapPFG

default TRUE.
If TRUE, POST_FATE.graphic_mapPFG function will be run.

mapPFGvsHS.stratum

(optional) default all.
The stratum number from which to extract PFG binary maps (see POST_FATE.graphic_mapPFGvsHS)

binMap.method

an integer to choose the transformation method :
1 (relative abundance) or 2 (optimizing TSS) (see POST_FATE.binaryMaps)

binMap.method1.threshold

default 0.05.
If method = 1, minimum relative abundance required for each PFG to be considered as present in the concerned pixel (see POST_FATE.binaryMaps)

binMap.method2.cutoff

default NULL.
If method = 2, a data.frame with 3 columns : year, PFG, cutoff
(see POST_FATE.binaryMaps)

mapPFG.stratum_min

(optional) default 1.
An integer corresponding to the lowest stratum from which PFG abundances will be summed up (see POST_FATE.graphic_mapPFG)

mapPFG.stratum_max

(optional) default 10.
An integer corresponding to the highest stratum from which PFG abundances will be summed up (see POST_FATE.graphic_mapPFG)

mapPFG.doBinary

(optional) default TRUE.
If TRUE, abundance maps (absolute or relative) are systematically multiplied by binary maps (see POST_FATE.graphic_mapPFG)

opt.doPlot

(optional) default TRUE.
If TRUE, plot(s) will be processed, otherwise only the calculation and reorganization of outputs will occur, be saved and returned

opt.no_CPU

(optional) default 1.
The number of resources that can be used to parallelize the unzip/zip of raster files, as well as the extraction of values from raster files

Value

The following POST_FATE_GRAPHIC_[...].pdf files are created :

A_evolution_coverage

spaceOccupancy

to visualize for each PFG the evolution of its occupation of the studied area through simulation time

abundance

to visualize for each PFG the evolution of its abundance within the whole studied area through simulation time

A_evolution_pixels

to visualize for each PFG the evolution of its abundance within each selected pixel through simulation time, as well as the evolution of light and soil resources

A_evolution_stability

to visualize for each habitat the evolution of its total abundance and its evenness through simulation time

B_validationStatistics

to assess the modeling quality of each PFG based on given observations within the studied area

B_map_PFGvsHS

to visualize the PFG presence within the studied area (probability and simulated occurrence)

C_map_PFG

PFGcover

to visualize the PFG cover within the studied area

PFGrichness

to visualize the PFG richness within the studied area

PFGlight

to visualize the light CWM within the studied area

PFGsoil

to visualize the soil CWM within the studied area

Three folders are created :

ABUND_REL_perPFG
_allStrata

containing relative abundance raster maps for each PFG across all strata (see POST_FATE.relativeAbund)

BIN_perPFG
_allStrata

containing presence / absence raster maps for each PFG across all strata (see POST_FATE.binaryMaps)

BIN_perPFG
_perStrata

containing presence / absence raster maps for each PFG for each stratum (see POST_FATE.binaryMaps)

Details

This function allows to obtain, for a specific FATE simulation and a specific parameter file within this simulation, up to eleven preanalytical graphics.

For each PFG and each selected simulation year, raster maps are retrieved from the results folders (ABUND_perPFG_perStrata, ABUND_perPFG_allStrata, ABUND_REL_perPFG_allStrata, BIN_perPFG_perStrata, BIN_perPFG_allStrata, LIGHT or SOIL) and unzipped. Informations extracted lead to the production of the following graphics before the maps are compressed again :

• the evolution of space occupancy of each plant functional group through simulation time,
  with space occupancy representing the percentage of pixels within the mask of studied area where the PFG is present
  (see POST_FATE.graphic_evolutionCoverage)

• the evolution of total abundance of each plant functional group through simulation time,
  with total abundance being the sum over the whole studied area of the PFG abundances (FATE arbitrary unit)
  (see POST_FATE.graphic_evolutionCoverage)

• the evolution of abundance of each Plant Functional Group through simulation time, within 5 (or more) randomly selected pixels of the studied area (FATE arbitrary unit), as well as light resources within each height stratum (1: Low, 2: Medium, 3: High) and soil resources (user-defined scale) if these modules were selected (see POST_FATE.graphic_evolutionPixels)

• the evolution of total abundance (FATE arbitrary unit) and evenness (between 0 and 1) of each habitat through simulation time, with evenness representing the uniformity of the species composition of the habitat (similar to Shannon entropy) (see POST_FATE.graphic_evolutionStability)

• the value of several statistics to evaluate the predictive quality of the model for each plant functional group
  (sensitivity, specificity, auc, TSS = sensitivity + specificity - 1) (see POST_FATE.graphic_validationStatistics)

• the comparison between each PFG habitat suitability map and its simulated map of presence
  (see POST_FATE.graphic_mapPFGvsHS)

• the map of PFG richness within each pixel, representing the sum of binary maps (see POST_FATE.graphic_mapPFG)

• the map of PFG relative cover, representing the sum of relative abundance maps of all PFG
  (potentially above a height threshold defined by opt.stratum_min) (see POST_FATE.graphic_mapPFG)

• the map of light Community Weighted Mean
  (potentially above a height threshold defined by opt.stratum_min) (see POST_FATE.graphic_mapPFG)

• the map of soil Community Weighted Mean
  (potentially above a height threshold defined by opt.stratum_min) (see POST_FATE.graphic_mapPFG)

See also

POST_FATE.temporalEvolution, POST_FATE.graphic_evolutionCoverage, POST_FATE.graphic_evolutionPixels, POST_FATE.graphic_evolutionStability, POST_FATE.relativeAbund, POST_FATE.binaryMaps, POST_FATE.graphic_validationStatistics, POST_FATE.graphic_mapPFGvsHS, POST_FATE.graphic_mapPFG

Author

Maya Guéguen