Skip To Content

Train Random Trees Regression Model

Available with Image Analyst license.

Description

Train Random Trees Regression Model

The Train Random Trees Regression Model task models the relationship between explanatory variables (independent variables) and a target dataset (dependent variable).

As of 10.9.1, you must license your ArcGIS Server as an ArcGIS Image Server to use this resource.

Request parameters

ParameterDetails
inputRasters

(Required)

A raster or a list of input rasters. The input rasters can be the Portal Item ID, Image Service URL, cloud multidimensional raster dataset or shared raster dataset. The rasters can be single-band, multidimensional, multiband raster datasets, or mosaic datasets, containing explanatory variables

An input mosaic dataset will be treated as a raster dataset, not a collection of rasters. To use a collection of rasters as input, build multidimensional info for the mosaic dataset and use the result as input.

At least one type of input needs to be provided in the JSON object. If multiple inputs are given, the itemIds takes priority.

Syntax: A JSON object describing the input raster(s).

Example for a single inputRasters item.

inputRasters = {"itemId": <portal item id>}
inputRasters  = {"url": <image service url>}
inputRasters = {"uri": <cloud raster uri or shared data path>}

Example for multiple inputRasters items.

inputRasters = {"itemIds": [<portal item id>, <portal item id>, <portal item id>]}
inputRasters  = {"urls": [<image service url>, <image service url>, <image service url>]}
inputRasters  = {"uris": [<cloud raster uri or shared data path>, <cloud raster uri or shared data path>]}
inputTargetData

(Required)

The raster or point feature class containing the target variable (dependent variable) data.

This parameter can have either a raster input or a feature input. For raster input, this parameter can be specified as a portal item ID, a URL to a raster image service layer, a cloud raster dataset, or a shared raster dataset. For feature input, this parameter can be specified as a URL to a feature service layer, shared data path or service properties.

When the target is a feature, the targetValueField value must be set to a numeric field.

If the input target feature has a date field or a field that defines a dimension, specify a value for both targetValueField and targetDimensionField.

Syntax: A JSON object that describes the input.

Example

inputTargetData ={"itemId": <portal item id>}
inputTargetData = {"url": <image service url or feature service url>}
inputTargetData = {"uri": <cloud raster uri or shared data path>}
targetValueField

(Optional)

The field name of the information to model in the target point feature class or raster dataset.

Syntax: String representing the targetValueField.

Example

"median_house"
targetDimensionField

(Optional)

A date field or numeric field in the input point feature class that defines the dimension values.

Syntax: String representing the targetDimensionField.

Example

"Date_Local"
rasterDimension

(Optional)

The dimension name of the input multidimensional raster (explanatory variables) that links to the dimension in the target data.

Syntax: String representing the rasterDimension.

Example

"StdTime"
outputImportanceTableName

(Optional)

The output table feature service name that will be created. You can specify the name, or you can create an empty service using Portal Admin Sharing API and use the returned JSON object as input to this parameter.

Syntax: A JSON object that describes the name of the output or the output table.

Example of outputImportanceTableName

{"serviceProperties":{"name":<service name>}}
maxNumberOfTrees

(Optional)

The maximum number of trees in the random forest. Increasing the number of trees will lead to higher accuracy rates, although this improvement will level off. The number of trees increases the processing time linearly. The default is 50.

Syntax: A long value that represents the maxNumberOfTrees.

Example

60
maxTreeDepth

(Optional)

The maximum depth of each tree in the random forest. Depth determines the number of rules each tree can create, resulting in a decision. Trees will not grow any deeper than this setting. The default is 30.

Syntax: A long value that represents the maxTreeDepth.

Example

100
maxNumberOfSamples

(Optional)

The maximum number of samples that will be used for the regression analysis. A value that is less than or equal to 0 means that the system will use all the samples from the input target raster or point feature class to train the regression model. The default value is 100,000.

Syntax: A long value that represents the maxNumberOfSamples.

Example

25000
averagePointsPerCell

(Optional)

Specifies whether the average will be calculated when multiple training points fall into one cell. This parameter is applicable only when the input target is a point feature class.

  • KEEP_ALL_POINTS—All points will be used when multiple training points fall into a single cell. This is the default.
  • AVERAGE_POINTS_PER_CELL—The average value of the training points within a cell will be calculated.

Syntax: A String value representing the averagePointsPerCell.

Example

“KEEP_ALL_POINTS”
outputScatterPlotsName

(Optional)

The output scatterplots in PDF or HTML format. It includes scatterplots of training data, test data, and location test data.

Note:
For Portal, only PDF type is supported while datastores support both PDF and HTML. If no extension is specified, PDF is used by default.

Syntax: A JSON object that describes the name of the output or path to the datastore.

Examples


//name example
{"name": "output_plot"}

//uri example
{"uri": <datastore path>}
outputSampleFeaturesName

(Optional)

Outputs a feature class containing target values and predicted values for training points, test points, and location test points. You can specify the name, or you can create an empty service using Portal Admin Sharing API and use the returned JSON object as input to this parameter.

Syntax: A JSON object that describes the output feature service name.

Example

{"serviceProperties": {"name": "<service name>"}}
percentSamplesForTesting

(Optional)

Defines the percentage of test points used for error checking. The tool checks for three types of errors: errors on training points, errors on test points, and errors on test location points. The default is 10.

Syntax: A double value that represents the percentSamplesForTesting.

Example:

20

context

(Optional)

Contains additional settings that affect task execution. This task has the following settings:

  • Cell Size (cellSize)—The output raster will have the resolution specified by cell size.
  • Extent (extent)—A bounding box that defines the analysis area.
  • Output Spatial Reference (outSR)—The output raster will be projected into the output spatial reference.
  • Parallel Processing Factor (parallelProcessingFactor)—The specified number or percentage of processes will be used for the analysis.

f

(Optional)

The response format. The default response format is html.

Values: html | json

Response

When you submit a request, the task assigns a unique job ID for the transaction.

Syntax:

{
"jobId": "<unique job identifier>",
"jobStatus": "<job status>"
}

After the initial request is submitted, you can use jobId to periodically review the status of the job and messages as described in Checking job status. Once the job has successfully completed, use jobId to retrieve the results. To track the status, you can make a request of the following form:

https://<raster analysis tools url>/TrainRandomTreesRegressionModel/jobs/<jobId>

When the status of the job request is esriJobSucceeded, you can access the results of the analysis by making a request of the following form:

To access the output regression definition file:

http://<raster analysis url>/
TrainRandomTreesRegressionModel/jobs/<jobId>/results/outputRegressionDefinitionFile
?token=<your token>&f=json

The ecd is the value property of the resulting JSON.

To access the output importance table:

http://<raster analysis url>/
TrainRandomTreesRegressionModel/jobs/<jobId>/results/outputImportanceTable
?token=<your token>&f=json

To access the output scatter plots:

http://<raster analysis url>/
TrainRandomTreesRegressionModel/jobs/<jobId>/results/outputScatterPlots
?token=<your token>&f=json

To access the output sample features:

http://<raster analysis url>/
TrainRandomTreesRegressionModel/jobs/<jobId>/results/outputSampleFeatures
?token=<your token>&f=json