Package edu.cmu.tetrad.sem

Class SemIm

java.lang.Object
edu.cmu.tetrad.sem.SemIm
All Implemented Interfaces:
Simulator, ISemIm, Im, TetradSerializable, Serializable
public final class SemIm extends Object implements Im, ISemIm
Stores an instantiated structural equation model (SEM), with error covariance terms, possibly cyclic, suitable for estimation and simulation. For estimation, the maximum likelihood fitting function and the negative log likelihood function (Bollen 1989, p. 109) are calculated; these can be maximized by an estimator to estimate optimal parameter values. The values of freeParameters are set as indicated in their corresponding Parameter objects as initial values for estimation. Provides multiple ways to get and set the values of free freeParameters. For simulation, cyclic and acyclic methods are provided; the cyclic method is used by default, although the acyclic method is considerably faster for large data sets.

Let V be the set of variables in the model. The freeParameters of the model are as follows: (a) the list of linear coefficients for all edges u-->v in the model, where u, v are in V, (b) the list of variances for all variables in V, (c) the list of all error covariances d<->e, where d an e are exogenous terms in the model (either exogenous variables or error terms for endogenous variables), and (d) the list of means for all variables in V.

It is important to note that the likelihood functions this class calculates do not depend on variable means. They depend only on edge coefficients and error covariances. Hence, variable means are treated differently from edge coefficients and error covariances in the model.

Reference: Bollen, K. A. (1989). Structural Equations with Latent Variables. New York: John Wiley and Sons.

Author:
Frank Wimberly, Ricardo Silva, Joseph Ramsey
See Also:

  • Constructor Details

    • SemIm

      public SemIm(SemPm semPm)
      Constructs a new SEM IM from a SEM PM.

    • SemIm

      public SemIm(SemPm semPm, Parameters params)
      Constructs a new SEM IM from the given SEM PM, using the given params object to guide the choice of parameter values.

    • SemIm

      public SemIm(SemPm semPm, SemIm oldSemIm, Parameters parameters)
      Constructs a new SEM IM from the given SEM PM, using the old SEM IM and params object to guide the choice of parameter values. If old values are retained, they are gotten from the old SEM IM.

    • SemIm

      public SemIm(SemPm semPm, ICovarianceMatrix covMatrix)
      Constructs a SEM model using the given SEM PM and sample covariance matrix.

    • SemIm

      public SemIm(SemIm semIm)
      Copy constructor.
      Throws:
      RuntimeException - if the given SemIm cannot be serialized and deserialized correctly.

    • SemIm

      public SemIm(SemPm semPm, List<Node> variableNodes, List<Node> measuredNodes, Matrix edgeCoef, double[] variableMeansStdDev)

  • Method Details

    • getParameterNames

      public static List<String> getParameterNames()

    • retainValues

      public static SemIm retainValues(SemIm semIm, SemGraph graph)
      Constructs a new SEM IM with the given graph, retaining parameter values from semIm for nodes of the same name and edges connecting nodes of the same names.
      Parameters:
      semIm - The old SEM IM.
      graph - The graph for the new SEM IM.
      Returns:
      The new SEM IM, retaining values from semIm.

    • serializableInstance

      public static SemIm serializableInstance()
      Generates a simple exemplar of this class to test serialization.

    • updatedIm

      public SemIm updatedIm(Matrix covariances, Vector means)
      Returns:
      a variant of the getModel model with the given covariance matrix and means. Used for updating.

    • setCovMatrix

      public void setCovMatrix(ICovarianceMatrix covMatrix)
      Sets the sample covariance matrix for this Sem as a submatrix of the given matrix. The variable names used in the SemPm for this model must all appear in this CovarianceMatrix.

    • setDataSet

      public void setDataSet(DataSet dataSet)
      Calculates the covariance matrix of the given DataSet and sets the sample covariance matrix for this model to a subset of it. The measured variable names used in the SemPm for this model must all appear in this data set.

    • getSemPm

      public SemPm getSemPm()
      Specified by:
      getSemPm in interface ISemIm
      Returns:
      the Digraph which describes the causal structure of the Sem.

    • getFreeParamValues

      public double[] getFreeParamValues()
      Specified by:
      getFreeParamValues in interface ISemIm
      Returns:
      an array containing the getModel values for the free freeParameters, in the order in which the freeParameters appear in getFreeParameters(). That is, getFreeParamValues()[i] is the value for getFreeParameters()[i].

    • setFreeParamValues

      public void setFreeParamValues(double[] params)
      Sets the values of the free freeParameters (in the order in which they appear in getFreeParameters()) to the values contained in the given array. That is, params[i] is the value for getFreeParameters()[i].
      Specified by:
      setFreeParamValues in interface ISemIm

    • getParamValue

      public double getParamValue(Parameter parameter)
      Gets the value of a single free parameter, or Double.NaN if the parameter is not in this
      Specified by:
      getParamValue in interface ISemIm
      Throws:
      IllegalArgumentException - if the given parameter is not a free parameter in this model.

    • setParamValue

      public void setParamValue(Parameter parameter, double value)
      Sets the value of a single free parameter to the given value.
      Specified by:
      setParamValue in interface ISemIm
      Throws:
      IllegalArgumentException - if the given parameter is not a free parameter in this model.

    • setFixedParamValue

      public void setFixedParamValue(Parameter parameter, double value)
      Sets the value of a single free parameter to the given value.
      Specified by:
      setFixedParamValue in interface ISemIm
      Throws:
      IllegalArgumentException - if the given parameter is not a free parameter in this model.

    • getErrVar

      public double getErrVar(Node x)

    • getErrCovar

      public double getErrCovar(Node x, Node y)

    • getEdgeCoef

      public double getEdgeCoef(Node x, Node y)

    • getEdgeCoef

      public double getEdgeCoef(Edge edge)

    • setErrVar

      public void setErrVar(Node x, double value)
      Specified by:
      setErrVar in interface ISemIm

    • setEdgeCoef

      public void setEdgeCoef(Node x, Node y, double value)
      Specified by:
      setEdgeCoef in interface ISemIm

    • existsEdgeCoef

      public boolean existsEdgeCoef(Node x, Node y)

    • setErrCovar

      public void setErrCovar(Node x, double value)

    • setErrCovar

      public void setErrCovar(Node x, Node y, double value)

    • setMean

      public void setMean(Node node, double mean)
      Sets the mean associated with the given node.
      Specified by:
      setMean in interface ISemIm

    • setMeanStandardDeviation

      public void setMeanStandardDeviation(Node node, double mean)
      Sets the mean associated with the given node.

    • setIntercept

      public void setIntercept(Node node, double intercept)
      Sets the intercept. For acyclic SEMs only.
      Specified by:
      setIntercept in interface ISemIm
      Throws:
      UnsupportedOperationException - if called on a cyclic SEM.

    • getIntercept

      public double getIntercept(Node node)
      Specified by:
      getIntercept in interface ISemIm
      Returns:
      the intercept, for acyclic models, or Double.NaN otherwise.
      Throws:
      UnsupportedOperationException - if called on a cyclic SEM.

    • getMean

      public double getMean(Node node)
      Specified by:
      getMean in interface ISemIm
      Returns:
      the value of the mean assoc iated with the given node.

    • getMeans

      public double[] getMeans()
      Returns:
      the means for variables in order.

    • getMeanStdDev

      public double getMeanStdDev(Node node)
      Specified by:
      getMeanStdDev in interface ISemIm
      Returns:
      the value of the mean associated with the given node.

    • getVariance

      public double getVariance(Node node, Matrix implCovar)
      Specified by:
      getVariance in interface ISemIm
      Returns:
      the value of the variance associated with the given node.

    • getStdDev

      public double getStdDev(Node node, Matrix implCovar)
      Specified by:
      getStdDev in interface ISemIm
      Returns:
      the value of the standard deviation associated with the given node.

    • getParamValue

      public double getParamValue(Node nodeA, Node nodeB)
      Gets the value of a single free parameter to the given value, where the free parameter is specified by the endpoint nodes of its edge in the w graph. Note that coefficient freeParameters connect elements of getVariableNodes(), whereas variance and covariance freeParameters connect elements of getExogenousNodes(). (For variance freeParameters, nodeA and nodeB are the same.)
      Specified by:
      getParamValue in interface ISemIm
      Throws:
      IllegalArgumentException - if the given parameter is not a free parameter in this model or if there is no parameter connecting nodeA with nodeB in this model.

    • setParamValue

      public void setParamValue(Node nodeA, Node nodeB, double value)
      Sets the value of a single free parameter to the given value, where the free parameter is specified by the endpoint nodes of its edge in the graph. Note that coefficient freeParameters connect elements of getVariableNodes(), whereas variance and covariance freeParameters connect elements of getExogenousNodes(). (For variance freeParameters, nodeA and nodeB are the same.)
      Specified by:
      setParamValue in interface ISemIm
      Throws:
      IllegalArgumentException - if the given parameter is not a free parameter in this model or if there is no parameter connecting nodeA with nodeB in this model, or if value is Double.NaN.

    • getFreeParameters

      public List<Parameter> getFreeParameters()
      Specified by:
      getFreeParameters in interface ISemIm
      Returns:
      the (unmodifiable) list of free freeParameters in the model.

    • getNumFreeParams

      public int getNumFreeParams()
      Specified by:
      getNumFreeParams in interface ISemIm
      Returns:
      the number of free freeParameters.

    • getFixedParameters

      public List<Parameter> getFixedParameters()
      Specified by:
      getFixedParameters in interface ISemIm
      Returns:
      the (unmodifiable) list of fixed freeParameters in the model.

    • getNumFixedParams

      public int getNumFixedParams()
      Returns:
      the number of free freeParameters.

    • getVariableNodes

      public List<Node> getVariableNodes()
      The list of measured and latent nodes for the semPm. (Unmodifiable.)
      Specified by:
      getVariableNodes in interface ISemIm

    • getMeasuredNodes

      public List<Node> getMeasuredNodes()
      The list of measured nodes for the semPm. (Unmodifiable.)
      Specified by:
      getMeasuredNodes in interface ISemIm

    • getSampleSize

      public int getSampleSize()
      Specified by:
      getSampleSize in interface ISemIm
      Returns:
      the sample size (that is, the sample size of the CovarianceMatrix provided at construction time).

    • getEdgeCoef

      public Matrix getEdgeCoef()
      Returns:
      a copy of the matrix of edge coefficients. Note that edgeCoefC[i][j] is the coefficient of the edge from getVariableNodes().get(i) to getVariableNodes().get(j), or 0.0 if this edge is not in the graph. The values of these may be changed, but the array itself may not.

    • getErrCovar

      public Matrix getErrCovar()
      Returns:
      a copy of the matrix of error covariances. Note that errCovar[i][j] is the covariance of the error term of getExoNodes().get(i) and getExoNodes().get(j), with the special case (duh!) that errCovar[i][i] is the variance of getExoNodes.get(i). The values of these may be changed, but the array itself may not.

    • getImplCovar

      public Matrix getImplCovar(boolean recalculate)
      Specified by:
      getImplCovar in interface ISemIm
      Returns:
      a copy of the implied covariance matrix over all the variables.

    • getImplCovarMeas

      public Matrix getImplCovarMeas()
      Specified by:
      getImplCovarMeas in interface ISemIm
      Returns:
      a copy of the implied covariance matrix over the measured variables only.

    • getSampleCovar

      public Matrix getSampleCovar()
      Returns:
      a copy of the sample covariance matrix, or null if no sample covar has been set.

    • getScore

      public double getScore()
      The value of the maximum likelihood function for the getModel the model (Bollen 107). To optimize, this should be minimized.
      Specified by:
      getScore in interface ISemIm

    • getTruncLL

      public double getTruncLL()
      The negative of the log likelihood function for the getModel model, with the constant chopped off. (Bollen 134). This is an alternative, more efficient, optimization function to Fml which produces the same result when minimized.

    • getBicScore

      public double getBicScore()
      Specified by:
      getBicScore in interface ISemIm
      Returns:
      BIC score, calculated as chisq - dof. This is equal to getFullBicScore() up to a constant.

    • getRmsea

      public double getRmsea()
      Specified by:
      getRmsea in interface ISemIm

    • getCfi

      public double getCfi()
      Specified by:
      getCfi in interface ISemIm

    • getChiSquare

      public double getChiSquare()
      Specified by:
      getChiSquare in interface ISemIm
      Returns:
      the chi square value for the model.

    • getPValue

      public double getPValue()
      Specified by:
      getPValue in interface ISemIm
      Returns:
      the p-value for the model.

    • simulateData

      public DataSet simulateData(int sampleSize, boolean latentDataSaved)
      This simulate method uses the implied covariance metrix directly to simulate data, instead of going tier by tier. It should work for cyclic graphs as well as acyclic graphs.
      Specified by:
      simulateData in interface Simulator

    • setScoreType

      public void setScoreType(ScoreType scoreType)

    • simulateDataCholesky

      public DataSet simulateDataCholesky(int sampleSize, boolean latentDataSaved)
      Simulates data from this Sem using a Cholesky decomposition of the implied covariance matrix. This method works even when the underlying graph is cyclic.
      Parameters:
      sampleSize - the number of rows of data to simulate.
      latentDataSaved - True iff data for latents should be saved.

    • simulateDataRecursive

      public DataSet simulateDataRecursive(int sampleSize, boolean latentDataSaved)

    • simulateDataReducedForm

      public DataSet simulateDataReducedForm(int sampleSize, boolean latentDataSaved)

    • simulateOneRecord

      public Vector simulateOneRecord(Vector e)

    • initializeValues

      public void initializeValues()
      Iterates through all freeParameters, picking values for them from the distributions that have been set for them.

    • getStandardError

      public double getStandardError(Parameter parameter, int maxFreeParams)
      Specified by:
      getStandardError in interface ISemIm

    • listUnmeasuredLatents

      public List<Node> listUnmeasuredLatents()
      Specified by:
      listUnmeasuredLatents in interface ISemIm

    • getTValue

      public double getTValue(Parameter parameter, int maxFreeParams)
      Specified by:
      getTValue in interface ISemIm

    • getPValue

      public double getPValue(Parameter parameter, int maxFreeParams)
      Specified by:
      getPValue in interface ISemIm

    • isParameterBoundsEnforced

      public boolean isParameterBoundsEnforced()
      Specified by:
      isParameterBoundsEnforced in interface ISemIm

    • setParameterBoundsEnforced

      public void setParameterBoundsEnforced(boolean parameterBoundsEnforced)
      Specified by:
      setParameterBoundsEnforced in interface ISemIm

    • isEstimated

      public boolean isEstimated()
      Specified by:
      isEstimated in interface ISemIm

    • setEstimated

      public void setEstimated(boolean estimated)

    • isCyclic

      public boolean isCyclic()
      Specified by:
      isCyclic in interface ISemIm

    • getVariableNode

      public Node getVariableNode(String name)
      Returns:
      the variable by the given name, or null if none exists.
      Throws:
      NullPointerException - if name is null.

    • toString

      public String toString()
      Overrides:
      toString in class Object
      Returns:
      a string representation of the Sem (pretty detailed).

    • getParams

      public Parameters getParams()

    • setParams

      public void setParams(Parameters params)

    • getVariableMeans

      public double[] getVariableMeans()

    • isSimulatedPositiveDataOnly

      public boolean isSimulatedPositiveDataOnly()
      Specified by:
      isSimulatedPositiveDataOnly in interface ISemIm

    • getImplCovar

      public Matrix getImplCovar(List<Node> nodes)