Class KnowledgeTierStructure

java.lang.Object
edu.cmu.tetrad.data.KnowledgeTierStructure
All Implemented Interfaces:
TetradSerializable, Serializable
public final class KnowledgeTierStructure extends Object implements TetradSerializable
An additional, named tier structure over (a subset of) the variables of a Knowledge object, independent of the main temporal tiers and of every other tier structure. Within one structure, edges from a later tier to an earlier tier are forbidden, and a tier may additionally forbid edges within itself; variables of different structures (or of a structure and the main tiers) constrain one another only through whatever other knowledge mentions them.

This exists for data sets whose variables carry several temporal orderings at once -- for example a course data set with one ordering over the exams, another over the module checkpoints, and another over the unit completions -- which a single tier list cannot represent without also forbidding edges between the orderings.

Unlike the main tiers, the within-tier and ordering constraints of a tier structure are stored here directly, as the structure itself, and Knowledge consults the structure when asked whether an edge is forbidden; nothing is compiled into pairwise rules.

A variable may belong to at most one tier of a given structure, but may appear in any number of structures and in the main tiers at the same time. Variable names are held as plain names; wildcards are not interpreted here.

Mutable; instances are shared with editors, which edit them in place.

Author:
josephramsey
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    KnowledgeTierStructure(String name)
    Constructs an empty tier structure with the given name.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addToTier(int tier, String var)
    Adds the given variable to the given tier of this structure, removing it from any other tier of this structure first.
    void
    ensureTiers(int tier)
    Ensures that tiers 0..tier exist.
    boolean
    equals(Object o)
    Compares this structure with the given object for equality of name, tiers, and within-tier flags.
    String
    getName()
    Returns the display name of this structure.
    int
    getNumTiers()
    Returns the number of tiers in this structure.
    List<String>
    getTier(int tier)
    Returns a copy of the given tier, in natural sort order.
    Set<String>
    getVariables()
    Returns the set of variable names appearing in some tier of this structure.
    int
    hashCode()
    Computes a hashcode.
    boolean
    isEmpty()
    Returns whether no tier of this structure contains a variable.
    boolean
    isForbidden(String var1, String var2)
    Returns whether the edge var1 --> var2 is forbidden by this structure: var1 lies in a later tier than var2, or they lie in the same tier and that tier forbids edges within itself.
    int
    isInWhichTier(String var)
    Returns the index of the tier of this structure containing the variable, or -1.
    boolean
    isTierForbiddenWithin(int tier)
    Returns whether edges within the given tier are forbidden.
    void
    removeFromTiers(String var)
    Removes the given variable from every tier of this structure.
    static KnowledgeTierStructure
    serializableInstance()
    Generates a simple exemplar of this class to test serialization.
    void
    setName(String name)
    Sets the display name of this structure.
    void
    setTierForbiddenWithin(int tier, boolean forbidden)
    Forbids edges within the given tier, or cancels this forbidding.
    String
    toString()
    Returns a short description of this structure.
    void
    trimTrailingEmptyTiers()
    Removes empty tiers from the end of the structure, so that saved and rendered forms do not accumulate trailing blanks.

    Methods inherited from class Object

    getClass, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • KnowledgeTierStructure

      public KnowledgeTierStructure(String name)
      Constructs an empty tier structure with the given name.
      Parameters:
      name - the display name; may contain spaces but not be null or blank

  • Method Details

    • serializableInstance

      public static KnowledgeTierStructure serializableInstance()
      Generates a simple exemplar of this class to test serialization.
      Returns:
      a KnowledgeTierStructure object

    • getName

      public String getName()
      Returns the display name of this structure.
      Returns:
      the name

    • setName

      public void setName(String name)
      Sets the display name of this structure.
      Parameters:
      name - the new name; may contain spaces but not be null or blank

    • getNumTiers

      public int getNumTiers()
      Returns the number of tiers in this structure.
      Returns:
      the number of tiers

    • ensureTiers

      public void ensureTiers(int tier)
      Ensures that tiers 0..tier exist.
      Parameters:
      tier - the largest tier index that must exist

    • addToTier

      public void addToTier(int tier, String var)
      Adds the given variable to the given tier of this structure, removing it from any other tier of this structure first.
      Parameters:
      tier - the tier index, a non-negative integer
      var - the variable name

    • removeFromTiers

      public void removeFromTiers(String var)
      Removes the given variable from every tier of this structure.
      Parameters:
      var - the variable name

    • getTier

      public List<String> getTier(int tier)
      Returns a copy of the given tier, in natural sort order.
      Parameters:
      tier - the tier index
      Returns:
      the variables in that tier

    • isInWhichTier

      public int isInWhichTier(String var)
      Returns the index of the tier of this structure containing the variable, or -1.
      Parameters:
      var - the variable name
      Returns:
      the tier index, or -1 if the variable is in no tier of this structure

    • isTierForbiddenWithin

      public boolean isTierForbiddenWithin(int tier)
      Returns whether edges within the given tier are forbidden.
      Parameters:
      tier - the tier index
      Returns:
      true iff edges within the tier are forbidden

    • setTierForbiddenWithin

      public void setTierForbiddenWithin(int tier, boolean forbidden)
      Forbids edges within the given tier, or cancels this forbidding.
      Parameters:
      tier - the tier index
      forbidden - true to forbid edges within the tier

    • isForbidden

      public boolean isForbidden(String var1, String var2)
      Returns whether the edge var1 --> var2 is forbidden by this structure: var1 lies in a later tier than var2, or they lie in the same tier and that tier forbids edges within itself. Distinct variables only; a variable never forbids itself.
      Parameters:
      var1 - the name of the would-be parent
      var2 - the name of the would-be child
      Returns:
      true iff the edge is forbidden by this structure

    • getVariables

      public Set<String> getVariables()
      Returns the set of variable names appearing in some tier of this structure.
      Returns:
      the union of the tiers

    • isEmpty

      public boolean isEmpty()
      Returns whether no tier of this structure contains a variable.
      Returns:
      true iff every tier is empty

    • trimTrailingEmptyTiers

      public void trimTrailingEmptyTiers()
      Removes empty tiers from the end of the structure, so that saved and rendered forms do not accumulate trailing blanks. Interior empty tiers are kept, since tier indices are meaningful.

    • hashCode

      public int hashCode()
      Computes a hashcode.
      Overrides:
      hashCode in class Object
      Returns:
      a hashcode

    • equals

      public boolean equals(Object o)
      Compares this structure with the given object for equality of name, tiers, and within-tier flags.
      Overrides:
      equals in class Object
      Parameters:
      o - the object to compare with
      Returns:
      true iff the two are equal

    • toString

      public String toString()
      Returns a short description of this structure.
      Overrides:
      toString in class Object
      Returns:
      a string naming the structure and its tiers