emod-api 3.0.2__py3-none-any.whl

emod_api/demographics/demographics_overlay.py

@@ -0,0 +1,41 @@
+import json
+
+from emod_api.demographics.demographics_base import DemographicsBase
+from emod_api.demographics.overlay_node import OverlayNode
+
+
+class DemographicsOverlay(DemographicsBase):
+    """
+    This class inherits from :py:obj:`emod_api:emod_api.demographics.DemographicsBase` so all functions that can be used
+    to create demographics can also be used to create an overlay file. The intended use is for a user to pass a
+    self-built default OverlayNode object in to represent the Defaults section in the demographics overlay.
+    """
+
+    def __init__(self,
+                 default_node: OverlayNode,
+                 nodes: list[OverlayNode] = None,
+                 idref: str = None):
+        """
+        An object representation of an EMOD demographics overlay input (file). The contents are interpreted by EMOD
+        at runtime as overrides to the canonical/primary demographics input file.
+
+        Args:
+            default_node: (OverlayNode) Contains default settings for nodes in the overlay.
+            nodes (List[OverlayNode]): Overlay is applied to these nodes. Default is no nodes.
+            idref (str): a name used to indicate files (demographics, climate, and migration) are used together
+        """
+        nodes = [] if nodes is None else nodes
+        super().__init__(nodes=nodes, idref=idref, default_node=default_node)
+
+    def to_file(self, file_name: str = "demographics_overlay.json") -> None:
+        """
+        Writes the DemographicsOverlay to an EMOD-compatible json file.
+
+        Args:
+            file_name (str): The filepath to write to.
+
+        Returns:
+            Nothing
+        """
+        with open(file_name, "w") as demo_override_f:
+            json.dump(self.to_dict(), demo_override_f)

emod_api/demographics/fertility_distribution.py

@@ -0,0 +1,235 @@
+import emod_api.demographics.demographic_exceptions as demog_ex
+
+from emod_api.demographics.updateable import Updateable
+from emod_api.utils import check_dimensionality
+
+
+class FertilityDistribution(Updateable):
+    def __init__(self,
+                 ages_years: list[float],
+                 calendar_years: list[float],
+                 pregnancy_rate_matrix: list[list[float]]):
+        """
+        A pregancies/births distribution in units of "annual birth rate per 1000 women". For alternative representations
+        of fertlity/birth in EMOD, see config parameter Birth_Rate_Dependence for more details.
+
+        The FertilityDistribution is used to determine the rate of pregnancies that a "possible mother" will have based
+        on the individual's age and the calendar year. A woman is a possible mother if her age is between (14.0, 45.0)
+        non-inclusive and is not already pregnant. Once a woman becomes pregnant, she will be pregnant for 40 weeks and
+        then give birth.
+
+        EMOD uses double linear interpolation (bilinear) of a 'possible mothers' age and the current calendar year to
+        determine her probability of becoming pregnant. At every time step, 'possible mothers' are identified and are
+        then probabilistically checked to determine if they become pregnant.
+        - See https://www.wikihow.com/Do-a-Double-Linear-Interpolation
+
+        Fertility at any age or any year that preceeds or exceeds the supplied data will be equal to the value at
+        the nearest age and/or timepoint of supplied data.
+
+        In order to model the transfer of immunity or infection from mother to child, one must model pregnancies.
+
+        NOTE: In the limit of low birth rate, the probability of becoming pregnant is equivalent to the birth rate.
+        However, at higher birth rates, some fraction of possible mothers will already be pregnant.
+        Roughly speaking, if we want women to give birth every other year, and they gestate for one year,
+        then the expected time between pregnancy has to be one year, not two.
+        Hence, the maximum possible birth rate is 1 child per woman per gestation period.
+
+        To determine if a woman becomes pregnant, the following logic is used:
+
+            birthrate = FertilityDistribution.draw_value( age, calendar_year )
+            birthrate = birthrate / (1.0 - birthrate * DAYSPERWEEK(7) * WEEKS_FOR_GESTATION(40))
+            birth_probability = birthrate * dt * x_Birth
+            is_pregnant = uniform_random_number < birth_probability
+
+        Args:
+            ages_years (list[float]): A list of ages (in years) that fertility data will be provided for. Must be a
+                list of monotonically increasing floats. Regardless of the provided ages and data, women in EMOD can
+                only be possible mothers if their age is between (14.0, 45.0) non-inclusive.
+
+            calendar_years (list[float]): A list of times (in calendar years) that fertility data will be
+                provided for. Must be a list of monotonically increasing floats within range 1900 <= year <= 2200 .
+
+            pregnancy_rate_matrix (list[list[float]]): A 2-d grid of fertility rates in units of
+                "annual birth rate per 1000 women". The first data dimension (index) is by age, the second data
+                dimension is by calendar year. For M ages (in years) and N calendars years, the dimensionality of this
+                matrix must be MxN .
+
+        Example:
+            ages_years: [15.0, 24.999, 25.0, 34.999, 35.0, 44.999, 45.0, 125.0]     # M ages
+            calendar_years: [2010.0, 2014.999, 2015.0, 2019.999, 2020.0, 2024.999]  # N times
+            pregnancy_rate_matrix: dimensionality MxN, units: fertility/year/1000 women
+                [[103.3, 103.3, 77.5, 77.5, 65.5, 65.5],     # fertility rates at age 15.0, the six timepoints above
+                 [103.3, 103.3, 77.5, 77.5, 65.5, 65.5],     # fertility rates at age 24.999
+                 [265.0, 265.0, 278.7, 278.7, 275.4, 275.4], # fertility rates at age 25.0
+                 [265.0, 265.0, 278.7, 278.7, 275.4, 275.4], # fertility rates at age 34.999
+                 [152.4, 152.4, 129.2, 129.2, 115.9, 115.9], # fertility rates at age 35.0
+                 [152.4, 152.4, 129.2, 129.2, 115.9, 115.9], # fertility rates at age 44.999
+                 [19.9, 19.9, 14.6, 14.6, 12.1, 12.1],       # fertility rates at age 45.0
+                 [19.9, 19.9, 14.6, 14.6, 12.1, 12.1]]       # fertility rates at age 125.0
+
+            A 30 year-old woman who is not pregnant at time/year 2022.5 bilinearly interpolated (shown in steps):
+                275.4 + (2022.5-2020.0) * ((275.4-275.4) / (2024.999-2020.0)) = 275.4 (age 25.0 fertility at 2022.5)
+                275.4 + (2022.5-2020.0) * ((275.4-275.4) / (2024.999-2020.0)) = 275.4 (age 34.99 fertility at 2022.5)
+                275.4 + (30-25.0) * ((275.4-275.4) / (34.999-25)) = 275.4 (age 30 fertility at 2022.5)
+                scale result to fertility/woman/day: 275.4 / (365 * 1000) = 0.0007545 (birth probability)
+        """
+        super().__init__()
+        self.ages_years = ages_years
+        self.calendar_years = calendar_years
+        self.pregnancy_rate_matrix = pregnancy_rate_matrix
+
+        # This will convert the object to a fertility dictionary and then validate it reporting object-relevant messages
+        self._validate(distribution_dict=self.to_dict(validate=False), source_is_dict=False)
+
+    @property
+    def _population_groups(self):
+        return [self.ages_years, self.calendar_years]
+
+    @classmethod
+    def _rate_scale_factor(cls):
+        return 1 / 365.0 / 1000  # convert from per-year, per 1000 women to per/woman/day
+
+    @classmethod
+    def _rate_scale_units(cls):
+        return "annual birth rate per 1000 women"
+
+    @classmethod
+    def _axis_names(cls):
+        return ['age', 'year']
+
+    @classmethod
+    def _axis_scale_factors(cls):
+        return [365.0, 1]
+
+    def to_dict(self, validate: bool = True) -> dict:
+        distribution_dict = {
+            'AxisNames': self._axis_names(),
+            'AxisScaleFactors': self._axis_scale_factors(),
+            'PopulationGroups': self._population_groups,
+            'ResultScaleFactor': self._rate_scale_factor(),
+            'ResultUnits': self._rate_scale_units(),
+            'ResultValues': self.pregnancy_rate_matrix
+        }
+        if validate:
+            self._validate(distribution_dict=distribution_dict, source_is_dict=False)
+        return distribution_dict
+
+    @classmethod
+    def from_dict(cls, distribution_dict: dict):
+        cls._validate(distribution_dict=distribution_dict, source_is_dict=True)
+        return cls(ages_years=distribution_dict['PopulationGroups'][0],
+                   calendar_years=distribution_dict['PopulationGroups'][1],
+                   pregnancy_rate_matrix=distribution_dict['ResultValues'])
+
+    # True means message relevant to verifying a fertility dictionary, False means messages relevant to verifying an obj
+    _validation_messages = {
+        'fixed_value_check': {
+            True: "key: {0} value: {1} does not match expected value: {2}",
+            False: None  # These are all properties of the obj and cannot be made invalid
+        },
+        'population_group_length_check': {
+            True: "PopulationGroups expected to be a 2-d array of floats. The first dimension length must be two, but "
+                  "is length {0}",
+            False: None  # This is a property of the obj and cannot be made invalid
+        },
+        'data_dimensionality_check': {
+            True: "ResultValues is expected to be a 2-d matrix of data but it is not.",
+            False: "pregnancy_rate_matrix has an improper dimensionality. It must be a 2-d matrix."
+        },
+        'data_dimensionality_check_dim0': {
+            True: "ResultValues first dimension length {0} does not match the PopulationGroups[0] age bin count {1}",
+            False: "pregnancy_rate_matrix first dimension length: {0} does not match the ages_years length: {1}"
+        },
+        'data_dimensionality_check_dim1': {
+            True: "ResultValues second dimension length {0} does not match the PopulationGroups[1] time bin count: {1}",
+            False: "pregnancy_rate_matrix second dimension length: {0} does not match the calendar_years length: {1}"
+        },
+        'age_range_check': {
+            True: "PopulationGroups[0] age values must be: 0 <= age <= 200 in years. Out-of-range index:values : {0}",
+            False: "All ages_years values must be: 0 <= age <= 200 in years. Out-of-range index:values : {0}"
+        },
+        'time_range_check': {
+            True: "PopulationGroups[1] time values must be: 1900 <= time <= 2200 calendar year",
+            False: "All calendar_years values must be: 1900 <= time <= 2200 calendar year"
+        },
+        'age_monotonicity_check': {
+            True: "PopulationGroups[0] ages in years must monotonically increase but do not, index: {0} value: {1}",
+            False: "ages_years values must monotonically increase but do not, index: {0} value: {1}"
+        },
+        'time_monotonicity_check': {
+            True: "PopulationGroups[1] times in calendar years must monotonically increase but do not, index: {0} value: {1}",
+            False: "calendar_years values must monotonically increase but do not, index: {0} value: {1}"
+        }
+    }
+
+    @classmethod
+    def _validate(cls, distribution_dict: dict, source_is_dict: bool):
+        """
+        Validate a FertilityDistribution in dict form
+
+        Args:
+            distribution_dict: (dict) the fertility dict to validate
+            source_is_dict: (bool) If true, report dict-relevant error messages. If false, report obj-relevant messages.
+
+        Returns:
+            Nothing
+        """
+        if source_is_dict is True:
+            expected_values = {
+                'AxisNames': cls._axis_names(),
+                'AxisScaleFactors': cls._axis_scale_factors(),
+                'ResultScaleFactor': cls._rate_scale_factor(),
+                'ResultUnits': cls._rate_scale_units()
+            }
+            for key, expected_value in expected_values.items():
+                value = distribution_dict[key]
+                if value != expected_value:
+                    message = cls._validation_messages['fixed_value_check'][source_is_dict].format(key, value, expected_value)
+                    raise demog_ex.InvalidFixedValueException(message)
+
+        # ensure the data table is MxN for the population groups == [M, N]
+        population_groups = distribution_dict['PopulationGroups']
+        data_table = distribution_dict['ResultValues']
+        if source_is_dict is True:
+            if len(population_groups) != 2:
+                message = cls._validation_messages['population_group_length_check'][source_is_dict].format(len(population_groups))
+                raise demog_ex.InvalidPopulationGroupLengthException(message)
+
+        # ensure the data table has the correct dimensionality. It must be 2-d.
+        is_2d = check_dimensionality(data=data_table, dimensionality=2)
+        if not is_2d:
+            message = cls._validation_messages['data_dimensionality_check'][source_is_dict]
+            raise demog_ex.InvalidDataDimensionality(message)
+
+        # continue checking dimension lengths
+        ages = population_groups[0]
+        times = population_groups[1]
+        n_ages = len(ages)
+        n_times = len(times)
+        if len(data_table) != n_ages:
+            message = cls._validation_messages['data_dimensionality_check_dim0'][source_is_dict].format(len(data_table), n_ages)
+            raise demog_ex.InvalidDataDimensionDim0Exception(message)
+        for i in range(len(data_table)):
+            if len(data_table[i]) != n_times:
+                message = cls._validation_messages['data_dimensionality_check_dim1'][source_is_dict].format(len(data_table[i]), n_times)
+                raise demog_ex.InvalidDataDimensionDim1Exception(message)
+
+        # ensure the age and time lists are ascending and in reasonable ranges
+        out_of_range = [f"{index}:{age}" for index, age in enumerate(ages) if (age < 0) or (age > 200)]
+        if len(out_of_range) > 0:
+            oor_str = ', '.join(out_of_range)
+            message = cls._validation_messages['age_range_check'][source_is_dict].format(oor_str)
+            raise demog_ex.AgeOutOfRangeException(message)
+
+        if any([(time < 1900) or (time > 2200) for time in times]):
+            message = cls._validation_messages['time_range_check'][source_is_dict]
+            raise demog_ex.TimeOutOfRangeException(message)
+
+        for i in range(1, len(ages)):
+            if ages[i] - ages[i - 1] <= 0:
+                message = cls._validation_messages['age_monotonicity_check'][source_is_dict].format(i, ages[i])
+                raise demog_ex.NonMonotonicAgeException(message)
+        for i in range(1, len(times)):
+            if times[i] - times[i - 1] <= 0:
+                message = cls._validation_messages['time_monotonicity_check'][source_is_dict].format(i, times[i])
+                raise demog_ex.NonMonotonicTimeException(message)

emod_api/demographics/implicit_functions.py

@@ -0,0 +1,112 @@
+# Migration
+
+def _set_migration_model_fixed_rate(config):
+    config.parameters.Migration_Model = "FIXED_RATE_MIGRATION"
+    return config
+
+
+def _set_enable_migration_model_heterogeneity(config):
+    config.parameters.Enable_Migration_Heterogeneity = 1
+    return config
+
+
+def _set_migration_pattern_srt(config):
+    config.parameters.Migration_Pattern = "SINGLE_ROUND_TRIPS"
+    return config
+
+
+def _set_migration_pattern_rwd(config):
+    config.parameters.Migration_Pattern = "RANDOM_WALK_DIFFUSION"
+    return config
+
+
+def _set_regional_migration_filenames(config, file_name):
+    config.parameters.Regional_Migration_Filename = file_name
+    return config
+
+
+def _set_local_migration_filename(config, file_name):
+    config.parameters.Local_Migration_Filename = file_name
+    return config
+
+
+def _set_demographic_filenames(config, filenames):
+    config.parameters.Demographics_Filenames = filenames
+    return config
+
+
+def _set_local_migration_roundtrip_probability(config, probability_of_return):
+    config.parameters.Local_Migration_Roundtrip_Probability = probability_of_return
+    return config
+
+
+def _set_regional_migration_roundtrip_probability(config, probability_of_return):
+    config.parameters.Regional_Migration_Roundtrip_Probability = probability_of_return
+    return config
+
+
+# Susceptibility
+
+def _set_suscept_complex(config):
+    config.parameters.Susceptibility_Initialization_Distribution_Type = "DISTRIBUTION_COMPLEX"
+    return config
+
+
+def _set_suscept_simple(config):
+    config.parameters.Susceptibility_Initialization_Distribution_Type = "DISTRIBUTION_SIMPLE"
+    return config
+
+
+# Age Structure
+
+def _set_age_simple(config):
+    config.parameters.Age_Initialization_Distribution_Type = "DISTRIBUTION_SIMPLE"
+    return config
+
+
+def _set_age_complex(config):
+    config.parameters.Age_Initialization_Distribution_Type = "DISTRIBUTION_COMPLEX"
+    return config
+
+
+# Initial Prevalence
+
+def _set_init_prev(config):
+    config.parameters.Enable_Initial_Prevalence = 1
+    return config
+
+
+# Mortality
+
+def _set_enable_natural_mortality(config):
+    config.parameters.Enable_Natural_Mortality = 1
+    return config
+
+
+def _set_mortality_age_gender(config):
+    config.parameters.Death_Rate_Dependence = "NONDISEASE_MORTALITY_BY_AGE_AND_GENDER"
+    return config
+
+
+def _set_mortality_age_gender_year(config):
+    config.parameters.Death_Rate_Dependence = "NONDISEASE_MORTALITY_BY_YEAR_AND_AGE_FOR_EACH_GENDER"
+    return config
+
+
+# Fertility
+
+def _set_fertility_age_year(config):
+    config.parameters.Birth_Rate_Dependence = "INDIVIDUAL_PREGNANCIES_BY_AGE_AND_YEAR"
+    return config
+
+
+def _set_population_dependent_birth_rate(config):
+    config.parameters.Birth_Rate_Dependence = "POPULATION_DEP_RATE"
+    return config
+
+
+# Risk
+
+def _set_enable_demog_risk(config):
+    config.parameters.Enable_Demographics_Risk = 1
+    return config

emod_api/demographics/mortality_distribution.py

@@ -0,0 +1,227 @@
+from typing import Union
+
+import emod_api.demographics.demographic_exceptions as demog_ex
+from emod_api.demographics.updateable import Updateable
+from emod_api.utils import check_dimensionality
+
+
+class MortalityDistribution(Updateable):
+    def __init__(self,
+                 ages_years: list[float],
+                 mortality_rate_matrix: Union[list[list[float]], list[float]],
+                 calendar_years: list[float] = None):
+        """
+        A natural mortality distribution for one gender in units of "annual death rate for an individual". If the
+        distribution is time-dependent, pass in a list of times (calendar_years).
+
+        The MortalityDistribution provides a rate (probability) at which each agent will die naturally on any given
+        model day given their current age. EMOD uses double linear interpolation (bilinear) of an agent's age and the
+        current calendar year to determine the exact probability of their death.
+        - See https://www.wikihow.com/Do-a-Double-Linear-Interpolation
+
+        Mortality at any age or any year that preceeds or exceeds the supplied data will be equal to the value at
+        the nearest age and/or timepoint of supplied data.
+
+        Args:
+            ages_years: (list[float]) A list of ages (in years) that mortality data will be provided for. Must be a
+                list of monotonically increasing floats within range 0 <= age <= 200 .
+            mortality_rate_matrix: (list[list[float]] or list[float]) A 2-d grid of mortality rates in units of
+                "annual death rate for an individual". The first data dimension (index) is by age, the second data
+                dimension is by calendar year. For M ages (in years) and N calendars years, the dimensionality of this
+                matrix must be MxN . Alternately, a 1-d array of mortality rates may be given and will be interpreted
+                as a time-independent "for all time" distribution. This option is only available if the calendar_years
+                argument is not used.
+            calendar_years: (list[float]) (optional) A list of times (in calendar years) that mortality data will be
+                provided for. Must be a list of monotonically increasing floats within range 1900 <= year <= 2200 .
+                If not provided, a default single calendar year (1900) will be used that effectively means
+                "for all time".
+
+        Example:
+            ages_years: [0, 10, 20, 50, 100]   # M ages
+            calendar_years: [1950, 1970, 1990] # N times. If not supplied, one time "forever" is used and N below is 1.
+            mortality_rate_matrix: dimensionality: MxN
+                [[0.2,  0.15, 0.1 ],  # These are mortality rates at age 0, the three time points above
+                 [0.12, 0.08, 0.06],  # These are mortality rates at age 10
+                 [0.05, 0.03, 0.01],  # These are mortality rates at age 20
+                 [0.15, 0.1,  0.05],  # These are mortality rates at age 50
+                 [0.3,  0.25, 0.2 ]]  # These are mortality rates at age 100
+
+            Mortality at age 5 at 1960, bilinearly interpolated (shown in steps):
+                0.2 + (1960-1950) * ((0.15-0.2) / (1970-1950)) = 0.175 (age 0 mortality rate at 1960)
+                0.12 + (1960-1950) * ((0.08-0.12) / (1970-1950)) = 0.1 (age 10 mortality rate at 1960)
+                0.175 + (5-0) * ((0.1-0.175) / (10-0)) = 0.1375 (age 5 mortality rate at 1960)
+            Mortality at age 5 at 2100 (beyond supplied times), bilinearly interpolated: (shown in steps)
+                (compute the value at the closest time possible, 1970, then report it for year 2100)
+                0.1 (age 0 mortality rate at 1970 (also 2100))
+                0.06 (age 10 mortality rate at 1970 (also 2100))
+                0.1 + (5-0) * ((0.06-0.1) / (10-0)) = 0.08 (age 5 mortality rate at 1970 (also 2100))
+        """
+        super().__init__()
+        self.ages_years = ages_years
+
+        if calendar_years is None:
+            self.calendar_years = [self._default_calendar_year]
+            # Here we convert a 1-d array of values to a (trivial) 2-d array. Only allowed if time not passed.
+            if check_dimensionality(data=mortality_rate_matrix, dimensionality=1) is True:
+                mortality_rate_matrix = [[item] for item in mortality_rate_matrix]
+        else:
+            self.calendar_years = calendar_years
+        self.mortality_rate_matrix = mortality_rate_matrix
+
+        # This will convert the object to a mortality dictionary and then validate it reporting object-relevant messages
+        self._validate(distribution_dict=self.to_dict(validate=False), source_is_dict=False)
+
+    @property
+    def _population_groups(self):
+        return [self.ages_years, self.calendar_years]
+
+    @classmethod
+    def _rate_scale_factor(cls):
+        return 1 / 365.0  # convert from per-year to per-day
+
+    @classmethod
+    def _rate_scale_units(cls):
+        return "annual death rate for an individual"
+
+    @property
+    def _default_calendar_year(self):
+        return 1900
+
+    @classmethod
+    def _axis_names(cls):
+        return ['age', 'year']
+
+    @classmethod
+    def _axis_scale_factors(cls):
+        return [365.0, 1]
+
+    def to_dict(self, validate: bool = True) -> dict:
+        distribution_dict = {
+            'AxisNames': self._axis_names(),
+            'AxisScaleFactors': self._axis_scale_factors(),
+            'PopulationGroups': self._population_groups,
+            'ResultScaleFactor': self._rate_scale_factor(),
+            'ResultUnits': self._rate_scale_units(),
+            'ResultValues': self.mortality_rate_matrix
+        }
+        if validate:
+            self._validate(distribution_dict=distribution_dict, source_is_dict=False)
+        return distribution_dict
+
+    @classmethod
+    def from_dict(cls, distribution_dict: dict):
+        cls._validate(distribution_dict=distribution_dict, source_is_dict=True)
+        return cls(ages_years=distribution_dict['PopulationGroups'][0],
+                   mortality_rate_matrix=distribution_dict['ResultValues'],
+                   calendar_years=distribution_dict['PopulationGroups'][1])
+
+    # True means message relevant to verifying a mortality dictionary, False means messages relevant to verifying an obj
+    _validation_messages = {
+        'fixed_value_check': {
+            True: "key: {0} value: {1} does not match expected value: {2}",
+            False: None  # These are all properties of the obj and cannot be made invalid
+        },
+        'population_group_length_check': {
+            True: "PopulationGroups expected to be a 2-d array of floats. The first dimension length must be two, but "
+                  "is length {0}",
+            False: None  # This is a property of the obj and cannot be made invalid
+        },
+        'data_dimensionality_check': {
+            True: "ResultValues is expected to be a 2-d matrix of data but it is not.",
+            False: "mortality_rate_matrix has an improper dimensionality. It must be a 2-d matrix if calendar_years is "
+                   "given. If calendar_years is NOT given, it MAY be a 1-d list of values."
+        },
+        'data_dimensionality_check_dim0': {
+            True: "ResultValues first dimension length {0} does not match the PopulationGroups[0] age bin count {1}",
+            False: "mortality_rate_matrix first dimension length: {0} does not match the ages_years length: {1}"
+        },
+        'data_dimensionality_check_dim1': {
+            True: "ResultValues second dimension length {0} does not match the PopulationGroups[1] time bin count: {1}",
+            False: "mortality_rate_matrix second dimension length: {0} does not match the calendar_years length: {1}"
+        },
+        'age_range_check': {
+            True: "PopulationGroups[0] age values must be: 0 <= age <= 200 in years",
+            False: "All ages_years values must be: 0 <= age <= 200 in years"
+        },
+        'time_range_check': {
+            True: "PopulationGroups[1] time values must be: 1900 <= time <= 2200 calendar year",
+            False: "All calendar_years values must be: 1900 <= time <= 2200 calendar year"
+        },
+        'age_monotonicity_check': {
+            True: "PopulationGroups[0] ages in years must monotonically increase but do not, index: {0} value: {1}",
+            False: "ages_years values must monotonically increase but do not, index: {0} value: {1}"
+        },
+        'time_monotonicity_check': {
+            True: "PopulationGroups[1] times in calendar years must monotonically increase but do not, index: {0} value: {1}",
+            False: "calendar_years values must monotonically increase but do not, index: {0} value: {1}"
+        }
+    }
+
+    @classmethod
+    def _validate(cls, distribution_dict: dict, source_is_dict: bool):
+        """
+        Validate a MortalityDistribution in dict form
+
+        Args:
+            distribution_dict: (dict) the mortality dict to validate
+            source_is_dict: (bool) If true, report dict-relevant error messages. If false, report obj-relevant messages.
+
+        Returns:
+            Nothing
+        """
+        if source_is_dict is True:
+            expected_values = {
+                'AxisNames': cls._axis_names(),
+                'AxisScaleFactors': cls._axis_scale_factors(),
+                'ResultScaleFactor': cls._rate_scale_factor(),
+                'ResultUnits': cls._rate_scale_units()
+            }
+            for key, expected_value in expected_values.items():
+                value = distribution_dict[key]
+                if value != expected_value:
+                    message = cls._validation_messages['fixed_value_check'][source_is_dict].format(key, value, expected_value)
+                    raise demog_ex.InvalidFixedValueException(message)
+
+        # ensure the data table is MxN for the population groups == [M, N]
+        population_groups = distribution_dict['PopulationGroups']
+        data_table = distribution_dict['ResultValues']
+        if source_is_dict is True:
+            if len(population_groups) != 2:
+                message = cls._validation_messages['population_group_length_check'][source_is_dict].format(len(population_groups))
+                raise demog_ex.InvalidPopulationGroupLengthException(message)
+
+        # ensure the data table has the correct dimensionality. It must be 2-d.
+        is_2d = check_dimensionality(data=data_table, dimensionality=2)
+        if not is_2d:
+            message = cls._validation_messages['data_dimensionality_check'][source_is_dict]
+            raise demog_ex.InvalidDataDimensionality(message)
+
+        # continue checking dimension lengths
+        ages = population_groups[0]
+        times = population_groups[1]
+        n_ages = len(ages)
+        n_times = len(times)
+        if len(data_table) != n_ages:
+            message = cls._validation_messages['data_dimensionality_check_dim0'][source_is_dict].format(len(data_table), n_ages)
+            raise demog_ex.InvalidDataDimensionDim0Exception(message)
+        for i in range(len(data_table)):
+            if len(data_table[i]) != n_times:
+                message = cls._validation_messages['data_dimensionality_check_dim1'][source_is_dict].format(len(data_table[i]), n_times)
+                raise demog_ex.InvalidDataDimensionDim1Exception(message)
+
+        # ensure the age and time lists are ascending and in reasonable ranges
+        if any([(age < 0) or (age > 200) for age in ages]):
+            message = cls._validation_messages['age_range_check'][source_is_dict]
+            raise demog_ex.AgeOutOfRangeException(message)
+        if any([(time < 1900) or (time > 2200) for time in times]):
+            message = cls._validation_messages['time_range_check'][source_is_dict]
+            raise demog_ex.TimeOutOfRangeException(message)
+
+        for i in range(1, len(ages)):
+            if ages[i] - ages[i - 1] <= 0:
+                message = cls._validation_messages['age_monotonicity_check'][source_is_dict].format(i, ages[i])
+                raise demog_ex.NonMonotonicAgeException(message)
+        for i in range(1, len(times)):
+            if times[i] - times[i - 1] <= 0:
+                message = cls._validation_messages['time_monotonicity_check'][source_is_dict].format(i, times[i])
+                raise demog_ex.NonMonotonicTimeException(message)