\documentstyle[psfig,times]{article}

\begin{document}
\begin{center}
  {\Large\em L'ambiente PR (Pattern Recognition)}
\end{center}
\vspace{1truecm}
\noindent

\section{i.pr\_training}
Interfaccia grafica per estrazione di dati di training da mappe raster
GRASS.  Data una lista di mappe (parametro map), di cui la prima
verr\`{a} utilizzata per visualizzazione se non \`{e} settato il
parametro vis\_map, l'utente cliccando sulla mappa selezioner\`{a}
esempi di training che avranno dimensione rows $\times$ cols
(parametri rows e cols rispettivamente).  Gli esempi selezionati
saranno assegnati alla classe scelta in input dall'utente (parametro
class) che dovr\`{a} essere un intero positivo progressivo.  Una
procedura alternativa (e non grafica) \`{e} quella di dare in input al
programma un file di siti GRASS (parametro site\_file) e il programma
creer\`{a} gli esempi di training in corrispondenza dei siti stessi.
La classe assegnata agli esempi sar\`{a} quella definita nel file di
siti. L'output del programma \`{e} una serie di mappe raster di
dimensione rows $\times$ cols il cui nome sar\`{a} del tipo {\em x\_y.z}
dove {\em y} \`{e} il nome della mappe raster da cui \`{e} stata estratta,
{\em z} un contatore mentre {\em x} sar\`{a} il nome di un file che
verr\`{a} creato (parametro training) e che sar\`{a} come quello generato
dalle seguenti chiamate:

ESEMPIO: i.pr\_training map=ammcom,genesi rows=11 cols=11 training=AAA class=1

ESEMPIO: i.pr\_training map=ammcom,genesi rows=11 cols=11 training=AAA class=2

FILE: AAA

\noindent
\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#
\begin{verbatim}
Data type:
GrassTraining
Number of layers:
2
Label:
AAA
Data:
Layer_1 Layer_2 Class   East    North   Rows    Cols    EW-res  NS-res
AAA_ammcom.1    AAA_genesi.1    1       1657029  5072830  11      11      1.5       1.5
AAA_ammcom.2    AAA_genesi.2    1       1657072  5072864  11      11      1.5        1.5
AAA_ammcom.3    AAA_genesi.3    2       1657123  5072871  11      11      1.5        1.5
AAA_ammcom.4    AAA_genesi.4    2       1657153  5072910  11      11      1.5        1.5
\end{verbatim}
\noindent
\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#

\subsection*{Help}
\begin{verbatim}
Usage:
 i.pr_training map=name[,name,...] [vis_map=name] training=name
   [vector=name] rows=value cols=value [class=value]

Parameters:
        map   Input raster maps (max 25) for extracting the training
              examples.
                The first one will be used for graphical output 
                in case vis_map option not set
    vis_map   Raster map for visualization.
   training   Name of the output file containing the training raster 
              maps.
                If this file already exists, the new data will 
                be appended to the end of the file.
     vector   Name of the  site file containing labelled location.
                Substitutes the interactive procedure of site selection.
       rows   Number of rows (required odd) of the training samples.
       cols   Number of columns (required odd) of the training samples.
      class   Numerical label to be attached to the training examples.
                Option not required with the vector option.
\end{verbatim}

\section{i.pr\_features}
Processa dati di training ed estrae features. Dato un file di training
in ingresso (paretro training) e che contiene il nome di mappe raster
relative a layers differenti permette eleborare di normalizzare le
mappa dei layers selezionati (parametro normalize) di calcolarne la
media (parametro mean), la varianza (parametro variance). Inoltre per
ogni layer selezionato permette di calcolare la componenti principali
(parametro prin\_comp); il modello di componenti principali pu\`{o}
essere calcolato su tutti i dati (default) oppure solo sui dati delle
classi selezionate (parametro class\_pc). Inoltre permette di
standardizzare le features estratte (parametro standardize); questo
parametro non \`{e} collegato al numero di layers contenuti nel file di
training ma \`{e} collegato al numero di features precedentemente
calcolate. L'output del programma \`{e} un file (parametro features) come quello generato dalla seguente chiamata:

ESEMPIO: i.pr\_features training=AAA features=BBB normalize=1 mean=1,2

FILE BBB:

\noindent
\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#
\begin{verbatim}
#####################
TRAINING: (AAA)
#####################
Type of data:
1
Number of layers:
2
Training dimensions:
11      11
EW-res  NS-res
1.5        1.5
#####################
FEATURES:
#####################
normalize:
1       1       1
standardize:
0
mean:
1       2       1       2
variance:
0
pca:
0
Number of classes:
2
Classes:
1       2
Standardization values:
NULL
NULL
Features dimensions:
4       2
Features:
l1_mean l2_mean class
1.000000        5.000000        1
1.000000        5.000000        1
1.000000        5.000000        2
1.000000        5.000000        2
\end{verbatim}
\noindent
\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#

\noindent
Se nessuna opearazione viene selezionata, le features estratte saranno i dati stessi.

\noindent
Il programma i.pr\_features permette di eseguire le stesse operazione
su dati non GRASS, ovvero su una tabella di dati. Il formato dei dati
deve essere come il seguente:

FILE AAA:

\noindent
\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#
\begin{verbatim}
Data type:
TableTraining
Dimension:
2
Data:
6.5     0.      1
-6.5    -0.     -1
6.3     1.2     1
-6.3    -1.2    -1
5.8     2.4     1
-5.8    -2.4    -1
\end{verbatim}
\noindent
\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#

\noindent
In questo caso i dati sono interpretati come singolo layer (quindi ad esempio se si setta mean=1, la feature estratta sar\`{a} la media dei dati).

\noindent
L'output sar\`{a} come il seguente:

ESEMPIO: i.pr\_features training=AAA features=BBB mean=1

FILE: BBB

\noindent
\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#
\begin{verbatim}

#####################
TRAINING: (AAA)
#####################
Type of data:
2
Number of layers:
1
Training dimensions:
1       2
EW-res  NS-res
0.000000        0.000000
#####################
FEATURES:
#####################
normalize:
0
standardize:
0
mean:
1       1       1
variance:
0
pca:
0
Number of classes:
2
Classes:
1       -1
Standardization values:
NULL
NULL
Features dimensions:
6     1
Features:
l1_mean class
3.250000        1
-3.250000       -1
3.784850        1
-3.784850       -1
4.164670        1
-4.164670       -1
\end{verbatim}
\noindent
\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#\#

\subsection*{Help}
\begin{verbatim}
Usage:
 i.pr_features [-s] training=name[,name,...] features=name
   [normalize=value[,value,...]] [mean=value[,value,...]]
   [variance=value[,value,...]] [prin_comp=value[,value,...]]
   [class_pc=value[,value,...]] [standardize=value[,value,...]]

Flags:
  -s   Print site file containing coordinates of examples and class labels
        (from training data) into features option and exit.

Parameters:
     training   Input files (max 50) containing training data.
                2 formats are currently supported:
                1) GRASS_data (output of i.pr_training)
                2) TABLE_data.
     features   Name of the output file containing the features.
    normalize   Numbers of the layers to be normalized.
         mean   Numbers of the layers on which to compute the mean value.
     variance   Numbers of the layers on which to compute the variance.
    prin_comp   Numbers of the layers on which to compute the principal 
                components.
     class_pc   Classes of the data to be used for computing the 
                principal components.
                If not set, all the examples will be used.
  standardize   Numbers of features to be standardize.
                WARNING: not related to the number of layers.
\end{verbatim}

\section{i.pr\_statistics}
Calcola statistiche sulle features. Dato un file di features in input
(parametro features), calcola kolgomorov-smirnov test e t\-test per
ogni classe di ogni features. Se nelle features sono presenti
componenti principali, calcola la varianza spiegata da esse. Se ci
sono pi\`{u} modelli di componenti principali (per pi\`{u} layers),
l'analisi viene eseguita solo su un layer (parametro layer). Il
parametro npc serve per limitare l'analissi alle prime npc componenti
princiapli.

\begin{verbatim}
Usage:
 i.pr_statistics features=name [layer=value] [npc=value]

Parameters:
  features   Input file containing the features (output of i.pr_features).
     layer   Number of the layer to be analized (concerning with the 
             principal components).
                Ignored if features does not contain principal 
                components model.
             default: 1
       npc   Number of principal components to be analized.
                If this number is greater then the dimension of the data,
                all the principal components will be considered.
                Ignored if features does not contain principal 
                components model.
\end{verbatim}

\section{i.pr\_model}
Crea modello di classificazione a partire da file di features. Il tipo
di modello creato viene scelto settando uno dei flag g (gaussian mixture) n (nearest
neighbor) t (classification trees) s (support vector machines). Ci
sono poi dei parametri generali come il file delle features (parametro
features), il nome del file prodotto e contenente il modello
(parametro model), il nome di un file di features addizioanle sul
quale calcolare dei valori di predizione durante la fase di training
(parametro validation), il nome di un file di features addizioanle sul
quale calcolare dei valori di predizione oltre al training set
(parametro test) e il numero di componenti principali da utilizzare
nel modello (parametro npc) se queste sono presenti nelle features.
Poi ci sono parametri modello specifici. Nessuno per la gaussian
mixture. Il numero di neighbors per nearest neighbor (parametro
nn\_k), anche se questo parametro serve solo per la valutazione del
modello in quando il modello di per s\`{e} sono i dati stessi. Per i
classification trees si pu\`{o} decidere se fare alberi ad un solo
nodo (stamps) o no (parametro tree\_stamps), oppure decidere quanti
dati deve contenere almeno un nodo per essere splittato (parametro
tree\_minsize). Inoltre il parametro tree\_costs permette di
sbilanciare le classi (stile rpart). Per le support vector machines
l'utente deve settare il tipo di kernel (parametro svm\_kernel, che
pu\'o assumere i valori linear gaussian e 2pbk), l'ampiezza del kernel
in caso sia gaussiano (parametro (svm\_kp), il parametro di
regolarizzazione (svm\_C), i parametri di convergenza svm\_eps,
svm\_tolerance e svm\_maxloops. Si suggereisce di non modificare i
primi due mentre il numero massimo di loop di ottimizazione pu\`{o}
essere modificato (sempre con cura). Per le support vector machines si
pu\`{o} decidere di calcolare una stima del leave-one-out model error
utilizzando il paramtro svm\_l1o. L'output della procedura \`{e} un
file che contiene il modello selezionato. A standard output verranno
descritte le prestazioni del modello sul training set e opzionalmente
su un test set. Per le support vector machines opzionalmente anche una
stima di cross-validation. Per i modelli classification trees e
support vecor machines sono disponibili anche combinazioni di modelli
(bagging e boosting). Il numero di modelli \`{e} scelto dall'utente
(parametri bagging e boosting rispettivamente). Per il boosting \`{e}
disponibile anche la versione cost-sensitive, il cui parametro \`{e}
cost\_boosting. Se si usa boosting, \'e possibile ottenere la dinamica
dei pesi boosting utilizzando il parametro weights\_boosting. Sempre
per boosting di trees \`e possibile sviluppare (il tutto \'e
sperimentale) la versione soft del modello con il parametro
soft\_margin\_boosting. Una versione cost-sensitive per la support
vector machine singola \`e ottenibile utilizzando il parametro
svm\_cost. 
\`E possibile inoltre utilizzare una versione regolarizzata dell'algoritmo
AdaBoost specificando il numero di intervalli (parametro reg) in cui
suddividere il misclassification ratio (quindi il numero di 
training set generati), in questo caso il validation set \`e indispnsabile, in 
alternativa \`e possibile scegliere manualmente il valore di misclassification 
ratio al disopra del quale i campioni vengono eliminati dal training set 
(parametro misclass\_ratio).
Per alcuni modelli sono implementate solo classificazione
binarie in accordo al seguente prospetto:

\noindent
gaussian mixture: multiclasse

\noindent
nearest neighbor: multiclasse

\noindent
classification trees: multiclasse

\noindent
support vector machines: binaria

\noindent
bagging classification trees: multiclasse

\noindent
boosting classification trees: binaria

\noindent
bagging support vector machines: binaria

\noindent
boosting support vector machines: binaria

\subsection*{Help}
\begin{verbatim}
Usage:
 i.pr_model [-gtsn] features=name model=name [validation=name]
   [test=name] [npc=value] [bagging=value] [boosting=value] [reg=value]
   [misclass_ratio=value] [reg_verbose=value] [progressive_error=value]
   [cost_boosting=value] [weights_boosting=value] [parallel_boosting=value]
   [soft_margin_boosting=value] [tree_stamps=value] [tree_minsize=value]
   [tree_costs=value[,value,...]] [svm_kernel=name] [svm_kp=value]
   [svm_C=value] [svm_cost=value] [svm_tol=value] [svm_eps=value]
   [svm_l1o=value] [svm_maxloops=value] [svm_verbose=value] [nn_k=value]

Flags:
  -g   selected model: gaussian mixture.
  -t   selected model: classification trees.
  -s   selected model: support vector machines.
  -n   selected model: nearest neighbor.

Parameters:
              features   Input file containing the features 
                         (output of i.pr_features).
                 model   Name of the output file containing the model.
            validation   Input file containing other features for the 
                         training and for the evaluation of the performances 
                         of the model on an independent test set 
                         (for regularized AdaBoost).
                  test   Input file containing other features for the 
                         evaluation of the performances of the model 
                         on an independent test set.
                   npc   Number of the principal components to be used 
                         for the model development.
                         If not set all the principal components 
                         will be used.
                         Ignored if features does not contain 
                         principal  components model.
               bagging   Number of bagging models.
                         If bagging = 0 the classical model will
                         be implemented.
                         Implemented for trees and svm only.
                         default: 0
              boosting   Number of boosting models.
                         If boosting = 0 the classical model will 
                         be implemented.
                         Implemented for trees and svm only.
                         default: 0
                   reg   Number of misclassification ratio intervals.
                         default: 0
        misclass_ratio   For regularized AdaBoost: misclassification ratio 
                         for hard point shaving and compute the new model.
                         default: 1.00
           reg_verbose   For regularized AdaBoost:
                         - if it is set = 1 the current value of 
                           misclassification ratio and the current 
                           error will be printed.
                         - if it is set to >1 the number of
                           loops, accuracy and the current value of 
                           misclassification ratio will be printed.
                         For shaving and compute:
                         - if it is set >0 the numbers of samples 
                           shaved will be printed.
                         default: 0
     progressive_error   Progressive estimate of the model error
                         increasing the number of aggregated models
                         options: 0,1
                         default: 0
         cost_boosting   Cost parameter for the implementation of 
                         cost-sensitive procedure(w in [0,2]).
                         w>1 results higher weight on examples of class 1.
                         w<1 results higher weight on examples of class -1.
                         w=1 corresponds to standard Adaboost.
                         default: 1.0
      weights_boosting   For boosting: if weights_boosting = 1, a file 
                         containing the evolution of the weights associated 
                         to data points will be produced.
                         options: 0,1
                         default: 0
     parallel_boosting   For boosting: number of true boosting steps for 
                         parallel boosting.
                         Implemented only for trees!!
                         default: 0
  soft_margin_boosting   For boosting: if soft_margin_boosting = 1, 
                         sof margin of Ababoost will bee used. 
                         Implemented only with trees. (Sperimental!!!!!!!!)
                         options: 0,1
                         default: 0
           tree_stamps   For trees: if tree_stamps = 1, a single split 
                         tree will be procuded, if tree_stamps = 0, 
                         a classical tree will be procuded.
                         options: 0,1
                         default: 0
          tree_minsize   For trees: minimum number of examples containined
                         into a node for splitting the node itself
                         default: 0
            tree_costs   For trees: misclassification costs for each class
            svm_kernel   For svm: type of employed kernel.
                         options: gaussian,linear,2pbk
                         default: linear
                svm_kp   For svm: kernel parameter (Required parameter if 
                         you are using gaussian kernel).
                 svm_C   For svm: optimization parameter (Required parameter).
              svm_cost   Cost parameter for the implementation of 
                         cost-sensitive procedure(w in [-1,1]).
                         w>0 results higher weight on examples of class 1.
                         w<0 results higher weight on examples of class -1.
                         w=0 corresponds to standard SVM.
                         Not yet implemented (and may be it will be 
                         never implemented) for bagging and boosting.
                         default: 0.0
               svm_tol   For svm: tollerance parameter.
                         default: 0.001
               svm_eps   For svm: epsilon.
                         default: 0.001
               svm_l1o   For svm: leave 1 out error estimate.
                         options: 0,1
                         default: 0
          svm_maxloops   For svm: maximum number of optimization steps.
                         default: 1000
           svm_verbose   For svm: if it is set to 1 the number of loops will 
                         be printed.
                         options: 0,1
                         default: 0
                  nn_k   For nn: Number of neighbor to be considered during 
                         the test phase.
                         default: 1
\end{verbatim}


\section*{i.pr\_classify}
Classifica mappe raster GRASS sulla base di un modello di
classificazione. Dato un numero di mappe raster GRASS in input
(parametr input\_map) in cui l'ordine deve essere lo stesso utilizzato
per l'estrazione di dati di training(!!!!), ed un modello di
classificazione (parametro model), viene prodotta una mappa raster
GRASS contenente il risultato della classifcazione.

Valori della mappa per tipo di modello:

\noindent
gaussian mixture binaria: probabilit\`{a} a posteriori della classe pi\`{u} probabile moltiplicata per la classe stessa $\{-1,1\}$

\noindent
gaussian mixture multiclasse: classe pi\`{u} probabile

\noindent
nearest neighbor binaria: proporzione di dati della classe pi\`{u} probabile moltiplicata per la classe stessa $\{-1,1\}$

\noindent
nearest neighbor multiclasse: classe pi\`{u} probabile

\noindent
classification trees binaria: proporzione di dati della classe pi\`{u} probabile nel nodo terminale moltiplicata per la classe stessa $\{-1,1\}$

\noindent
classification trees multiclasse: classe pi\`{u} probabile

\noindent
support vector machines binaria: output della support vector machine stessa $(-\infty,\infty)$

\noindent
bagging classification trees multiclasse: classe pi\`{u} probabile

\noindent
bagging classification trees binaria: somma pesata di modelli $(-1,1)$

\noindent
boosting classification trees (solo binaria): somma pesata di modelli $(-1,1)$

\noindent
bagging support vector machines (solo binaria): somma pesata di modelli $(-1,1)$

\noindent
boosting support vector machines(solo binaria) : somma pesata di modelli $(-1,1)$

\subsection*{Help}
\begin{verbatim}
Usage:
 i.pr_classify input_map=name[,name,...] model=name output_map=name

Parameters:
   input_map   Input raster maps to be classified.
                It is required a number of maps at least equal to the number 
                of maps used for the training. If this number is greater 
                the last maps will be ignored.
                WARNING: the order in which the maps are given should 
                be compared  with that used for the training.
       model   Input file containing the model (output of i .pr_model).
                If the data used for model development are not GRASS_data 
                the program will abort.
  output_map   Name of the output raster map conaining the resulting 
               classification.
\end{verbatim}


\section*{i.pr\_subsets}
Crea features file per esperimenti a partire da un file di features
(opzione features) implementando cross-validation (flag c) o bootstrap
resampling (flag b). L'opzione n\_sets setta il numero di bootstap
subsets o il numero di folder per cross-validation. L'opzione seed permette di creare insiemi differenti.

\subsection*{Help}
\begin{verbatim}
Usage:
 i.pr_subsets [-cb] features=name n_sets=value seed=value

Flags:
  -c   selected method: cross-validation.
  -b   selected method: bootstrap.

Parameters:
  features   Input file containing the features (output of i.pr_features).
    n_sets   Number of subsets (>=1). If you set n_sets=1 and select 
             cross-validation, leave one out cv will be implemented.
      seed   Seed for the initialization (>=0), which specifies a 
             starting point for the random number sequence. Replicate
             same experiment.
             default: 0
\end{verbatim}

\section*{i.pr\_features\_additional}
Dato un file di features (opzione features) applica le regole che
hanno creato quelle features a una lista di training files (opzione
training) e crea da questi un nuovo file di features (opzione
features\_out).

\subsection*{Help}
\begin{verbatim}
Usage:
 i.pr_features_additional training=name[,name,...] features=name
   features_out=name

Parameters:
      training   Input files (max 50) containing training data.
                2 formats are currently supported:
                1) GRASS_data (output of i.pr_training)
                2) TABLE_data.
      features   Name of the input file containing the features.
  features_out   Name of the output file containing the features.
\end{verbatim}
\end{document}


