5.7. Step 7: Base Immigration

5.7.1. Model Description

At this step we add a module for immigration based on age, sex and district of landing. This is a simple version of immigration resembling a typical macro population projection approach.

5.7.2. The new module: ImmigrationAgeSexDistrict.mpp

This module implements a base version of immigration. It is based on the number of projected immigrants by age, sex and district, which is a typical approach in cohort-component models. The module can be switched on/off by the user.

Model parameters are the number and sex of immigrants by year, the age distribution by sex, and the distribution of destination districts by sex and age. Immigrants are created at birth and live abroad until the moment of immigration.

Adding immigrants require some code additions in other modules as they have to be created and added to the simulated population (this is done in the Simulation() function in the model_core.mpp module) and their states have to be initialized (which is done in the Start() function in PersonCore.mpp). The total number of immigrants is calculated in the PreSimuation() phase, where a model-generated parameter is set. Depending on the actor weight determined in the Simulation() function, the simulated number of the immigrant sample is determined there.

////////////////////////////////////////////////////////////////////////////////////////////////////
// Parameters
////////////////////////////////////////////////////////////////////////////////////////////////////

parameters
{
    logical     ModelImmigration;                       //EN Switch immigration on/off
    double      NumberImmigrants[SIM_YEAR_RANGE][SEX];  //EN Number of immigrants
    cumrate     AgeImmigrants[SEX][AGE_RANGE];          //EN Age distribution of immigrants

    //EN Destination of immigrants
    cumrate     DestinationImmigrants[SEX][AGE5_PART][DISTRICT_NAT];

   //EN Number of immigrants (for sampling, determined in presimulation)
    model_generated cumrate[2] NumberImmigrantsTable[SIM_YEAR_RANGE][SEX];

    //EN Total number of immigrants (determined in presiulation)
    model_generated long ImmiPopSize;
};

parameter_group PG_Immigration                      //EN Base Immigration
{
    ModelImmigration, NumberImmigrants, AgeImmigrants, DestinationImmigrants
};

////////////////////////////////////////////////////////////////////////////////////////////////////
// Actor block
////////////////////////////////////////////////////////////////////////////////////////////////////

actor Person
{
    DISTRICT_NAT    district_immi = { DISTN_00 };               //EN District of immigration
    TIME            time_of_immigration = { TIME_INFINITE };    //EN Time of immigration
    void            GetImmigrantCharacteristics();              //EN Sample characteristics
    event           timeImmigrationEvent, ImmigrationEvent;     //EN Immigration Event
};

////////////////////////////////////////////////////////////////////////////////////////////////////
// Implementation
////////////////////////////////////////////////////////////////////////////////////////////////////

TIME Person::timeImmigrationEvent() { return time_of_immigration; }
void Person::ImmigrationEvent()
{
    district_int = (DISTRICT_INT)(int)district_immi;
    ever_resident = TRUE;
    time_of_immigration = TIME_INFINITE;
}

////////////////////////////////////////////////////////////////////////////////////////////////////
// Pre-Simulation
////////////////////////////////////////////////////////////////////////////////////////////////////

void PreSimulation()
{
    // Total Immigrant population
    ImmiPopSize = 0.0;
    if (ModelImmigration) // If immigration is switched on
    {
        for (int nSex = 0; nSex < SIZE(SEX); nSex++)
        {
            for (int nYear = 0; nYear < SIZE(SIM_YEAR_RANGE); nYear++)
            {
                ImmiPopSize = ImmiPopSize + NumberImmigrants[nYear][nSex];
                NumberImmigrantsTable[nYear][nSex] = NumberImmigrants[nYear][nSex];;
            }
        }
    }
};

5.7.3. Changes in the Simulation() function in model_core.mpp

The immigrant population is created in the Start() function after the starting file population is created and weights are calculated.

    // Create the immigrant population
    if (ModelImmigration)
    {
        long nImmigrants = int( ImmiPopSize / asGlobals->Item(0)->person_weight);
        for (long nI = 0; nI < nImmigrants; nI++)
        {
            auto paPerson = new Person();
            paPerson->Start(NULL, NULL);
        }
    }

5.7.4. Changes in the Start() function in PersonCore.mpp

The states of the immigrant actors have to be initialized in the Start() function. Most characteristics are sampled from the parameter tables.

    else // Person is an immigrant
    {
        // (A) States corresponding to Starting population file variables
        int nSex, nYear, nAge, nDistrict;
        Lookup_NumberImmigrantsTable(RandUniform(7), &nYear, &nSex);
        Lookup_AgeImmigrants(RandUniform(8), nSex, &nAge);
        Lookup_DestinationImmigrants(RandUniform(9), nSex, SPLIT(nAge, AGE5_PART), &nDistrict);

        sex                 = (SEX)nSex;
        time_of_immigration = MIN(SIM_YEAR_RANGE) + nYear + RandUniform(12);
        family_role         = FR_HEAD;
        district_int        = DISTI_ABROAD;
        district_immi       = (DISTRICT_NAT)nDistrict;
        time                = time_of_immigration - (nAge + RandUniform(11));

        // (B) Other states
        time_of_birth       = time;
        calendar_year       = (int)time;
        ever_resident       = FALSE;
    }