Screened Tables - openmpp/openmpp.github.io GitHub Wiki

double TransformScreened1(
    const double in_value,
...
)
{
    /// transformed value, initialized to quiet NaN (shows as empty)
    double out_value = UNDEF_VALUE;

    // notional example of transformation (round to 100's)
    out_value = 100.0 * std::round(in_value / 100.0);

    return out_value;
}

options screened1_extremas_size = 3;

/**
 * Table screening transformation function #1
 *
 * @param   in_value     The table value subject to transformation.
 * @param   description  A formatted string describing the table and statistic.
 * @param   statistic    The statistic of the accumulator, e.g. sum, mean.
 * @param   increment    The increment of the accumulator, e.g. delta, value_out.
 * @param   table        The table of the accumulator (model-specific).
 * @param   attribute    The attribute of the accumulator (model-specific).
 * @param   observations The count of observations in the cell (# of increments).
 * @param   extrema_size The maximum size M of the two extrema collections (configurable)
 * @param   smallest     The extrema collection containing the smallest M observations.
 * @param   largest      The extrema collection containing the largest M observations.
 *
 * @returns The transformed version of in_value.
 */
double TransformScreened1(
    const double in_value,
    const char* description,
    const omr::stat statistic,
    const omr::incr increment,
    const omr::etbl table,
    const omr::attr attribute,
    const double observations,
    const size_t extrema_size,
    const std::multiset<double>& smallest,
    const std::multiset<double>& largest
)

namespace omr {
    /// statistic in an entity table
    enum class stat {
        unit,
        sum,
        minimum,
        maximum,
        mean,
        variance,
        stdev,
        P1,
        P2,
        P5,
        P10,
        P20,
        P25,
        P30,
        P40,
        P50,
        P60,
        P70,
        P75,
        P80,
        P90,
        P95,
        P98,
        P99,
        gini,
    };
} // namespace omr

namespace omr {
    /// increment in an entity table
    enum class incr {
        unused,
        delta,
        delta2,
        nz_delta,
        value_in,
        value_in2,
        nz_value_in,
        value_out,
        value_out2,
        nz_value_out,
    };
} // namespace omr

namespace omr {
    /// entity table in model
    enum class etbl {
        ExampleTable,
        om_none
    };
} // namespace omr

namespace omr {
    /// visible entity attribute in model
    enum class attr {
        age,
        alive,
        all_earnings,
        benefit,
        case_id,
        case_seed,
        earnings,
        entity_id,
        integer_age,
        lifecycle_counter,
        lifecycle_event,
        positive_earnings,
        region,
        se_earnings,
        time,
        under_audit,
        om_none
    };
} // namespace omr

table snapshot screened1 Person ExampleTable
[trigger_entrances(integer_age, 50)]
{
    {
        unit,                   //EN Persons
        nz_value_out(earnings), //EN Persons with earnings
        mean(earnings),         //EN Average earnings
        sum(earnings),          //EN Total earnings
        P50(earnings),          //EN Median earnings
        maximum(earnings),      //EN Maximum earnings
        gini(earnings)          //EN gini of earnings
    }
};

{
    /// transformed value, initialized to quiet NaN (shows as empty)
    double out_value = UNDEF_VALUE;

    /// the increment is from the count-like nz family
    bool is_nz = 
           (increment == omr::incr::nz_delta)
        || (increment == omr::incr::nz_value_in)
        || (increment == omr::incr::nz_value_out);

    if (statistic == omr::stat::gini) {
        // gini coefficient
        // do not modify
        out_value = in_value;
    }
    else if ((statistic == omr::stat::unit) || is_nz) {
        // count-like value
        // round to 100's
        out_value = 100.0 * std::round(in_value / 100.0);
    }
    else if (statistic == omr::stat::mean) {
        // average-like value
        // round to 1000's
        out_value = 1000.0 * std::round(in_value / 1000.0);
    }
    else if (statistic == omr::stat::sum) {
        // total-like value
        // round to 1000000's
        out_value = 1000000.0 * std::round(in_value / 1000000.0);
    }
    else {
        // suppress other things
        out_value = UNDEF_VALUE;
    }

    return out_value;
}

table snapshot screened1 Person StatsAt50
[trigger_entrances(integer_age, 50)]
{
    {
        unit,                   //EN Persons
        nz_value_out(earnings), //EN Persons with earnings
        mean(earnings),         //EN Average earnings
        sum(earnings),          //EN Total earnings
        P50(earnings),          //EN Median earnings
        maximum(earnings),      //EN Maximum earnings
        gini(earnings)          //EN gini of earnings
    }
};

{
    // pass through non-finite values and 0.0
    if (!std::isfinite(in_value) || in_value == 0.0) {
        return in_value;
    }

    /// transformed value, initialized to quiet NaN (shows as empty)
    double out_value = UNDEF_VALUE;

    // number of significant digits to retain
    const static double precision = 3; 

    double d = std::ceil(std::log10(std::abs(in_value)));
    /// power of 10 for scaling
    double power = precision - std::trunc(d);
    /// scaling needed before rounding
    double magnitude = std::pow(10.0, power);

    out_value = std::round(in_value * magnitude) / magnitude;

    return out_value;
}

table snapshot screened1 Person ExampleTable //EN High earners by region
[trigger_entrances(integer_age, 50)]
{
    region+
    * {
        high_earner //EN High earners
    }
};

{
    /// transformed value, initialized to quiet NaN (shows as empty)
    double out_value = UNDEF_VALUE;

    if (observations < 100) {
        // suppress if fewer than 100 observations
        out_value = UNDEF_VALUE;
    }
    else {
        // round to 5's
        out_value = 5.0 * std::round(in_value / 5.0);
    }

    return out_value;
}

table snapshot screened1 Person ExampleTable //EN Average earnings of high earners
[trigger_entrances(integer_age, 50) && high_earner]
{
    region+
    * {
        mean(earnings) //EN Earnings
    }
};

{
    /// transformed value, initialized to quiet NaN (shows as empty)
    double out_value = UNDEF_VALUE;

    switch (table) {
    case omr::etbl::ExampleTable:
    {
        assert(extrema_size == 3); // code below requires that extrema size is 3

        assert(statistic == omr::stat::mean);     // sanity check
        assert(attribute == omr::attr::earnings); // sanity check

        double sum_top3 = 0.0;
        for (auto& val : largest) {
            sum_top3 += val;
        }
        double sum_all = in_value * observations;

        if ((sum_top3 / sum_all) >= 0.60) {
            // suppress if top 3 earners account for 60% or more of earnings in cell
            out_value = UNDEF_VALUE;
        }
        else {
            // round value to 1000's
            out_value = 1000.0 * std::round(in_value / 1000.0);
        }
        break;
    }
    default:
    {
        // code to handle other screened tables would go here
        break;
    }
    } // switch
    return out_value;
}

/* NOTE(Income.mpp, EN)
    This module contains hard-coded notional income dynamics for testing screened tables.
*/

#include "omc/optional_IDE_helper.h" // help an IDE editor recognize model symbols

#if 0 // Hide non-C++ syntactic island from IDE

range REGION //EN Region
{
    0,
    4
};

parameters
{
    double EarningsNonZeroProportion;
    double EarningsScaleFactor;
    double EarningsSigma;
    double SE_EarningsNonZeroProportion;
    double SE_EarningsScaleFactor;
    double SE_EarningsSigma;
    double HighIncomeThreshold;
    double GuaranteedAnnualIncome;
    double AuditThreshold;
    cumrate RegionDistribution[REGION];
};

entity Person
{
    //EN Earnings
    double earnings = { 0.0 };

    //EN Self-employed earnings
    double se_earnings = { 0.0 };

    //EN All earnings
    double all_earnings = earnings + se_earnings;

    //EN Positive earnings
    double positive_earnings = max(0.0, all_earnings);

    //EN Benefit
    double benefit = max(GuaranteedAnnualIncome, GuaranteedAnnualIncome - positive_earnings);

    //EN High earner
    bool high_earner = (all_earnings >= HighIncomeThreshold);

    //EN Under audit
    bool under_audit = (all_earnings >= AuditThreshold) || (positive_earnings != all_earnings);

    //EN Region
    REGION region;

    //EN Notional model of earnings
    void AssignEarnings(void);

    //EN Assign region
    void AssignRegion(void);

    // call EarningsGrowth at each change in integer_age
    hook AssignEarnings, trigger_changes(integer_age);

    // call AssignRegion at Start
    hook AssignRegion, Start, 1;
};

#endif // Hide non-C++ syntactic island from IDE

void Person::AssignEarnings(void)
{
    if (integer_age == 20) {
        // Assign starting earnings at age 20
        if (RandUniform(10) < EarningsNonZeroProportion) {
            double z = RandNormal(11);
            double x = EarningsScaleFactor * std::exp(EarningsSigma * z);
            earnings = std::round(x);
        }
        // else earnings have default value of 0

        // Assign starting se_earnings at age 20
        if (RandUniform(12) < SE_EarningsNonZeroProportion) {
            // 80% have self-employed earnings
            double z = RandNormal(13);
            double x = SE_EarningsScaleFactor * std::exp(SE_EarningsSigma * z);
            se_earnings = std::round(x);
        }
    }
    else if (integer_age > 20) {
        // Annual change to earnings
        {
            double u = RandUniform(14);
            // rescale uniform to to [0.9, 1.1]
            u = 0.9 + 0.2 * u;
            double x = earnings * u;
            x *= 1.03; // career growth with increasing age
            earnings = std::round(x);
        }
        // Annual change to se_earnings
        {
            double u = RandUniform(15);
            // rescale uniform to [0.9, 1.1]
            u = 0.9 + 0.2 * u;
            double x = se_earnings * u;
            x *= 1.03; // career growth with increasing age
            se_earnings = std::round(x);
        }
    }
    else {
        // No earnings before age 20
    }
}

void Person::AssignRegion(void)
{
    double draw = RandUniform(3);
    int nRegion = 0;
    Lookup_RegionDistribution(draw, &nRegion);
    region = (REGION)nRegion;
}

parameters
{
    double EarningsNonZeroProportion     = 0.80;
    double EarningsScaleFactor           = 50000.0;
    double EarningsSigma                 = 0.25;
    double SE_EarningsNonZeroProportion  = 0.80;
    double SE_EarningsScaleFactor        = 40000.0;
    double SE_EarningsSigma              = 0.25;
    double HighIncomeThreshold           = 250000.00;
    double GuaranteedAnnualIncome        = 20000.00;
    double AuditThreshold                = 250000.00;
    cumrate RegionDistribution[REGION] =
    {
        200, 100, 50, 10, 10
    };
};