TfExponential

Summary

Defines an Exponential transformation function which is determined from the shift and base factor 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 TfExponential object is Rescale by Function.

The highest possible function value is limited to one-half of the maximum single-precision floating-point value (FLT_MAX, whose value is 3.402823466 x 10³⁸), the value of which is 1.701411733 x 10³⁸. Any input values that exceed this limit will receive the To scale value on the output raster.

Each increment of high input values can dramatically increase the resulting function range. As a result, when the function range is linearly transformed to the evaluation scale, the higher function values skew the function range so the shape of the Exponential function curve may be lost in the output evaluation scale. Lowering the upperThreshold can be used to truncate some of the high values.

Dive in:

There is a relationship between the baseFactor and the base of the exponential. The formula to change the base to a natural base is:

\(b^x = ({\rm e}^{\large \ln(b)})^x = {\rm e}^{\large x \space * \space \ln(b)}\)

where \({\ln(b)}\) is the baseFactor in the formula used in the TfExponential function \({\rm Exp}((x - shift) * baseFactor\)).

Syntax

TfExponential({shift}, {baseFactor}, {lowerThreshold}, {valueBelowThreshold}, {upperThreshold}, {valueAboveThreshold})

Name	Explanation	Data type
shift (Optional)	Defines how much each input value is to be shifted. The shift value is subtracted from the input value. The transformation function is applied to the shifted input value to determine the function value. The shift can be positive or negative. The default value is None.	Double
baseFactor (Optional)	A multiplier that controls how steep the Exponential function increases. The larger the multiplier, the steeper the curve will be at the larger input values. There is a close connection between the base factor and the base of the Exponential function. A `baseFactor` of 1 equals the natural exponential (e^x). 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 user-specified 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 user-specified 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
shift (Read and Write)	The value of the `shift` for the function which defines how much to subtract from each input value before applying the function.	Double
baseFactor (Read and Write)	The value of the `baseFactor` for the transformation function which controls how steep the Exponential function increases.	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 Exponential example 1 (Python window)

Demonstrates how to create a TfExponential 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("distroads", TfExponential(30, 0.00035, "#", "#", "#", "#"), 1, 10)
outRescale.save("c:/sapyexamples/rescaletfex1")

Transformation function Exponential example 2 (stand-alone script)

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

# Name: TfExponential_Ex_02.py
# Description: Rescales input raster data using an Exponential function and
#     transforms the function values onto a specified evaluation scale.
# Requirements: Spatial Analyst extension

# Import system modules
import arcpy
from arcpy import env
from arcpy.sa import *

# Set environment settings
env.workspace = "C:/sapyexamples/data"

# Set local variables
inRaster = "distroads"

# Create the TfExponential object
shift = 30
basefactor = 0.00035
lowerthresh = "#"
valbelowthresh = "#"
upperthresh = "#"
valabovethresh = "#"
myTfFunction = TfExponential(shift, basefactor, lowerthresh, valbelowthresh, upperthresh, valabovethresh)

# Set evaluation scale
fromscale = 1
toscale = 10

# Run RescaleByFunction
outRescale = RescaleByFunction(inRaster, myTfFunction, fromscale, toscale)

# Save the output
outRescale.save("c:/sapyexamples/rescaletfex2")