TrainRandomForest Task

This task creates a set of decision trees from a randomly selected subset of the training set.

For background on the algorithm used, see Random Forest Classification.

Example

; Start the application

e = ENVI()

; Open an input raster file

RasterFile = Filepath('qb_boulder_msi', Subdir=['data'], $

  Root_Dir=e.Root_Dir)

Raster = e.OpenRaster(RasterFile)

; Open an input ROI file

ROIFile = Filepath('qb_boulder_roi.xml', Subdir=['data'], $

Root_Dir=e.Root_Dir)

ROI = e.OpenROI(ROIFile)

; Get the statistics task from the catalog of ENVITasks

StatsTask = ENVITask('NormalizationStatistics')

; Define inputs

StatsTask.INPUT_RASTERS = Raster

; Run the task

StatsTask.Execute

; Get the data prep task from the catalog of ENVITasks

DataPrepTask = ENVITask('MLTrainingDataFromROIs')

; Define inputs

DataPrepTask.INPUT_RASTER = Raster

DataPrepTask.INPUT_ROI = ROI

DataPrepTask.BACKGROUND_LABELS = ['Disturbed Earth', 'Water']

DataPrepTask.NORMALIZE_MIN_MAX = StatsTask.Normalization

DataPrepTask.Execute

; Get the training task from the catalog of ENVITasks

TrainTask = ENVITask('TrainRandomForest')

; Define inputs

TrainTask.INPUT_RASTER = DataPrepTask.OUTPUT_RASTER

TrainTask.NUM_ESTIMATORS = 100

; Run the task

TrainTask.Execute

; Output model metadata

outputModelUri = TrainTask.OUTPUT_MODEL_URI

print, 'Model URI: ' + outputModelUri

outputModel = TrainTask.OUTPUT_MODEL

print, outputModel.Attributes, /IMPLIED

Syntax

Result = ENVITask('TrainRandomForest')

Input parameters (Set, Get): CUSTOM_MAX_FEATURES, BALANCE_CLASSES, INPUT_RASTERS, MAX_DEPTH, MAX_FEATURES, MODEL_DESCRIPTION, MODEL_NAME, MODEL_VERSION, NUM_ESTIMATORS, OOB_SCORE, OUTPUT_MODEL_URI, REMOVE_OUTLIERS

Output parameters (Get only): OUTPUT_MODEL

Parameters marked as "Set" are those that you can set to specific values. You can also retrieve their current values any time. Parameters marked as "Get" are those whose values you can retrieve but not set.

Input Parameters

BALANCE_CLASSES (optional)

Specify whether all classes should be considered equal during training. This helps to account for classes with few samples compared to classes with many examples.

CUSTOM_MAX_FEATURES (optional)

Specify the number of features to consider when looking for the best split. This parameter accepts a float or integer value. If specified, this value will override MAX_FEATURES.

INPUT_RASTERS (required)

Specify one or more preprocessed training rasters to be used for training.

MAX_DEPTH (optional)

Specify the number of decision trees to use. The estimators are the predictors of the algorithm. The default is 100.

MAX_FEATURES (optional)

Specify the number of features to consider when looking for the best split. This parameter offers options sqrt or log2 string literals. The default is sqrt.

MODEL_DESCRIPTION (optional)

Specify the purpose of the model.

MODEL_NAME (optional)

Specify the name of the model. The default is Random Forest Supervised Classifier.

MODEL_VERSION (optional)

Specify a semantic version format (MAJOR.MINOR.PATCH) for the trained model (for example, 1.0.0). The version may indicate the following:

MAJOR: Breaking changes to the model
MINOR: Compatibility or new features
PATCH: Minor adjustments

NUM_ESTIMATORS (optional)

Specify the number of decision trees in the forest. Estimators are the predictors of the algorithm. The default is 100. The default is false.

OOB_SCORE (optional)

Specify whether to use out-of-bag samples to estimate the generalization score. The default is false. If set to true, the score will be stored in the OUTPUT_MODEL statistics report.

OUTPUT_MODEL_URI (optional)

Specify a string with the fully qualified filename and path of the associated OUTPUT_MODEL. If you do not specify this parameter, or set it to an exclamation symbol (!), a temporary file will be created.

REMOVE_OUTLIERS (optional)

The default of true removes outliers using histogram stretching to increase the minimum and decrease the maximum data values. If set to false, use the true minimum and maximum data ranges to normalize the data.

Output Parameters

OUTPUT_MODEL

This is a reference to the output model file.

Methods

Execute

Parameter

ParameterNames

See ENVI Help for details on these ENVITask methods.

Properties

DESCRIPTION

DISPLAY_NAME

NAME

REVISION

See the ENVITask topic in ENVI Help for details.

Version History

Machine Learning 2.0	Introduced
Machine Learning 2.1	Added MAX_FEATURES, CUSTOM_MAX_FEATURES, and OOB_SCORE parameters
Machine Learning 3.0.1	Added REMOVE_OUTLIERS parameter
Machine Learning 6.2	Added the MODEL_VERSION and OUTPUT_MODEL_URI parameters