########################################################################################
#
# PROGRAM:	grassr-clasif.py
# AUTHOR(S):	Francisco Gomariz-Castillo, Francisco Alonso-Sarría and 
#		        Fulgencio Cánovas-García
#
# PURPOSE:      To generate supervised clasifications using 
#               Maxlik, SMAP, RandomForest and Support Vector Machines.
#
#               It allows to combine different seature-sets although can be also 
#               used with just a group giving the value "" to the optional 
#               parameters. The allowed combination is:
#                 1. Three feature-sets. In this paper they include:
#                   a) Spectral
#                   b) Spectral and textural
#                   c) Spectral, textural and terrain derived
#                 2. Combination of images from different years     
#
#               Besides, it is posible to combine raster layers with different types
#               of information, for example set b might be a list of raster layers
#               representing climatic features and set c might be other type of 
#               information. 
#
#
# VARIABLES AND PARAMETERS:------------------------------------------------------------
# spectral:   List of spectral images (required)
# training:   Training raster (required)
# validate:   Validate raster (required)
# optim (-c): Optimise RandomForest (mtry) and SVM (Cost) based on repeated CV (k=5,n=10)
#             and maximize Kappa. 0: not optimize; 1: Optimize (required)
# textural:   list of texture raster layers (optional)
# covar:      List of covariates (for example relief features) (optional)
# seasons:  Sufix refering to the season of the image (optional)
# year:       Year of the image (optional)
#
#
# SUBPROGRAMS (in R lenguage)----------------------------------------------------------
# kappa-confusion.R: Calculate confusion matrices, kappa and condicional kappa for
#             Maxlik y SMAP
# clasifSVM-RF.R:    Classify using RandomForest and Support Vector Machine
#                    with or without optimization; it also calculates confusion matrices,
#                    kappa and condicional kappa.
#
# Required packages: rgrass7, caret, randomForest, e1071, vcd
#
#
#NOTE: For the script to function correctly, the environmental variable “R_HOME"
#(installation directory) must be properly set. It can be set in Windows Command-line
#executing:
#SET R_HOME=C:\"Program Files"\R\R-3.3.2 (for R-3.3.2) or adding to the file "grass7X.bat"
#the line: SET R_HOME=C:\"Program Files"\R\R-3.3.2
#
#In Linux can be set executing (usually):
#export R_HOME=/usr/lib/R
#
#
# RESULTS:-----------------------------------------------------------------------------
# Raster classif.: GRASS raster layers named "clasif_$model$dataset$year$est"
#                  where:
#                    $model: maxlik, smap, rf, svm
#                    $dataset: S (spectral), T (spectral and textural), R (spectral,
#                              textural and covariates; 
# Summaries:       TXT  files:
#                    "summaryCAL$year$est.txt": Summary of RandomForest  and SVM 
 #                   calibrations (parameters and calibration adjustments)
#                    "summaryVAL$year$est.txt": Summary of te final validation      
# Folder "clasifresults":
#                  1. Confusion matrices of the clasifications as txt files
#                  2. OOB error and feature importance (RandomForest) graphs.
#                  3. If -c flag is activated, the gaphs of the RandomForest and SVM calibration
#                      processes.
#
#
# EXAMPLE:------------------------------------------------------------------------------
# We want to clasify a 2015 image comparing the four algorithms and combining different raster layers. We have the folowing information:
#        1. Seasons: Two landsat 8 images (winter and summer)
#        2. Spectral features: bands 2 a 7 (for each season)
#        3. Textural features: albedo and ndvi semivariograms in each season
#        4. Relief features: Elevation and slope 
#        5. Training data
#        6. Validation data
#
# We also want to optimize RF and SVM
#
#
# Execute:
# python grassr-clasif.py  spectral="b2,b3,b4,b5,b6,b7" training="train" validate="validate" textural="lnalbedosm1,lnndvism1" covar="DEM,SLP" seasons="_i,_v" year="2015" -c
#
#
########################################################################################



