Class DesignMatrix

java.lang.Object
ubic.gemma.core.util.math.linearmodels.DesignMatrix
public class DesignMatrix extends Object
Represents the A matrix in regression problems posed as Ax=b. The starting point is a matrix of sample information, where the rows are sample names and the columns are the names of factors or covariates. Intercept and interaction terms can be added.

Baseline levels are initially determined by the order in which factor levels appear. You can re-level using the setBaseline method.

Author:
paul

  • Constructor Details

    • DesignMatrix

      public DesignMatrix(Object[] factor, int start, String factorName)
      Parameters:
      factor - in form of Doubles or Strings. Any other types will yield errors.
      start -

    • DesignMatrix

      public DesignMatrix(ObjectMatrix<String, String, ? extends Object> sampleInfo)
      Parameters:
      sampleInfo - in form of Doubles or Strings. Any other types will yield errors.

    • DesignMatrix

      public DesignMatrix(ObjectMatrix<String,String,?> sampleInfo, boolean intercept)
      Parameters:
      sampleInfo - in form of Doubles or Strings. Any other types will yield errors.
      intercept -

    • DesignMatrix

      public DesignMatrix(StringMatrix<String,String> sampleInfo)

    • DesignMatrix

      public DesignMatrix(ObjectMatrix<String,String,Object> design, boolean intercept, boolean strict)
      Parameters:
      design -
      intercept - whether to include an intercept in the model
      strict - whether to remove columns from the design matrix that are unlikely to be useable. By default this is "true" for other constructors.

  • Method Details

    • getInteractionTerms

      public Collection<String[]> getInteractionTerms()
      Returns:
      a collection of String arrays. If empty, there are no interactions. Each array represents an interaction in the model. The elements of the array are the terms included in the interaction, as Strings provided when calling addInteraction.

    • makeContrasts

      public DoubleMatrix2D makeContrasts()
      In limma, the contrasts are built by referring to the coefficients by name, which isn't what we want.
      Returns:

    • add

      public void add(ObjectMatrix<String,String,Object> sampleInfo)
      Append additional factors/covariates to this
      Parameters:
      sampleInfo -

    • addInteraction

      public void addInteraction()
      Add interaction term; only works if there exactly two factors so this can figure out which interaction to add. For more control use the other method.

    • addInteraction

      public void addInteraction(String... interactionTerms)
      This will not add the interaction unless all of the terms are already part of the design, and interactions that obviously can't be estimated will be dropped if possible, but otherwise this is fairly brain dead.
      Parameters:
      interactionTerms -

    • getAssign

      public List<Integer> getAssign()
      Returns:

    • getBaseline

      public String getBaseline(String factorName)

    • getDoubleMatrix

      public DoubleMatrix2D getDoubleMatrix()

    • getLevelsForFactors

      public Map<String, List<String>> getLevelsForFactors()

    • getMatrix

      public DoubleMatrix<String,String> getMatrix()

    • getDerivedLevelColumns

      public Map<String, List<Integer>> getDerivedLevelColumns()
      The contrasts a ContrastCoding.SUM_TO_ZERO factor needs but has no column for, as a map from the name such a column would have had to the design columns that determine it.

      A derived level's deviation is minus the sum of its factor's coefficients, and the variance of that sum needs the whole covariance block for those columns, not the individual variances -- which is why the columns are handed over rather than just the name. LeastSquaresFit does the arithmetic per row, where the QR for that row is in hand.

      A factor's columns are identified by exact name (factorName + level) rather than by prefix: factor names are f plus an id, so f10 is a prefix of f100 and matching on prefixes would quietly pull another factor's columns into the sum.

      🛑 A factor whose columns do not come out at one per non-derived level is left out entirely. Dropped factors, interactions and any future change to how columns are named all land here, and a contrast that is missing is something a caller notices, whereas one computed over the wrong columns is not.

      Returns:
      derived-level column name to design column indices, empty when no factor is sum-coded

    • getTerms

      public List<String> getTerms()

    • getValuesForFactors

      public Map<String, List<Object>> getValuesForFactors()

    • hasIntercept

      public boolean hasIntercept()

    • isHasIntercept

      public boolean isHasIntercept()

    • getContrastCoding

      public ContrastCoding getContrastCoding(String factorName)
      How the given factor's levels are coded into columns; ContrastCoding.TREATMENT unless set.

    • setContrastCoding

      public void setContrastCoding(String factorName, ContrastCoding coding)
      Choose how one categorical factor's levels are coded, and rebuild the design.

      Per factor rather than per matrix on purpose: a design can hold a genotype factor with a real wild-type control and a tissue factor with no control at all, and those two want different codings in the same model.

      The level that has no column of its own is the same one under either coding, so setBaseline(String, String) still decides which level is derived rather than estimated — under ContrastCoding.SUM_TO_ZERO it is not a baseline anything is measured against, only the one whose deviation is recovered from the others.

      Throws:
      IllegalArgumentException - if the factor is not in this design, or is continuous — a continuous covariate has one column and no levels, so there is nothing to code

    • setBaseline

      public void setBaseline(String factorName, String baselineFactorValue)
      Parameters:
      factorName -
      baselineFactorValue -

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • rebuild

      protected void rebuild()
      Refresh the design matrix, for example after releveling.