.TH v.class.mlR 1 "" "GRASS 7.8.6" "GRASS GIS User's Manual"
.SH NAME
\fI\fBv.class.mlR.py\fR\fR  \- Provides supervised support vector machine classification
.SH KEYWORDS
classification, machine learning, R, classifiers
.SH SYNOPSIS
\fBv.class.mlR.py\fR
.br
\fBv.class.mlR.py \-\-help\fR
.br
\fBv.class.mlR.py\fR [\-\fBfintp\fR]  [\fBsegments_map\fR=\fIname\fR]   [\fBsegments_layer\fR=\fIstring\fR]   [\fBtraining_map\fR=\fIname\fR]   [\fBtraining_layer\fR=\fIstring\fR]   [\fBsegments_file\fR=\fIname\fR]   [\fBtraining_file\fR=\fIname\fR]   [\fBtraining_sample_size\fR=\fIstring\fR]   [\fBtuning_sample_size\fR=\fIinteger\fR]   [\fBseparator\fR=\fIcharacter\fR]   [\fBraster_segments_map\fR=\fIname\fR]   [\fBclassified_map\fR=\fIname\fR]   [\fBtrain_class_column\fR=\fIstring\fR]  \fBoutput_class_column\fR=\fIstring\fR \fBoutput_prob_column\fR=\fIstring\fR  [\fBmax_features\fR=\fIinteger\fR]  \fBclassifiers\fR=\fIstring\fR[,\fIstring\fR,...] \fBfolds\fR=\fIinteger\fR \fBpartitions\fR=\fIinteger\fR \fBtunelength\fR=\fIinteger\fR  [\fBtunegrids\fR=\fIstring\fR]  \fBweighting_modes\fR=\fIstring\fR[,\fIstring\fR,...] \fBweighting_metric\fR=\fIstring\fR  [\fBoutput_model_file\fR=\fIname\fR]   [\fBinput_model_file\fR=\fIname\fR]   [\fBclassification_results\fR=\fIname\fR]   [\fBvariable_importance_file\fR=\fIname\fR]   [\fBaccuracy_file\fR=\fIname\fR]   [\fBmodel_details\fR=\fIname\fR]   [\fBbw_plot_file\fR=\fIname\fR]   [\fBr_script_file\fR=\fIname\fR]   [\fBprocesses\fR=\fIinteger\fR]   [\-\-\fBoverwrite\fR]  [\-\-\fBhelp\fR]  [\-\-\fBverbose\fR]  [\-\-\fBquiet\fR]  [\-\-\fBui\fR]
.SS Flags:
.IP "\fB\-f\fR" 4m
.br
Only write results to text file, do not update vector map
.IP "\fB\-i\fR" 4m
.br
Include individual classifier results in output
.IP "\fB\-n\fR" 4m
.br
Normalize (center and scale) data before analysis
.IP "\fB\-t\fR" 4m
.br
Only tune and train model, do not predict
.IP "\fB\-p\fR" 4m
.br
Include class probabilities in classification results
.IP "\fB\-\-overwrite\fR" 4m
.br
Allow output files to overwrite existing files
.IP "\fB\-\-help\fR" 4m
.br
Print usage summary
.IP "\fB\-\-verbose\fR" 4m
.br
Verbose module output
.IP "\fB\-\-quiet\fR" 4m
.br
Quiet module output
.IP "\fB\-\-ui\fR" 4m
.br
Force launching GUI dialog
.SS Parameters:
.IP "\fBsegments_map\fR=\fIname\fR" 4m
.br
Vector map with areas to be classified
.br
Vector map containing all areas and relevant attributes
.IP "\fBsegments_layer\fR=\fIstring\fR" 4m
.br
Layer of the segments map where attributes are stored
.br
Vector features can have category values in different layers. This number determines which layer to use. When used with direct OGR access this is the layer name.
.br
Default: \fI1\fR
.IP "\fBtraining_map\fR=\fIname\fR" 4m
.br
Vector map with training areas
.br
Vector map with training areas and relevant attributes
.IP "\fBtraining_layer\fR=\fIstring\fR" 4m
.br
Layer of the training map where attributes are stored
.br
Vector features can have category values in different layers. This number determines which layer to use. When used with direct OGR access this is the layer name.
.br
Default: \fI1\fR
.IP "\fBsegments_file\fR=\fIname\fR" 4m
.br
File containing statistics of all segments
.br
File containing relevant attributes for all areas
.IP "\fBtraining_file\fR=\fIname\fR" 4m
.br
File containing statistics of training segments
.br
File containing relevant attributes for training areas
.IP "\fBtraining_sample_size\fR=\fIstring\fR" 4m
.br
Size of subsample per class to be used for training
.IP "\fBtuning_sample_size\fR=\fIinteger\fR" 4m
.br
Size of sample per class to be used for hyperparameter tuning
.IP "\fBseparator\fR=\fIcharacter\fR" 4m
.br
Field separator
.br
Field separator in input text files
.br
Default: \fIpipe\fR
.IP "\fBraster_segments_map\fR=\fIname\fR" 4m
.br
Raster map with segments
.br
Input raster map containing all segments
.IP "\fBclassified_map\fR=\fIname\fR" 4m
.br
Prefix for raster maps (one per weighting mode) with classes attributed to pixels
.br
Output raster maps (one per weighting mode) in which all pixels are reclassed to the class attributed to the segment they belong to
.IP "\fBtrain_class_column\fR=\fIstring\fR" 4m
.br
Name of attribute column containing training classification
.IP "\fBoutput_class_column\fR=\fIstring\fR \fB[required]\fR" 4m
.br
Prefix of column with final classification
.br
Default: \fIvote\fR
.IP "\fBoutput_prob_column\fR=\fIstring\fR \fB[required]\fR" 4m
.br
Prefix of column with probability of classification
.br
Default: \fIprob\fR
.IP "\fBmax_features\fR=\fIinteger\fR" 4m
.br
Perform feature selection to a maximum of max_features
.IP "\fBclassifiers\fR=\fIstring[,\fIstring\fR,...]\fR \fB[required]\fR" 4m
.br
Classifiers to use
.br
Options: \fIsvmRadial, svmLinear, svmPoly, rf, ranger, rpart, C5.0, knn, xgbTree\fR
.br
Default: \fIsvmRadial,rf\fR
.IP "\fBfolds\fR=\fIinteger\fR \fB[required]\fR" 4m
.br
Number of folds to use for cross\-validation
.br
Default: \fI5\fR
.IP "\fBpartitions\fR=\fIinteger\fR \fB[required]\fR" 4m
.br
Number of different partitions to use for cross\-validation
.br
Default: \fI10\fR
.IP "\fBtunelength\fR=\fIinteger\fR \fB[required]\fR" 4m
.br
Number of levels to test for each tuning parameter
.br
Default: \fI10\fR
.IP "\fBtunegrids\fR=\fIstring\fR" 4m
.br
Python dictionary of customized tunegrids
.IP "\fBweighting_modes\fR=\fIstring[,\fIstring\fR,...]\fR \fB[required]\fR" 4m
.br
Type of weighting to use
.br
Options: \fIsmv, swv, bwwv, qbwwv\fR
.br
Default: \fIsmv\fR
.IP "\fBweighting_metric\fR=\fIstring\fR \fB[required]\fR" 4m
.br
Metric to use for weighting
.br
Options: \fIaccuracy, kappa\fR
.br
Default: \fIaccuracy\fR
.IP "\fBoutput_model_file\fR=\fIname\fR" 4m
.br
File where to save model(s)
.IP "\fBinput_model_file\fR=\fIname\fR" 4m
.br
Name of file containing an existing model
.IP "\fBclassification_results\fR=\fIname\fR" 4m
.br
File for saving results of all classifiers
.IP "\fBvariable_importance_file\fR=\fIname\fR" 4m
.br
File for saving relative importance of used variables
.IP "\fBaccuracy_file\fR=\fIname\fR" 4m
.br
File for saving accuracy measures of classifiers
.IP "\fBmodel_details\fR=\fIname\fR" 4m
.br
File for saving details about the classifier module runs
.IP "\fBbw_plot_file\fR=\fIname\fR" 4m
.br
PNG file for saving box\-whisker plot of classifier performance
.IP "\fBr_script_file\fR=\fIname\fR" 4m
.br
File containing R script
.IP "\fBprocesses\fR=\fIinteger\fR" 4m
.br
Number of processes to run in parallel
.br
Default: \fI1\fR
.SH DESCRIPTION
.PP
\fIv.class.mlR\fR is a wrapper module that uses the R caret package
for machine learning in R to classify objects using training features
by supervised learning.
.PP
The user provides a set of objects (or segments) to be classified, including
all feature variables describing these object, and a set of objects to be used
as training data, including the same feature variables as those describing the
unknown objects, plus one additional column indicating the class each training
falls into. The training data can, but does not have to be, a subset of the set
of objects to be classified.
.PP
The user can provide input either as vector maps (\fIsegments_map\fR
and \fItraining_map\fR, or as csv files (\fIsegments_file\fR and
\fItraining file\fR, or a combination of both. Csv files have to be
formatted in line with the default output of
v.db.select, i.e. with a header. The field
separator can be set with the \fIseparator\fR parameter.
Output can consist of either additional columns in the vector input map
of features, a text file (\fIclassification_results\fR) or reclassed
raster maps (\fIclassified_map\fR).
.PP
When using text file input, the training data should not contain an id
column. The object data  (i.e., full set of data to be classified) should have
the ids in the first column.
.PP
The user has to provide the name of the column in the training data
that contains the class values (\fItrain_class_column\fR), the prefix
of the columns that will contain the final class after classification
(\fIoutput_class_column\fR) as well as the prefix of the columns that
will contain the probability values linked to these classifications
(\fIoutput_prob_column\fR \- see below).
.PP
Different classifiers are proposed \fIclassifiers\fR:
k\-nearest neighbor (knn), support vector machine with a radial kernel
(svmRadial), support vector machine with a linear kernel (svmLinear), random
forest (rf), C5.0 (C5.0) and XGBoost (xgbTree) decision trees and recursive
partitioning (rpart). Each of these classifiers is tuned automatically through
repeated cross\-validation. Caret will automatically determine a reasonable set
of values for tuning. See the
caret webpage
for more information about the tuning parameters for each classifier, and
more generally for the information about how caret works. By default, the
module creates 10 5\-fold partitions for cross\-validation and tests 10
possible values of the tuning parameters. These values can be changed
using, repectively, the \fIpartitions\fR, \fIfolds\fR and
\fItunelength\fR parameters.
.PP
The user can define a customized tunegrid for each classifier, using
the \fItunegrids\fR parameter. Any customized tunegrid has to be defined
as a Python dictionary, with the classifiers as keys, and the input to
expand.grid() as content as defined
in the caret documentation.
.PP
For example, to define customized tuning grids for svmRadial and
RandomForest, the user can define the paramter as:
.br
.br
.nf
\fC
tunegrids=\(dq{\(cqsvmRadial\(cq: \(cqsigma=c(0.01,0.05,0.1), C=c(1,16,128)\(cq, \(cqrf\(cq: \(cqmtry=c(3,10,20)\(cq}\(dq
\fR
.fi
.PP
Tuning is potentially very time consuming. Using only a subset of the training
data for tuning can thus speed up the process significantly, without losing
much quality in the tuning results. For training, depending on the number of
features used, some R functions can reach their capacity limit.
The user can, therefore, define a maximum size of samples per class both for
tuning (\fItuning_sample_size\fR) and for training
(\fItraining_sample_size\fR).
.PP
Classifying using too many features (i.e. variables describing the objects
to be classified) as input can have negative effects on classification accuracy
(Georganos et al, 2018). The module therefore provides the possibility to run a
feature selection algorithm on the training data in order to identify those
features that are the most efficient for classification. Using less features
also speeds up the tuning, training and classification processes. To activate
feature selection, the user has to set the \fImax_features\fR parameter to
the maximum number of features that the model should select. Often, less than
this maximum will be selected. The method used for feature selection is recursive
feature elimination based on a random forest model. Note thus that feature
selection might be sub\-optimal for other classifiers, notably non tree\-based.
.PP
The module can be run only for tuning and training a model, but without
.PP
Optionally, the module can be run for tuning and training only,
i.e., no prediction (\fI\-t flag\fR). Any trained model can be saved to a
file (\fIoutput_model_file\fR) which can then be read into the module
at a later stage for the prediction step (\fIinput_model_file\fR). This can be
particularly useful for cluster computing approaches where a trained model
can be applied to different datasets in parallel.
.PP
The module can run the model tuning using parallel processing. In order
for this to work, the R\-package \fIdoParallel\fR has to be installed. The
\fIprocesses\fR parameter allows to chose the number of processes to
run.
.PP
The user can chose to include the individual classifiers results in
the output (the attributes and/or the raster maps) using the \fIi\fR
flag, but by default the output will be the result of a voting scheme
merging the results of the different classifiers. Votes can be weighted
according to a user\-defined mode (\fIweighting_mode\fR): simple majority
vote without weighting, i.e. all weights are equal (smv), simple weighted
majority vote (swv), best\-worst weighted vote (bwwv) and quadratic
best\-worst weighted vote (qbwwv). For more details about these voting
modes see Moreno\-Seco et al (2006). By default, the weights are calculated
based on the accuracy metric, but the user can chose the kappa value as an
alternative (\fIweighting_metric\fR).
.PP
In the output (as attribute columns or text file) each weighting schemes
result is provided accompanied by a value that can be considered as an
estimation of the probability of the classification after weighted vote,
based on equation (2) in Moreno et al (2006), page 709. At this stage, this
estimation does not, however, take into account the probabilities determined
individually by each classifier.
.PP
Optional output of the module include detailed information about the
different classifier models and their cross\-validation results
\fImodel_details\fR (for details of these results see the train,
resamples and confusionMatrix.train functions in the caret package),  a
box\-and\-whisker plot indicating the resampling variance based on the
cross\-validation for each classifier (\fIbw_plot_file\fR), a csv
file containing accuracy measures (overall accuracy and kappa) for each
classifier (\fIaccuracy_file\fR), and a file containing variable importance
as determined by the classifier (for those classifiers that allow such
calculation). When the \fI\-p\fR flag is given,
the module also provides probabilities per class for each classifier (at least
for those where caret can calculate such probabilities). This allows to evaluate
the confidence of classification of each object.
The user can also chose to
write the R script constructed and used internally to a text file for study or
further modification.
.SH NOTES
.PP
The module can be used in a tool chain together with i.segment
and the addon \fIi.segment.stats\fR for object\-based classification of
satellite imagery.
.PP
\fIWARNING:\fR The option output files are created by R and currently
no checking is done of whether files of the same name already exist. If they
exist, they are silently overwritten, regardless of whether the GRASS GIS
\fI\-\-o\fR flag is set or not.
.PP
The module makes no effort to check the input data for NA values or
anything else that might perturb the analyses. It is up to the user to
proceed to relevant checks before launching the module.
.SH DEPENDENCIES
.PP
This module uses R. It is the user\(cqs responsibility to make sure R is
installed and can be called from the environment this module is running in.
See the relevant
wiki page
for more information. The module tries to install necessary R packages
automatically if necessary. These include : \(cqcaret\(cq, \(cqkernlab\(cq, \(cqe1071\(cq,
\(cqrandomForest\(cq, and \(cqrpart\(cq. Other packages can be necessary such as \(cqggplot2\(cq,
\(cqlattice\(cq (for the plots), and \(cqdoParallel\(cq (if parallel processing is desired).
.SH TODO
.RS 4n
.IP \(bu 4n
Check for existing file created by R as no overwrite check is
done in R
.IP \(bu 4n
Use class probabilities determined by individual classifiers
to calculate overall class probabilities
.RE
.SH EXAMPLE
.PP
Using existing vector maps as input and writing the output to the attribute table of the segments map, including the individual classifier results:
.br
.nf
\fC
v.class.mlR segments_map=seg training_map=training train_class_column=class weighting_mode=smv,swv,qbwwv \-i
\fR
.fi
.PP
Using text files with segment characteristics as input and writing output to raster files and a csv file
.br
.nf
\fC
v.class.mlR segments_file=segstats.csv training_file=training.csv train_class_column=class weighting_mode=smv,swv,qbwwv raster_segments_map=seg classified_map=vote classification_results=class_results.csv
\fR
.fi
.SH REFERENCES
.PP
.RS 4n
.IP \(bu 4n
Moreno\-Seco, F. et al. (2006), Comparison of Classifier Fusion Methods for Classification in Pattern Recognition Tasks. In D.\-Y. Yeung et al., eds. Structural, Syntactic, and Statistical Pattern Recognition. Lecture Notes in Computer Science. Springer Berlin Heidelberg, pp. 705â€“713, http://dx.doi.org/10.1007/11815921_77.
.IP \(bu 4n
Georganos, S. et al (2018), Less is more: optimizing classification performance through feature selection in a very\-high\-resolution remote sensing object\-based urban application, GIScience and Remote Sensing, 55:2, 221\-242, DOI: 10.1080/15481603.2017.1408892
.RE
.SH SEE ALSO
\fI
i.segment,
r.object.activelearning,
r.learn.ml
\fR
.SH AUTHOR
Moritz Lennert, UniversitĂ© Libre de Bruxelles (ULB)
based on an initial R\-script by Ruben Van De Kerchove, also ULB at the time
.SH SOURCE CODE
.PP
Available at: v.class.mlR source code (history)
.PP
Main index |
Vector index |
Topics index |
Keywords index |
Graphical index |
Full index
.PP
© 2003\-2021
GRASS Development Team,
GRASS GIS 7.8.6 Reference Manual
