TfLogarithm (arcpy.sa)
Summary
Defines a Logarithm transformation function which is determined from the shift and 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 TfLogarithm object is Rescale by Function.
There is no direct relationship between the base of the logarithm and the factor.
By definition, as the input values near zero, their function values approach infinity. As the function values get closer to infinity, the smaller function values dramatically increase the function range. As a result, when the function range is transformed linearly to the evaluation scale, the smaller function values skew the range so that the shape of the logarithm curve may be lost. Increasing the lowerThreshold can be used to truncate some of these really low values.
To address the issue of small input values skewing the function range, a varying shift based on the input range is applied by default. This shift will truncate the very low values, thus maintaining the logarithm function shape in the output raster.
Dive-in:The conceptual technical interaction of the varying default shift is
- The function limit is calculated from the minimum and maximum input values multiplied by the factor.
- A Delta is calculated: Delta = Exp(functionLimit)/factor. The Delta needs to be less than FLT_EPSILON (which equals 1.19209290 x 10-07).
- Determine the shift: shift = inputMinimum - Delta.
Syntax
| Parameter | Explanation | Data Type |
shift |
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. By default, the shift adjusts the function so it begins at the lowerThreshold (or very close). As a result, the function will be applied to 0 (the shifted input value) with the function being constrained between the lower and upper thresholds. A shift can be applied so the low input values do not dramatically increase the range of the function values; therefore, the final output evaluation scale maintains the general function shape. The shift can be positive or negative. (The default value is None) | Double |
factor | The multiplier to apply to the shifted input values. The factor alters the rise of the Logarithm curve. (The default value is None) | Double |
lowerThreshold | 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 | 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 | 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 | 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
| Property | 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 |
| factor (Read and Write) |
The value of the factor for the transformation function which identifies the multiplier to apply to the shifted input values. | 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
Demonstrates how to create a TfLogarithm 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("elevation", TfLogarithm(450, 6.25, "#", "#", "#", "#"), 1, 10)
outRescale.save("c:/sapyexamples/rescaletflo1")
Demonstrates how to transform the input data with the RescaleByFunction tool using the TfLogarithm class.
# Name: TfLogarithm_Ex_02.py
# Description: Rescales input raster data using an Logarithm function and
# transforms the function values onto a specified evaluation scale.
# Requirements: Spatial Analyst Extension
# Author: esri
# 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 = "elevation"
# Create the TfLogarithm object
shift = 450
factor = 6.25
lowerthresh = "#"
valbelowthresh = "#"
upperthresh = "#"
valabovethresh = "#"
myTfFunction = TfLogarithm(shift, factor, lowerthresh, valbelowthresh, upperthresh, valabovethresh)
# Set evaluation scale
fromscale = 1
toscale = 10
# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")
# Execute RescaleByFunction
outRescale = RescaleByFunction(inRaster, myTfFunction, fromscale, toscale)
# Save the output
outRescale.save("c:/sapyexamples/rescaletflg2")