Class ConditionalKDE

java.lang.Object
edu.cmu.tetrad.util.ConditionalKDE
public class ConditionalKDE extends Object
Conditional Kernel Density Estimation with multivariate conditioning.

Estimates conditional distributions using a product Gaussian kernel over one or more conditioning variables. Supports:

1. Conditional univariate: p(Y | X = x) — 1D density over a grid 2. Conditional bivariate: p(Y1, Y2 | X = x) — 2D density over a grid 3. Correlation profile: rho(Y1,Y2 | X1=x1, X2 swept, ...) 4. Batch bivariate: all pairs at once, weights precomputed and shared

Performance design ------------------ - Call computeWeights(targets) once per slider position and pass the resulting double[] into any of the precomputed-weight overloads. This avoids recomputing O(n * nCond) kernel products for every pair. - batchBivariate() evaluates all requested pairs in parallel using the common ForkJoinPool, then parallelises the inner grid loop of each pair with a RecursiveAction. Adjust PARALLEL_THRESHOLD to tune granularity. - Single-pair methods expose a parallel flag; pass true when calling outside a batch (e.g. on a single highlighted cell).

Curse-of-dimensionality note ---------------------------- With k conditioning variables effective sample size falls roughly as n^(k/(k+4)). Beyond 4-5 conditioning variables you need a large dataset or explicitly widened bandwidths.

  • Constructor Details

    • ConditionalKDE

      public ConditionalKDE(double[][] condVars, double[] condBandwidths)
      Constructs a conditional kernel density estimator (KDE) with specified conditioning variables and bandwidths.
      Parameters:
      condVars - A 2D array of conditioning variables where each row represents a conditioning variable and each column corresponds to a data sample. All rows must have equal lengths.
      condBandwidths - An array of bandwidths for each conditioning variable. If null, empty, or containing non-positive values for any variable, the bandwidth for that variable will be automatically determined using Silverman's rule of thumb.
      Throws:
      IllegalArgumentException - if the length of any row in condVars is not equal to the length of the first row.

    • ConditionalKDE

      public ConditionalKDE(double[] condVar)
      Constructs a conditional kernel density estimator (KDE) with a single conditioning variable. This is a convenience constructor that wraps the single variable into a 2D array for compatibility with the main logic.
      Parameters:
      condVar - A 1D array representing the conditioning variable. Each element corresponds to a data sample.

    • ConditionalKDE

      public ConditionalKDE(double[][] condVars)
      Constructor for the ConditionalKDE class.
      Parameters:
      condVars - A 2D array where each row represents a data point and each column corresponds to a conditional variable.

  • Method Details

    • computeWeights

      public double[] computeWeights(double[] targets)
      Computes and normalises the product-kernel conditioning weights for the given target values. Call this ONCE per slider position, then pass the returned array to any precomputed-weight overload or to batchBivariate().
      Parameters:
      targets - one target value per conditioning variable (length nCond)
      Returns:
      normalised weight array of length n

    • computeWeights

      public double[] computeWeights(double target)
      Computes and returns an array of weights based on the given target value.
      Parameters:
      target - the target value to compute weights for
      Returns:
      an array of computed weights derived from the target value

    • conditionalUnivariate

      public ConditionalKDE.ConditionalResult1D conditionalUnivariate(double[] Y, double[] weights, double[] targets, int gridPoints, double yBandwidth, boolean parallel)
      Full control overload — accepts precomputed weights.
      Parameters:
      Y - response variable (length n)
      weights - precomputed from computeWeights(); null → recompute from targets
      targets - used only when weights == null
      gridPoints - grid resolution
      yBandwidth - <= 0 → Silverman auto
      parallel - true → parallelise over grid points
      Returns:
      a ConditionalResult1D object containing the computed univariate result.

    • conditionalUnivariate

      public ConditionalKDE.ConditionalResult1D conditionalUnivariate(double[] Y, double[] weights)
      Computes the conditional univariate result based on the provided data and weights.
      Parameters:
      Y - the array representing the target variable for the univariate computation.
      weights - the array of weights associated with the target variable values.
      Returns:
      the result of the conditional univariate computation encapsulated in a ConditionalResult1D object.

    • conditionalUnivariate

      public ConditionalKDE.ConditionalResult1D conditionalUnivariate(double[] Y, double target)
      Computes a conditional univariate result based on the provided parameters.
      Parameters:
      Y - The array of dependent variable values.
      target - The target value used to condition the univariate computation.
      Returns:
      A ConditionalResult1D object containing the result of the conditional univariate analysis.

    • conditionalUnivariate

      public ConditionalKDE.ConditionalResult1D conditionalUnivariate(double[] Y, double[] targets, int gridPoints, double yBandwidth)
      Computes the conditional univariate result based on the provided data and parameters.
      Parameters:
      Y - the array of observed data points for the dependent variable.
      targets - the array of target values for which the conditional univariate computation will be performed.
      gridPoints - the number of grid points to use in the computation.
      yBandwidth - the bandwidth parameter for the kernel density estimation.
      Returns:
      a ConditionalResult1D object representing the computed conditional univariate result.

    • conditionalBivariate

      public ConditionalKDE.ConditionalResult2D conditionalBivariate(double[] Y1, double[] Y2, double[] weights, double[] targets, int gridSize, double h1, double h2, boolean parallel)
      Computes the conditional bivariate density estimate for the given data points. This method uses kernel density estimation to generate a grid-based density representation.
      Parameters:
      Y1 - An array of double values representing the first dimension of the data points.
      Y2 - An array of double values representing the second dimension of the data points.
      weights - An optional array of weights for the data points. If null, weights will be computed internally.
      targets - An optional array of target values for conditioning. If null, no conditioning will be applied.
      gridSize - The number of grid points to compute along each dimension of the density grid.
      h1 - The bandwidth for the kernel in the first dimension. If less than or equal to 0, it will be calculated automatically.
      h2 - The bandwidth for the kernel in the second dimension. If less than or equal to 0, it will be calculated automatically.
      parallel - A boolean flag indicating whether to compute the density using parallel processing.
      Returns:
      A ConditionalResult2D object containing the computed density grid, grids along each dimension, weights, targets, and applied bandwidths.
      Throws:
      IllegalArgumentException - If the lengths of Y1 and Y2 do not match.

    • conditionalBivariate

      public ConditionalKDE.ConditionalResult2D conditionalBivariate(double[] Y1, double[] Y2, double[] weights)
      Computes a conditional bivariate result using the provided data arrays and weights.
      Parameters:
      Y1 - the first array of data points
      Y2 - the second array of data points
      weights - the weights corresponding to each data point
      Returns:
      a ConditionalResult2D representing the computed bivariate result

    • conditionalBivariateParallel

      public ConditionalKDE.ConditionalResult2D conditionalBivariateParallel(double[] Y1, double[] Y2, double[] weights)
      Computes a conditional bivariate result in parallel given input data arrays and weights.
      Parameters:
      Y1 - the first array of input values
      Y2 - the second array of input values
      weights - the weights associated with the input values
      Returns:
      the conditional bivariate result as an instance of ConditionalResult2D

    • conditionalBivariate

      public ConditionalKDE.ConditionalResult2D conditionalBivariate(double[] Y1, double[] Y2, double target)
      Computes a conditional bivariate result based on the provided input arrays and target value.
      Parameters:
      Y1 - the first array of data points.
      Y2 - the second array of data points.
      target - the target value used for conditioning the computation.
      Returns:
      an instance of ConditionalResult2D representing the computed conditional bivariate result.

    • conditionalBivariate

      public ConditionalKDE.ConditionalResult2D conditionalBivariate(double[] Y1, double[] Y2, double[] targets, int gridSize, double h1, double h2)
      Computes the conditional bivariate distribution for the given data and targets.
      Parameters:
      Y1 - the first array of random variable observations
      Y2 - the second array of random variable observations
      targets - the target values for conditioning
      gridSize - the size of the grid used in the computation
      h1 - the bandwidth parameter for the first variable
      h2 - the bandwidth parameter for the second variable
      Returns:
      a ConditionalResult2D object containing the computed conditional bivariate distribution

    • batchBivariate

      public ConditionalKDE.ConditionalResult2D[] batchBivariate(double[][] data, List<int[]> pairs, double[] weights, int gridSize)
      Evaluates p(Yi, Yj | X = targets) for every (i,j) pair in the supplied list, using a single shared weight vector. Pairs are evaluated in parallel via the common ForkJoinPool; the grid inner loop of each pair is also parallelised when gridSize is large enough to justify it.

      Typical plot-matrix usage: 

        double[] w = kde.computeWeights(sliderTargets);

  List<int[]> pairs = new ArrayList<>();
  for (int i = 0; i < p; i++)
      for (int j = i+1; j < p; j++)
          pairs.add(new int[]{ i, j });

  ConditionalResult2D[] results = kde.batchBivariate(data, pairs, w, 64);
      Parameters:
      data - [nVars][n] — all response variables
      pairs - list of {i, j} index pairs into data
      weights - precomputed from computeWeights()
      gridSize - grid resolution per axis
      Returns:
      results in the same order as pairs

    • batchBivariateAllPairs

      public ConditionalKDE.BatchResult batchBivariateAllPairs(double[][] data, double[] weights, int gridSize)
      Convenience form: builds all upper-triangle pairs from data automatically.
      Parameters:
      data - [nVars][n]
      weights - precomputed from computeWeights()
      gridSize - grid resolution
      Returns:
      BatchResult containing the pair index list and density results

    • conditionalCorrelationProfile

      public double[][] conditionalCorrelationProfile(double[] Y1, double[] Y2, double[] fixedTargets, int sweepIndex, int nSteps)
      Computes a conditional correlation profile between two response variables (Y1 and Y2) while sweeping through a range of values for a specified conditional variable. The correlation is calculated for each step in the sweep.
      Parameters:
      Y1 - the first response variable array; must have the same length as Y2.
      Y2 - the second response variable array; must have the same length as Y1.
      fixedTargets - an array of fixed values for the conditional variables, except for the swept variable.
      sweepIndex - the index of the conditional variable to be swept over.
      nSteps - the number of steps or points in the sweep range.
      Returns:
      a 2D array where each row contains the swept value and the corresponding weighted correlation value. The first column contains the swept variable values, and the second column contains the correlation values.
      Throws:
      IllegalArgumentException - if the lengths of Y1 and Y2 do not match, or if fixedTargets contains invalid inputs.

    • conditionalCorrelationProfile

      public double[][] conditionalCorrelationProfile(double[] Y1, double[] Y2, int nSteps)
      Computes the conditional correlation profile of two given time series over a specified number of steps. This method assumes there is only one conditioning variable.
      Parameters:
      Y1 - the first time series array
      Y2 - the second time series array
      nSteps - the number of steps for the correlation profile
      Returns:
      a 2D array representing the computed conditional correlation profile
      Throws:
      IllegalArgumentException - if more than one conditioning variable is used

    • conditionalCorrelationProfile

      public double[][] conditionalCorrelationProfile(double[] Y1, double[] Y2)
      Computes the conditional correlation profile between two input time series arrays.
      Parameters:
      Y1 - the first time series array, representing a sequence of numerical values
      Y2 - the second time series array, representing a sequence of numerical values
      Returns:
      a 2D array where each row contains the computed conditional correlation values for the corresponding lag or condition