Class IBSGroup

Object
IBSGroup
public class IBSGroup extends Object
Interaction and reference groups in IBS models.
Author:
Christoph Hauert

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private class 
    IBSGroup.HierarchyUnit
    Internal class to store hierarchy unit information.
    static enum 
    IBSGroup.SamplingType
    Types of sampling of groups for interactions or references: none no interactions all interact with all neighbours random interact with n random neighbours

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final int[]
    empty
    Shared empty group returned when no neighbours are sampled.
    (package private) int
    focal
    The index of the focal individual.
    (package private) AbstractGeometry
    geometry
    The geometry associated with this group.
    (package private) int[]
    group
    Reference to the indices of the members of the group.
    private static int[]
    loner
    The empty neighbourhood of a lone individual.
    private int[]
    mem
    Storage for selected interaction or reference groups.
    (package private) int
    nSampled
    The effective sample size.
    (package private) int
    nSamples
    The sample size requested.
    protected RNGDistribution
    rng
    The shared random number generator to ensure reproducibility of results.
    (package private) IBSGroup.SamplingType
    samplingType
    The current sampling type for the formation of interaction or reference groups.
    (package private) boolean
    self
    The flag indicating whether to include the focal individual when sampling.

  • Constructor Summary

    Constructors
    Constructor
    Description
    IBSGroup(RNGDistribution rng)
    Create a new interaction or competition group.

  • Method Summary

    Modifier and Type
    Method
    Description
    private void
    calcHierarchyUnit(IBSGroup.HierarchyUnit hu)
    Calculate hierarchy unit information.
    int
    getFocal()
    Gets the index of the focal individual.
    int[]
    getGroup()
    Gets the array of indices of the interaction/reference group members.
    int
    getNSampled()
    Get the number of interactions with random neighbours.
    int
    getNSamples()
    Get the number of interactions with random neighbours.
    IBSGroup.SamplingType
    getSampling()
    Gets the type of sampling of interaction/reference groups.
    boolean
    getSelf()
    Gets whether random sampling includes the focal individual or not.
    boolean
    isSampling(IBSGroup.SamplingType type)
    Checks whether the type of sampling of interaction/reference groups is type.
    int[]
    pickAt(int me, boolean downstream)
    Picks an interaction/reference group for the focal individual focal and the population structure geom.
    (package private) void
    pickGroup(int size)
    Pick group of nSampled random individuals with indices 0 - (size-1).
    (package private) void
    pickGroup(int size, int focal)
    Pick group of nSampled random individuals with indices 0 - (size-1).
    private int[]
    pickHierarchyMean(IBSGroup.HierarchyUnit hu, boolean downstream)
    Pick a single random individual in hierarchical mean-field structure either from the outgoing (downstream) or incoming (upstream) neighbours.
    private int[]
    pickHierarchySquare(IBSGroup.HierarchyUnit hu, boolean downstream)
    Pick a single random individual in hierarchical square lattice structure either from the outgoing (downstream) or incoming (upstream) neighbours.
    private int[]
    pickRandom(int size)
    Pick group of nSamples random individual with indices 0 - (size-1).
    private int[]
    pickRandomHierarchy(boolean downstream)
    Pick group of nSamples random individual in hierarchical structures either from the outgoing (downstream) or incoming (upstream) neighbours.
    private int[]
    pickRandomStructured(boolean downstream)
    Pick group of nSamples random individual in structured populations either from the outgoing (downstream) or incoming (upstream) neighbours.
    private void
    pickSingle(int size)
    Pick a single random individual with indices 0 - (size-1).
    void
    setGeometry(AbstractGeometry geometry)
    Set the geometry associated with this group.
    void
    setGroupAt(int focal, int[] group, int size)
    Sets the interaction/reference group to group with a size size and the focal indiviual focal.
    void
    setNSamples(int nSamples)
    Set the number of interactions with random neighbours.
    void
    setSampling(IBSGroup.SamplingType type)
    Sets the type of sampling of interaction/reference groups to type.
    void
    setSelf(boolean self)
    Sets whether random sampling should include the focal individual or not.

    Methods inherited from class Object

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

  • Field Details

    • loner

      private static int[] loner
      The empty neighbourhood of a lone individual.

    • geometry

      AbstractGeometry geometry
      The geometry associated with this group.

    • mem

      private int[] mem
      Storage for selected interaction or reference groups.

    • group

      int[] group
      Reference to the indices of the members of the group.

    • focal

      int focal
      The index of the focal individual.

    • rng

      protected RNGDistribution rng
      The shared random number generator to ensure reproducibility of results.
      See Also:

    • samplingType

      IBSGroup.SamplingType samplingType
      The current sampling type for the formation of interaction or reference groups.

    • nSamples

      int nSamples
      The sample size requested. Default is a single sample for RANDOM sampling.

    • nSampled

      int nSampled
      The effective sample size. nSampled < nSamples may hold depending on the population structure.

    • self

      boolean self
      The flag indicating whether to include the focal individual when sampling.

      Notes

      In the original Moran process the offspring can replace the parent. Hence, for reference groups in well-mixed populations it makes sense to include the focal individual. In contrast, self-interactions may simplify some analytical considerations but in IBS never make sense.

    • empty

      private static final int[] empty
      Shared empty group returned when no neighbours are sampled.

  • Constructor Details

    • IBSGroup

      public IBSGroup(RNGDistribution rng)
      Create a new interaction or competition group. The global, shared random number generator rng must be passed here to ensure reproducibility of the simulation results.

      Note: The default (empty) constructor does not need to be declared private in order to prevent instantiation. The compiler does not generate a default constructor if another one exists.

      Parameters:
      rng - the random number generator for picking interaction or reference groups

  • Method Details

    • setGeometry

      public void setGeometry(AbstractGeometry geometry)
      Set the geometry associated with this group.
      Parameters:
      geometry - the geometry associated with group

    • setSampling

      public void setSampling(IBSGroup.SamplingType type)
      Sets the type of sampling of interaction/reference groups to type.
      Parameters:
      type - the type of sampling

    • getSampling

      public IBSGroup.SamplingType getSampling()
      Gets the type of sampling of interaction/reference groups.
      Returns:
      the type of sampling

    • getNSamples

      public int getNSamples()
      Get the number of interactions with random neighbours.
      Returns:
      the number of interactions

    • setNSamples

      public void setNSamples(int nSamples)
      Set the number of interactions with random neighbours.
      Parameters:
      nSamples - the number of interactions

    • isSampling

      public boolean isSampling(IBSGroup.SamplingType type)
      Checks whether the type of sampling of interaction/reference groups is type.
      Parameters:
      type - the sampling type to check
      Returns:
      true if the type of sampling is type

    • getNSampled

      public int getNSampled()
      Get the number of interactions with random neighbours.
      Returns:
      the number of interactions

    • setSelf

      public void setSelf(boolean self)
      Sets whether random sampling should include the focal individual or not.
      Parameters:
      self - true if sampling includes focal

    • getSelf

      public boolean getSelf()
      Gets whether random sampling includes the focal individual or not.
      Returns:
      true if sampling includes focal

    • setGroupAt

      public void setGroupAt(int focal, int[] group, int size)
      Sets the interaction/reference group to group with a size size and the focal indiviual focal.
      Parameters:
      focal - the index of the focal individual
      group - the array with the indices of the members of the group
      size - the size of the group

    • getGroup

      public int[] getGroup()
      Gets the array of indices of the interaction/reference group members.
      Returns:
      the interaction/reference group

    • getFocal

      public int getFocal()
      Gets the index of the focal individual.
      Returns:
      the index of the focal individual

    • pickAt

      public int[] pickAt(int me, boolean downstream)
      Picks an interaction/reference group for the focal individual focal and the population structure geom. If the flag out == true then the group is sampled from the outgoing neighbours (downstream) of the focal and from the incoming neighbours (upstream) otherwise.

      Important: For efficiency the sampled group may be a direct reference to the population structure. For example, group = out[focal] to reference all neighbours of the focal individual. As a consequence the array group is untouchable and must never be manipulated because this would result in permanent changes of the population structure.

      Parameters:
      me - the index of the focal individual
      downstream - the flag indicating whether to sample the group from the outgoing (downstream) or incoming (upstream) neighbours
      Returns:
      the interaction/reference group (same as group)
      See Also:

    • pickRandom

      private int[] pickRandom(int size)
      Pick group of nSamples random individual with indices 0 - (size-1). The focal individual is included if self==true.
      Parameters:
      size - the maximum index to pick
      Returns:
      the picked group

    • pickRandomStructured

      private int[] pickRandomStructured(boolean downstream)
      Pick group of nSamples random individual in structured populations either from the outgoing (downstream) or incoming (upstream) neighbours.
      Parameters:
      downstream - the flag to indicating sampling from ownstream
      Returns:
      the picked group

    • pickRandomHierarchy

      private int[] pickRandomHierarchy(boolean downstream)
      Pick group of nSamples random individual in hierarchical structures either from the outgoing (downstream) or incoming (upstream) neighbours.
      Parameters:
      downstream - the flag to indicating sampling from ownstream
      Returns:
      the picked group

    • calcHierarchyUnit

      private void calcHierarchyUnit(IBSGroup.HierarchyUnit hu)
      Calculate hierarchy unit information.
      Parameters:
      hu - the hierarchy unit

    • pickHierarchyMean

      private int[] pickHierarchyMean(IBSGroup.HierarchyUnit hu, boolean downstream)
      Pick a single random individual in hierarchical mean-field structure either from the outgoing (downstream) or incoming (upstream) neighbours.
      Parameters:
      hu - the hierarchy unit
      downstream - the flag to indicating sampling from ownstream
      Returns:
      the picked group

    • pickHierarchySquare

      private int[] pickHierarchySquare(IBSGroup.HierarchyUnit hu, boolean downstream)
      Pick a single random individual in hierarchical square lattice structure either from the outgoing (downstream) or incoming (upstream) neighbours.
      Parameters:
      hu - the hierarchy unit
      downstream - the flag to indicating sampling from ownstream
      Returns:
      the picked group

    • pickSingle

      private void pickSingle(int size)
      Pick a single random individual with indices 0 - (size-1). The focal individual is included if self==true.
      Parameters:
      size - the upper bound of indices to pick (excluding)

    • pickGroup

      void pickGroup(int size)
      Pick group of nSampled random individuals with indices 0 - (size-1). The focal individual is included.
      Parameters:
      size - the upper bound of indices to pick (excluding)

    • pickGroup

      void pickGroup(int size, int focal)
      Pick group of nSampled random individuals with indices 0 - (size-1). The focal individual is excluded.
      Parameters:
      size - the upper bound of indices to pick (excluding)
      focal - the index of the individual to exclude