Enum Class AnnotationNormalization

java.lang.Object
java.lang.Enum<AnnotationNormalization>
edu.cmu.tetrad.search.harness.AnnotationNormalization
All Implemented Interfaces:
Serializable, Comparable<AnnotationNormalization>, Constable
public enum AnnotationNormalization extends Enum<AnnotationNormalization>
How a raw per-(SNP, trait) annotation matrix is turned into the adjustment scores that EdgePriorFacade and EdgePriorScoreFacade scale by tau.

Why this exists. The original scheme, Z_SCORE, standardises the pooled annotation to mean zero and unit standard deviation. That keeps tau = 0 an honest baseline but is unbounded: under toll scaling the effective penalty for an edge is lambda * log(n) * (1 - tau * a), so at tau = 0.5 a z-score of 2 zeroes the penalty and anything beyond that turns it into an edge-addition reward. The forward phase then adds the edge unconditionally and the backward phase can never remove it -- the required-knowledge limit is crossed silently, driven by the annotation's tails rather than by a deliberate choice. For a roughly normal annotation at tau = 0.5, about two percent of the pool crosses it. The bounded modes below exist so that no data-driven adjustment can cross that limit at moderate tau, and EdgePriorScoreFacade.numForcedPairs(double, int) exists so that a crossing, wherever it comes from, is counted rather than silent.

Conventions shared by every mode. An entry with no information -- NaN in the input, and for the log modes any non-positive weight -- receives a NaN adjustment, which the facades map to a zero prior; such entries do not enter the statistics. A degenerate column (constant, or with fewer than two usable entries) receives neutral adjustments throughout, so a constant annotation reproduces the unmodified search exactly. Z_SCORE pools the whole matrix, as the legacy code always has; the bounded modes normalise each trait column separately over the full candidate pool, so one trait's scale cannot distort another's, and the normalisation must be computed once over the full pool, never recomputed inside subsample repeats, for the same fixed-family reason as EdgePriors.normalizedToMeanOne().

Choosing a mode. CENTERED_LOG_MIN_MAX is the conservative default for positive, right-skewed weights: bounded, zero mean, respects magnitude on the log scale. Its weakness is that the two most extreme SNPs set the scale for everyone, so one huge weight flattens every other adjustment toward zero, and for light-tailed log weights the typical adjustment shrinks as the pool grows. ROBUST_CLIPPED trades the exact zero mean for a stable typical scale: outliers saturate at the clip instead of either dominating or flattening the rest. NONE is for adjustments computed elsewhere (for instance in Python) that must pass through untouched -- the facades do not re-standardise them.

Author:
josephramsey
See Also:

  • Nested Class Summary

    Nested classes/interfaces inherited from class Enum

    Enum.EnumDesc<E>

  • Enum Constant Summary

    Enum Constants
    Enum Constant
    Description
    CENTERED_LOG_MIN_MAX
    Centred log min-max, per trait column: CENTERED_MIN_MAX applied to log(w) over the column's entries that are finite and strictly positive; non-positive weights are treated as having no information.
    CENTERED_MIN_MAX
    Centred min-max, per trait column: a = (w - mean(w)) / (max(w) - min(w)) over the column's finite entries.
    NONE
    No normalisation: the entries are the adjustments, passed through unchanged (NaN still means no information).
    ROBUST_CLIPPED
    Robust clipped, per trait column, on the log scale: a = clip((log(w) - median) / (2 * IQR), -1, 1) over the column's finite, strictly positive entries, with quartiles by linear interpolation (type 7).
    Z_SCORE
    The legacy scheme: the pooled finite entries are standardised to mean zero and unit sample standard deviation (n - 1 denominator).

  • Method Summary

    Modifier and Type
    Method
    Description
    double[][]
    adjust(double[][] annotation)
    Computes the adjustment matrix for an annotation under this mode.
    static AnnotationNormalization
    valueOf(String name)
    Returns the enum constant of this class with the specified name.
    static AnnotationNormalization[]
    values()
    Returns an array containing the constants of this enum class, in the order they are declared.

    Methods inherited from class Enum

    compareTo, describeConstable, equals, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

    Methods inherited from class Object

    getClass, notify, notifyAll, wait, wait, wait

  • Enum Constant Details

    • Z_SCORE

      public static final AnnotationNormalization Z_SCORE
      The legacy scheme: the pooled finite entries are standardised to mean zero and unit sample standard deviation (n - 1 denominator). Zero mean, unbounded. When this mode is passed to a facade factory, the facade delegates to its original code path, so results are bit for bit what the pre-mode factories produce.

    • CENTERED_MIN_MAX

      public static final AnnotationNormalization CENTERED_MIN_MAX
      Centred min-max, per trait column: a = (w - mean(w)) / (max(w) - min(w)) over the column's finite entries. Zero mean and bounded in [-1, 1] by construction; the spread max(a) - min(a) is exactly 1, so for a roughly symmetric column the values sit near [-1/2, 1/2] and at tau = 0.5 the effective penalties stay within roughly 3/4 to 5/4 of baseline.

    • CENTERED_LOG_MIN_MAX

      public static final AnnotationNormalization CENTERED_LOG_MIN_MAX
      Centred log min-max, per trait column: CENTERED_MIN_MAX applied to log(w) over the column's entries that are finite and strictly positive; non-positive weights are treated as having no information. Zero mean and bounded in [-1, 1]; the natural choice for positive, right-skewed annotation weights. If a weight of zero is meant as evidence against an edge rather than as missing, floor it to a small positive value before calling, since this mode cannot tell the two apart.

    • ROBUST_CLIPPED

      public static final AnnotationNormalization ROBUST_CLIPPED
      Robust clipped, per trait column, on the log scale: a = clip((log(w) - median) / (2 * IQR), -1, 1) over the column's finite, strictly positive entries, with quartiles by linear interpolation (type 7). The typical adjustment keeps a stable size regardless of pool size or outliers -- for normal log weights about 0.7 percent of entries clip -- at the price of an exact zero median rather than an exact zero mean; the mean is approximately zero for roughly symmetric log weights. A column whose IQR is zero (heavy ties) is treated as degenerate and receives neutral adjustments.

    • NONE

      public static final AnnotationNormalization NONE
      No normalisation: the entries are the adjustments, passed through unchanged (NaN still means no information). This is the mode for adjustments precomputed outside -- the facades do not re-standardise them, which silently undoes any bounding done upstream. Nothing bounds these values, so under toll scaling any entry with tau * a >= 1 is a forced edge; the toll-scaled factories count such pairs and warn, and EdgePriorScoreFacade.numForcedPairs(double, int) reports the count on demand.

  • Method Details

    • values

      public static AnnotationNormalization[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static AnnotationNormalization valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class has no constant with the specified name
      NullPointerException - if the argument is null

    • adjust

      public double[][] adjust(double[][] annotation)
      Computes the adjustment matrix for an annotation under this mode. The input is not modified; the result has the same shape, with NaN wherever the entry carries no information under this mode's conventions (see the class Javadoc).
      Parameters:
      annotation - An n_snp x n_trait matrix; rows are SNPs, columns are traits. Higher means more prior support. NaN means no information.
      Returns:
      The adjustments, same shape; NaN for entries carrying no adjustment.
      Throws:
      IllegalArgumentException - If the matrix is ragged, or contains an infinite entry.
      NullPointerException - If the annotation or any of its rows is null.