Class Histogram

java.lang.Object
edu.cmu.tetrad.data.Histogram
public class Histogram extends Object
Model for a conditional histogram for mixed continuous and discrete variables. Drop-in replacement with optional x-axis bounds for continuous targets.
Author:
josephramsey

  • Constructor Summary

    Constructors
    Constructor
    Description
    Histogram(DataSet dataSet, String target, boolean removeZeroPointsPerPlot)
    Constructs a Histogram object for the given data set.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addConditioningVariable(String variable, double low, double high)
    Adds a continuous conditioning variable with a specified range.
    void
    addConditioningVariable(String variable, int value)
    Adds a discrete conditioning variable with a specified value.
    void
    clearContinuousBounds()
    Clears the continuous bounds applied to the histogram's target variable.
    double[]
    getContinuousData(String variable)
    Retrieves the continuous data for a specified variable from the dataset.
    DataSet
    getDataSet()
    Retrieves the current DataSet instance associated with this object.
    double
    getDisplayMax()
    Retrieves the maximum value used for display purposes in a continuous histogram.
    double
    getDisplayMin()
    Retrieves the minimum value used for display purposes in a continuous histogram.
    int[]
    getFrequencies()
    Calculates and returns frequency counts for the data associated with the target variable.
    double
    getMax()
    Computes and returns the maximum value from a list of unconditioned continuous data points.
    double
    getMin()
    Calculates and returns the minimum value from a list of unconditioned continuous data.
    int
    getN()
    Returns the size of the conditioned data list.
    String
    getTarget()
    Retrieves the name of the target associated with this instance.
    Node
    getTargetNode()
    Retrieves the target node.
    boolean
    hasContinuousBounds()
    Checks if both the lower and upper bounds for a continuous interval are set.
    void
    removeConditioningVariable(String variable)
    Removes a conditioning variable from the histogram.
    void
    setContinuousBounds(double low, double high, boolean ignoreOutside)
    Sets the continuous bounds for the target variable along with an option to ignore data outside these bounds.
    void
    setNumBins(int numBins)
    Sets the number of bins to be used in the histogram.

    Methods inherited from class Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Histogram

      public Histogram(DataSet dataSet, String target, boolean removeZeroPointsPerPlot)
      Constructs a Histogram object for the given data set. This constructor ensures that the data set is not null and contains variables. It optionally removes zero data points per plot.
      Parameters:
      dataSet - the data set used to compute the histogram; must not be null and must contain variables
      target - the target variable for which the histogram will be created
      removeZeroPointsPerPlot - a flag indicating whether zero data points should be removed per plot
      Throws:
      NullPointerException - if the provided dataSet is null
      IllegalArgumentException - if the provided dataSet contains no variables

  • Method Details

    • addConditioningVariable

      public void addConditioningVariable(String variable, double low, double high)
      Adds a continuous conditioning variable with a specified range. The conditioning variable is constrained to the interval [low, high]. If the variable is already conditioned, an exception is thrown.
      Parameters:
      variable - the name of the variable to be conditioned; must correspond to a continuous variable in the data set
      low - the lower bound of the conditioning interval (exclusive)
      high - the upper bound of the conditioning interval (exclusive); must be greater than the low value
      Throws:
      IllegalArgumentException - if low is not less than high, or if the specified variable is not continuous, or if the variable is already a conditioning variable

    • addConditioningVariable

      public void addConditioningVariable(String variable, int value)
      Adds a discrete conditioning variable with a specified value. The variable must be discrete. If the variable is not discrete, an IllegalArgumentException is thrown.
      Parameters:
      variable - the name of the variable to be conditioned; must correspond to a discrete variable in the data set
      value - the integer value associated with the discrete conditioning variable
      Throws:
      IllegalArgumentException - if the specified variable is not discrete

    • removeConditioningVariable

      public void removeConditioningVariable(String variable)
      Removes a conditioning variable from the histogram. This method deletes any existing conditioning rules for the specified variable, whether they are continuous intervals or discrete values. If the variable is not a conditioning variable, an IllegalArgumentException is thrown.
      Parameters:
      variable - the name of the variable to be removed from the conditioning set; must exist in the data set
      Throws:
      IllegalArgumentException - if the specified variable is not a conditioning variable

    • setNumBins

      public void setNumBins(int numBins)
      Sets the number of bins to be used in the histogram. This determines how the data is divided into intervals for counting. The number of bins must be a positive integer greater than or equal to 1. If the target variable is discrete, this operation is not allowed.
      Parameters:
      numBins - the number of bins to divide the histogram into; must be a positive integer and greater than or equal to 1
      Throws:
      IllegalArgumentException - if numBins is less than 1
      IllegalArgumentException - if the target variable is discrete

    • setContinuousBounds

      public void setContinuousBounds(double low, double high, boolean ignoreOutside)
      Sets the continuous bounds for the target variable along with an option to ignore data outside these bounds. The bounds apply only if the target variable is continuous and valid.
      Parameters:
      low - the lower bound of the range (inclusive); must be less than high
      high - the upper bound of the range (inclusive); must be greater than low
      ignoreOutside - a boolean specifying whether to ignore data points outside the specified bounds
      Throws:
      IllegalArgumentException - if low is not less than high
      IllegalArgumentException - if the target variable is not continuous

    • clearContinuousBounds

      public void clearContinuousBounds()
      Clears the continuous bounds applied to the histogram's target variable. This method removes any previously set continuous bounds by resetting the lower bound, upper bound, and the "ignore outside bounds" flag to their default values. Specifically: - The lower bound (`continuousBoundLow`) is set to null. - The upper bound (`continuousBoundHigh`) is set to null. - The flag indicating whether to ignore data outside the bounds (`ignoreOutsideBounds`) is set to true. After calling this method, the histogram no longer uses any continuous bounds for filtering or processing the target variable's data.

    • hasContinuousBounds

      public boolean hasContinuousBounds()
      Checks if both the lower and upper bounds for a continuous interval are set. This method evaluates whether the continuous bounds, defined by continuousBoundLow and continuousBoundHigh, are both non-null. It returns true if both bounds are set, indicating that the histogram is operating with a defined range for continuous values.
      Returns:
      true if the lower and upper bounds for a continuous interval are both non-null, false otherwise.

    • getDisplayMin

      public double getDisplayMin()
      Retrieves the minimum value used for display purposes in a continuous histogram. This method first checks if continuous bounds are defined and returns the lower bound if they are present. If no continuous bounds are set and a previously calculated display minimum exists, it returns that value. Otherwise, it defaults to the unconditioned minimum value of the data.
      Returns:
      the minimum value for display, determined based on continuous bounds or unconditioned data, as a double.

    • getDisplayMax

      public double getDisplayMax()
      Retrieves the maximum value used for display purposes in a continuous histogram. This method determines the display maximum by evaluating the following, in order: - If continuous bounds are defined, the upper bound is returned. - If a previously calculated display maximum exists, it is returned. - Otherwise, the maximum value from unconditioned data is returned.
      Returns:
      the maximum value for display, based on continuous bounds, previously calculated display value, or unconditioned data, as a double.

    • getFrequencies

      public int[] getFrequencies()
      Calculates and returns frequency counts for the data associated with the target variable. The method handles both continuous and discrete variable types. For continuous variables: - The data is divided into bins based on the specified number of bins and a computed range. - Special handling is applied for degenerate ranges (where min and max are identical). - Values outside the bounds may be ignored based on configuration. For discrete variables: - Counts are returned for each category based on the variable's number of categories. - Only valid category indices are counted.
      Returns:
      An array of integers representing the frequency counts. For continuous variables, the size of the array is equal to the number of bins. For discrete variables, the size of the array is equal to the number of categories of the target variable. If no valid data is available, an array of zeros is returned.
      Throws:
      IllegalArgumentException - if the target variable type is unrecognized.

    • getMax

      public double getMax()
      Computes and returns the maximum value from a list of unconditioned continuous data points. The method retrieves the data, converts it into an array of doubles, and calculates the maximum value contained within the array.
      Returns:
      the maximum value in the unconditioned continuous data

    • getMin

      public double getMin()
      Calculates and returns the minimum value from a list of unconditioned continuous data.
      Returns:
      The minimum value from the unconditioned continuous data as a double.

    • getN

      public int getN()
      Returns the size of the conditioned data list.
      Returns:
      the number of elements in the conditioned data list

    • getContinuousData

      public double[] getContinuousData(String variable)
      Retrieves the continuous data for a specified variable from the dataset.
      Parameters:
      variable - the name of the variable for which continuous data is to be retrieved
      Returns:
      an array of double values representing the continuous data for the specified variable

    • getDataSet

      public DataSet getDataSet()
      Retrieves the current DataSet instance associated with this object.
      Returns:
      the current DataSet instance

    • getTarget

      public String getTarget()
      Retrieves the name of the target associated with this instance.
      Returns:
      the name of the target as a String.

    • getTargetNode

      public Node getTargetNode()
      Retrieves the target node.
      Returns:
      the target node of type Node.