TfNear

Summary

Defines a Near transformation function which is determined from the midpoint and spread shape–controlling parameters as well as the lower and upper threshold that identify the range within which to apply the function.

Learn more about how the parameters affect this transformation function

Discussion

The tool that uses the TfNear object is Rescale by Function.

The equation for the Near transformation function is:

\(\mu(x) = \Large \frac {1}{1 \space + \space f1 \space * \space (x - f2)^2}\)

The inputs to the equation are \(f1\), the spread, and \(f2\), the midpoint.

The function values range from 0 to 1, which are then transformed to the evaluation scale.

The spread determines how rapidly the transformation function values decrease from the midpoint. If the midpoint is within the lower and upper thresholds, then the spread determines how rapidly the function values decrease from the toScale to the fromScale. The larger the value, the steeper the function values will be around the midpoint. Said another way, as the spread gets smaller, the transformation function values approach the midpoint more slowly. The selection of the appropriate spread value is a subjective process that is dependent on the range of the input values. The default value of 0.1 is a good starting point. Typically, the values vary within the ranges of 0.01 to 1 or 0.001 to 1, respectively. A default spread is calculated to fit the function to the minimum and maximum of the input dataset.

The Near function is useful if you want the highest output evaluation values (the highest preferences) to be assigned to cells with input values near a specific value with the evaluation values (preferences) decreasing as the input values move from the value.

The Near function is similar to the Gaussian transformation function, except the Near function has a narrower spread.

Syntax

TfNear({midpoint}, {spread}, {lowerThreshold}, {valueBelowThreshold}, {upperThreshold}, {valueAboveThreshold})

Name	Explanation	Data type
midpoint (Optional)	The user-defined value that defines the highest point of the Near transformation function curve. If the midpoint value is between the lower and upper threshold, input cell locations with the corresponding value will receive the `toScale` evaluation scale value on the output raster. The default value is None.	Double
spread (Optional)	Defines the spread of the Near function that controls the steepness of the decay of the function from the midpoint. The spread generally ranges from 0.001 to 1; the larger the value results in a steeper decay from the midpoint. The default value is None.	Double
lowerThreshold (Optional)	Defines the starting value at which to begin applying the specified transformation function. The input value corresponding to the `lowerThreshold` is assigned to the `fromScale` evaluation scale value on the output raster. Input values below the `lowerThreshold` are assigned to the `valueBelowThreshold` and are not considered in the function value range. The `lowerThreshold` must be less than the `upperThreshold`. The default value is None.	Double
valueBelowThreshold (Optional)	A value to assign output cell locations with input values below the `lowerThreshold`. The value for `valueBelowThreshold` can be float, integer, or NoData. In the tool dialog box, no quotation marks are used around NoData; however, quotation marks are required around "NoData" when scripting. The default value is None.	Variant
upperThreshold (Optional)	Defines the ending value at which to stop applying the specified transformation function. The input value corresponding to the `upperThreshold` is assigned to the `toScale` evaluation scale value on the output raster. Input values above the `upperThreshold` are assigned to the `valueAboveThreshold` and are not considered in the function value range. The `lowerThreshold` must be less than the `upperThreshold`. The default value is None.	Double
valueAboveThreshold (Optional)	A value to assign output cell locations with input values above the `upperThreshold`. The value for `valueAboveThreshold` can be float, integer, or NoData. In the tool dialog box, no quotation marks are used around NoData; however, quotation marks are required around "NoData" when scripting. The default value is None.	Variant

Properties

Name	Explanation	Data type
midpoint (Read and Write)	The value of the `midpoint` for the transformation function which defines the highest point of the function curve.	Double
spread (Read and Write)	The value of the `spread` for the transformation function which controls the steepness of the decay of the function from the midpoint.	Double
lowerThreshold (Read and Write)	The value of the `lowerThreshold` for the transformation function which defines the starting value at which to begin applying the specified transformation function.	Double
valueBelowThreshold (Read and Write)	The value that will be assigned to the output cells whose input values are below the `lowerThreshold`.	Variant
upperThreshold (Read and Write)	The value of the `upperThreshold` for the transformation function which defines the ending value at which to stop applying the specified function.	Double
valueAboveThreshold (Read and Write)	The value that will be assigned to the output cells whose input values are above the `upperThreshold`.	Variant

Code sample

Transformation function Near example 1 (Python window)

Demonstrates how to create a TfNear class and use it in the RescaleByFunction tool within the Python window.

import arcpy
from arcpy.sa import *
from arcpy import env
env.workspace = "c:/sapyexamples/data"
outRescale = RescaleByFunction("solar", TfNear(180, 0.002, "#", "#", "#", "#"), 1, 10)
outRescale.save("c:/sapyexamples/rescaletfne1")

Transformation function Near example 2 (stand-alone script)

Demonstrates how to transform the input data with the RescaleByFunction tool using the TfNear class.