POST_FATE.graphics: Create all possible graphical representations for a 'FATE'...
In MayaGueguen/RFate: Vegetation modelling with the FATE model

Description Usage Arguments Details Value Author(s) See Also Examples

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) vizualising 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
)

`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`, `POST_FATE.graphic_evolutionPixels`)
`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

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)

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)