Package microsim.alignment.outcome

Class ResamplingAlignment<T>

java.lang.Object
microsim.alignment.outcome.ResamplingAlignment<T>
All Implemented Interfaces:
AlignmentUtils<T>
public class ResamplingAlignment<T> extends Object implements AlignmentUtils<T>
Aligns the population by resampling of data with (or without) corresponding weights. This involves picking an agent from the relevant collection at random with a probability that depends on an associated weight in the case of weighted agents or uniformly otherwise. The chosen agent then undergoes resampling of its relevant attribute (as specified by the AlignmentOutcomeClosure). This process is continued until either the alignment target is reached, or the maximum number of attempts to resample has been reached.
See Also:
Implementation Requirements:
This method is for events with binary outcomes 0, 1 only.

  • Field Details

    • avgResampleAttempts

      public static final int avgResampleAttempts
      Constant: 20.
      See Also:

  • Constructor Details

    • ResamplingAlignment

      public ResamplingAlignment()

  • Method Details

    • align

      public void align(@NonNull @NonNull Collection<T> agents, @Nullable @Nullable org.apache.commons.collections4.Predicate<T> filter, @NonNull @NonNull AlignmentOutcomeClosure<T> closure, double targetShare)
      maxResamplingAttempts defaults to -1.
      See Also:

    • align

      public void align(@NonNull @NonNull Collection<T> agents, @Nullable @Nullable org.apache.commons.collections4.Predicate<T> filter, @NonNull @NonNull AlignmentOutcomeClosure<T> closure, int targetNumber)
      maxResamplingAttempts defaults to -1.
      See Also:

    • align

      public void align(@NonNull @NonNull Collection<T> agents, @Nullable @Nullable org.apache.commons.collections4.Predicate<T> filter, @NonNull @NonNull AlignmentOutcomeClosure<T> closure, double targetShare, int maxResamplingAttempts)
      Align share of population by resampling. This involves picking an agent from the relevant collection of agents at random with a probability that depends on an associated weight or uniformly if no weights exists. The chosen agent then undergoes resampling of its relevant attribute (as specified by the AlignmentOutcomeClosure). This process is continued until either the alignment target is reached, or the maximum number of attempts to resample has been reached, as specified by the maxResamplingAttempts parameter, or - if the input data is weighted - the pool of agents has been exhausted.
      Parameters:
      agents - A list of agents to potentially be resampled; the agent class may implement the Weight interface if needed by providing a Weight.getWeight() method. In the case of the alignment algorithm, Weight.getWeight() must return a non-negative value.
      filter - Filters the agents parameter so that only the relevant sub-population of agents is sampled, can be null.
      closure - AlignmentOutcomeClosure that specifies how to define the outcome of the agent and how to resample it.
      targetShare - The target share of the relevant subpopulation (specified as a proportion of the filtered population) for which the outcome (defined by the AlignmentOutcomeClosure) must be true.
      maxResamplingAttempts - The maximum number of attempts to resample before terminating the alignment. Introduced for situations when the resampling (as defined by the AlignmentOutcomeClosure) is unable to alter the outcomes of enough agents, due to the nature of the subpopulation and the definition of the outcome (i.e. if agents' attributes are so far away from a binary outcome threshold boundary, that the probability of enough of them switching to the desired outcome is vanishingly small). If lower than the size of the subset of the population whose outcomes need changing (or negative) the number is automatically enlarged to the default value of 20 times the size of the subset of the population to be resampled in order to move the delta between the simulation and the target towards 0. Therefore, in order to improve this delta, a member of the population undergoing alignment will be resampled up to a maximum of 20 times on average in order to change their outcome, before the alignment algorithm will give up and terminate.
      Throws:
      IllegalArgumentException - when targetShare is out of [0,1] range.
      NullPointerException - when agents, or closure, or both are null.
      Implementation Requirements:
      targetNumber is rounded down for the sake of consistency.

    • align

      public void align(@NonNull @NonNull Collection<T> agents, @Nullable @Nullable org.apache.commons.collections4.Predicate<T> filter, @NonNull @NonNull AlignmentOutcomeClosure<T> closure, int targetNumber, int maxResamplingAttempts)
      Align absolute number of population by weighted resampling. This involves picking an agent from the relevant collection of agents at random with a probability that depends on an associated weight. The chosen agent then undergoes resampling of its relevant attribute (as specified by the AlignmentOutcomeClosure). This process is continued until either the alignment target is reached, or the maximum number of attempts to resample has been reached, as specified by the maxResamplingAttempts parameter.
      Parameters:
      agents - A list of agents to potentially be resampled; the agent class must implement the Weight interface by providing a getWeight() method. In the case of the alignment algorithm, getWeight() must return a positive value.
      filter - Filters the agents so that only the relevant subpopulation of agents is sampled, can be null.
      closure - AlignmentOutcomeClosure that specifies how to define the outcome of the agent and how to resample it.
      targetNumber - The target number of the filtered population for which the outcome (defined by the AlignmentOutcomeClosure) must be true.
      maxResamplingAttempts - The maximum number of attempts to resample before terminating the alignment. Introduced for situations when the resampling (as defined by the AlignmentOutcomeClosure) is unable to alter the outcomes of enough agents, due to the nature of the subpopulation and the definition of the outcome (i.e. if agents' attributes are so far away from a binary outcome threshold boundary, that the probability of enough of them switching to the desired outcome is vanishingly small). If lower than the size of the subset of the population whose outcomes need changing (or negative) the number is automatically enlarged to the default value of 20 times the size of the subset of the population to be resampled in order to move the delta between the simulation and the target towards 0. Therefore, in order to improve this delta, a member of the population undergoing alignment will be resampled up to a maximum of 20 times on average in order to change their outcome, before the alignment algorithm will give up and terminate.
      Throws:
      IllegalArgumentException - when targetNumber is negative or exceeds the population size.
      NullPointerException - when agents, or closure, or both are null.

    • doAlignment

      public void doAlignment(@NonNull @NonNull List<T> list, @NonNull @NonNull AlignmentOutcomeClosure<T> closure, double targetNumber, int maxResamplingAttempts)
      The main alignment method. Calculates the difference between the target value and the actual sum of all positive (weighted) outcomes. Depending on the sign of this delta, resamples the agent (tries to change the outcome value).
      Parameters:
      list - A list of agents.
      closure - A closure object to update the state of an agent.
      targetNumber - The target sum of positive outcomes.
      maxResamplingAttempts - The total number of resampling attempts, if reached, the method picks randomly another agent.
      Throws:
      NullPointerException - when list, or closure. or both are null.
      Implementation Requirements:
      The list argument here is already filtered for the relevant agents in a corresponding align method., Consistent delta comparison for all cases: compare to zero every time., Consistent values of initial delta for given target numbers and equivalent target shares. Say, when there are 12 positive outcomes and the target number is 9, the equivalent target share must be 0.75 and - provided the rng seed stays the same - results must be identical., Resampling number adjustment is different for different signs of delta.