TfLogarithm

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 = {\rm 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

TfLogarithm({shift}, {factor}, {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. 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 (Optional)	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 (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
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

Transformation function Logarithm example 1 (Python window)

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")

Transformation function Logarithm example 2 (stand-alone script)

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

# 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

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

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