The JAS-mine platform‎ > ‎Documentation‎ > ‎Cookbook‎ > ‎

The JAS-mine alignment algorithms

Alignment is used in dynamic microsimulation to keep the simulation outcome in line with external targets.

For the time being, only binary alignment is implemented in JAS-mine. This does not mean that alignment for continuous regressions is not possible: it only means that alignment has to be done manually, in this case (the JAS-mine development team will gratefully acknowledge contributions by the community of users and include other alignment methods in a future release).

Five binary alignment methods are implemented, in JAS-mine: 
  1. Multiplicative Scaling (MS), 
  2. Sidewalk (SW), 
  3. Sorting by the difference between predicted probability and random number (SBD), 
  4. Sorting by the difference between logistic adjusted predicted probability and random number (SBDL), and
  5. Resampling (RS). 
Implementation of (1)-(4) is based on Li and O’Donoghue (2014) (Jinjing Li kindly provided the Stata code used in that paper), while implementation of (5) closely follows Richiardi and Poggi (2014) and Leombruni and Richiardi (2006).

(1) Multiplicative scaling involves undertaking an unaligned simulation using Monte Carlo techniques and then comparing the proportion of transitions with the external control total. The average ratio between the desired transition rate and the actual transition is used as a scaling factor for the simulated probabilities. The method ensures that the average scaled simulated probability is the same as the desired transition rate. The method, however, is criticized by Morrison (2006) as probabilities are not guaranteed to stay in the range 0-1 after scaling, though the problem is rare in practice as the multiplicative ratio tends to be small.

(2) The Sidewalk method was first introduced as a variance reduction technique, which was also used as an alternative to the random number based Monte Carlo simulation. It keeps a record of the accumulated probability from the first modelled binary outcome to the last. As long as there is a change of the integer part of the accumulated probability, the observation is assigned with an outcome value of 1.

Sorting based alignment algorithms involve sorting of the predicted probability adjusted with a stochastic component, and selects desired number of events according to the sorting order:

(3) SBD sorts by the difference between the predicted probability and a random number in (0,1), while

(4) SBDL sorts by a logistic transformation of the predicted probability.

(5) Finally, Resampling involves drawing again the event, without altering the predicted probabilities, either for agents who have experienced the transition (if too many transitions have occurred) or for agents that have not experienced the transition (if too few events have occurred), until the target is reached.

Li and O’Donoghue (2014) analyze three other binary alignment algorithms: 
  1. Sidewalk with nonlinear transformation (SNT), 
  2. the central limit theorem approach (CLT) and 
  3. Sorting by predicted probability (SBP). 
SNT and CLT have not been implemented yet in JAS-mine as they are relatively more complicated and run much slower than the other methods; SBP has not been implemented due to its theoretical shortcomings and poor empirical performances (see Li and O’Donoghue, 2014).

One important thing to note is that the processes to be aligned are executed at an individual level, while alignment always takes place at the population level. That is, individual outcomes or probabilities are determined for each individual based on the chosen econometric specification and the estimated coefficients. This in general leads to a mismatch between the simulated (provisional) totals and the aggregate targets, which can of course be assessed only at the population level. The alignment algorithm then directly modifies the individual outcomes or probabilities of occurrence. 

All alignment methods in JAS-mine require 4 arguments:
  1. collection: a collection of individuals whose outcome or probability of an event has to be aligned (e.g. all the population);

  2. filter: a filter to be applied to the collection (e.g. all females selected to divorce); 

  3. alignmentProbabilityClosure or alignmentOutcomeClosure: a piece of code that i) computes for each element of the filtered collection a probability for the event (in the case that the alignment method is aligning probabilities, as in the SBD algorithm) or an outcome (in the case that the alignment method is aligning outcomes), and ii) applies to each element of the filtered collection the specific instructions coming from the alignment method used;

  4. targetShare or targetNumber: the share or number of elements in the filtered collection that are expected to experience the transition.
Here is how the SBD alignment is implemented in the Demo07 model:

new SBDAlignment<Person>().align(
    // collection
    // filter
    new FemaleToDivorce(ageFrom, ageTo),
    // alignmentProbabilityClosure
    new AlignmentProbabilityClosure<Person>() {
// i) compute the probability of divorce
        public double getProbability(Person agent) {
            return agent.computeDivorceProb();
        // ii) determine what to do with the aligned probabilities
        public void align(Person agent, double alignedProbability) {
            boolean divorce = RegressionUtils.event(alignedProbability, SimulationEngine.getRnd());                agent.setToDivorce(divorce);
    // targetShare



Leombruni R, Richiardi M (2006). LABORsim: An Agent-Based Microsimulation of Labour Supply. An application to Italy. Computational Economics, vol. 27, no. 1, pp. 63-88

Li J, O'Donoghue C (2014). “Evaluating Binary Alignment Methods in Microsimulation Models”. Journal of Artificial Societies and Social Simulation, 17(1): art. 15.

Richiardi M., Poggi A. (2014). Imputing Individual Effects in Dynamic Microsimulation Models. An application to household formation and labor market participation in Italy. International Journal of Microsimulation, 7(2), pp. 3-39.