# ML - Train Object Classifier

This is an experimental module from the Xtra Library: https://www.thermofisher.com/software-em-3d-vis/xtra-library/.

This module trains an object classifier to associate a set of Measures (or features, as computed by the Label Analysis module) with a Material (or class), given the examples provided as inputs.

The module generates a trained model as a file on the disk, at specified location. This file is to be used with the associated module ML - Prediction Object Classifier.

The implementation of this module is based on scikit-learn python package.

## Known Limitations

- The trained model is stored on the disk, relying on the pickle python package. It is unlikely that a model trained with a version of the Software will work with a future version.
- The set of measures the model relies on is specified in this module, and must remain the same when using the module for Prediction (i.e. if the measure group is modified between Training and Prediction, the prediction will fail).
- As a consequence, if you need to transfer the model to a different computer, you will need to ensure the Measure Group is defined on that computer (see "Export Custom Measure Groups")

## Connections

Input | Description
--- | ---
Data: [required] | Label Image representing the masks of objects assigned to a Material that corresponds to the class. The notion of object is implicitly associated with the notion of connected components. The module Disconnect Touching Labels can help ensure this.
Intensity Image: [optional] | Grayscale image, the same size and shape as the Data, from which intensity features will be computed.

## Parameters (Ports)

Parameter | Description
--- | ---
Console | Opens the Python Script Object console of the module as the active console window.
Mode | Specify whether the input is interpreted as a 3D volume or a stack of 2D images for processing. 3D: the module configuration is set to 3D. The image will be processed as a whole in 3D. 2D (XY): the module configuration is set to 2D. The image will be processed slice by slice. Note: 2D measures will not be displayed in the analysis spreadsheet of a 3D volume and vice versa
Model | Select one or multiple base classifier. An ensemble classifier is trained from the selection, using soft voting.
Measures | Select the set of measures to be used for training. See 'Label Analysis' module for more information.
Feature Normalization | If active, each feature is normalized – with respect to the set of objects in the training data – prior to training the classifier. When prediction will be performed, the same normalization will be applied.
Output Directory | Folder where the trained model will be saved
Base Filename | The name of the model file to be generated
Apply | Execute the training

## Outputs

The main output of the module is the model file in the Output Directory.

Additional outputs are generated in the Project: the label field of object instances, and the analysis spreadsheet with additional columns for Class Name and ID.

## See also

ML - Prediction Object Classifier

Disconnect Touching Labels

ObjectClassification_Tuto.pdf