Record Class LogTransformSpec

java.lang.Object

java.lang.Record

edu.cmu.tetrad.data.LogTransformSpec

Record Components:

a - The offset added before taking the log (or subtracted after exponentiating when unlogging).

base - The base of the logarithm; 0 means the natural log and base e.

unlog - True to apply the inverse transform, false to apply the log transform.

public record LogTransformSpec(double a, int base, boolean unlog)
extends Record

A logarithmic transform to apply to a single variable: the direction (log or unlog), the offset a, and the base.

Logging applies f(x) = log_base(a + x); unlogging applies its inverse g(x) = base^x - a. A base of 0 means the natural log and base e, matching the convention used by the dataset-wide transform.

All three fields are per variable rather than per dataset because their correct values depend on the variable's scale. The offset in particular is scale-relative: since log(a + x) is approximately log(a) + x/a when x is much smaller than a, a single offset shared across variables of different magnitude performs a genuine logarithmic transform on the large-valued ones and an approximately affine rescaling on the small-valued ones. Keeping base and direction alongside the offset also guarantees that a transform can be inverted with the same spec.

Author:

josephramsey

Constructor Summary

Constructors

Constructor	Description
LogTransformSpec(double a, int base, boolean unlog)	Creates an instance of a LogTransformSpec record class.

Method Summary

Modifier and Type	Method	Description
double	a()	Returns the value of the a record component.
double	apply(double x)	Applies this spec to a single value.
int	base()	Returns the value of the base record component.
static Map<String, LogTransformSpec>	decode(String encoded)	Decodes a string produced by encode(java.util.Map).
static String	encode(Map<String, LogTransformSpec> specs)	Encodes a map of specs as a single string, for storage in a Parameters object and hence in a saved session.
final boolean	equals(Object o)	Indicates whether some other object is "equal to" this one.
final int	hashCode()	Returns a hash code value for this object.
static double	safeOffsetFor(double[] column)	Returns the smallest offset that keeps every value of the given column strictly positive under a log transform, or 0.0 if the column is already strictly positive.
final String	toString()	Returns a string representation of this record class.
boolean	unlog()	Returns the value of the unlog record component.

Methods inherited from class Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Details

LogTransformSpec

public LogTransformSpec(double a,
 int base,
 boolean unlog)

Creates an instance of a LogTransformSpec record class.

Parameters:

a - the value for the a record component

base - the value for the base record component

unlog - the value for the unlog record component

Method Details

apply

public double apply(double x)

Applies this spec to a single value.

Parameters:

x - The value to transform.

Returns:

The transformed value.

encode

public static String encode(Map<String, LogTransformSpec> specs)

Encodes a map of specs as a single string, for storage in a Parameters object and hence in a saved session.

The format is one variable per line, with fields separated by tabs: name, offset, base, unlog. A string is used rather than a serialized object so that the stored form is stable across versions of this class and legible when a saved session is inspected; tab and newline are safe separators because a variable name containing either could not have been read from a delimited data file.

Parameters:

specs - The specs to encode; may be null or empty.

Returns:

The encoded string, empty if there is nothing to encode.

decode

public static Map<String, LogTransformSpec> decode(String encoded)

Decodes a string produced by encode(java.util.Map). Malformed lines are skipped rather than throwing, so that a session saved by a later version with extra fields still opens.

Parameters:

encoded - The encoded string; may be null or empty.

Returns:

The decoded specs, empty if there was nothing to decode.

safeOffsetFor

public static double safeOffsetFor(double[] column)

Returns the smallest offset that keeps every value of the given column strictly positive under a log transform, or 0.0 if the column is already strictly positive. This is a convenience for editors that want to propose a safe default; it is not applied automatically anywhere.

Parameters:

column - The column values.

Returns:

A safe offset for the column, or 0.0 if none is needed.

toString

public final String toString()

Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.

Specified by:

toString in class Record

Returns:

a string representation of this object

hashCode

public final int hashCode()

Returns a hash code value for this object. The value is derived from the hash code of each of the record components.

Specified by:

hashCode in class Record

Returns:

a hash code value for this object

equals

public final boolean equals(Object o)

Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. All components in this record class are compared with the compare method from their corresponding wrapper classes.

Specified by:

equals in class Record

Parameters:

o - the object with which to compare

Returns:

true if this object is the same as the o argument; false otherwise.

a

public double a()

Returns the value of the a record component.

Returns:

the value of the a record component

base

public int base()

Returns the value of the base record component.

Returns:

the value of the base record component

unlog

public boolean unlog()

Returns the value of the unlog record component.

Returns:

the value of the unlog record component