emod-api 3.0.2__py3-none-any.whl

emod_api/config/default_from_schema_no_validation.py

@@ -0,0 +1,177 @@
+#!/usr/bin/python
+
+import json
+import os
+from typing import Union
+import warnings
+import emod_api.schema_to_class as s2c
+
+
+def _set_defaults_for_schema_group(dc_param,
+                                   schema_section,
+                                   schema):
+    """
+    By making this part of write_default_from_schema its own function, it becomes reusable for the purposes
+    of Malaria_Drug_params which is a pretty funky part of the schema honestly.
+    """
+    for param in schema_section:
+        if param == "class":
+            continue
+        if 'default' in schema_section[param]:
+            value = schema_section[param]['default']
+            dc_param[param] = value
+            dc_param["schema"][param] = schema_section[param]
+        # Our vectors don't seem to have defaults but we think an empty array is a valid default based on type alone?
+        elif "type" in schema_section[param] and "Vector" in schema_section[param]["type"]:
+            dc_param[param] = list()
+            dc_param["schema"][param] = schema_section[param]
+        else:
+            dc_param[param] = {}  # hack for Drug Params.... and for the nested ones.
+            keys = [x for x in schema_section[param].keys()]
+            # This is all too "special-casey"
+            if len(keys) == 1:
+                key = keys[0]  # HACK
+                dc_param["schema"][param] = schema_section[param][key]
+            else:
+                # e.g., Fractional_Dose_xxx map which has comlex type
+                # Want to call this but we need the full json so we can access the idmType section
+                #  print( "Don't actually want to do this but just testing the concept." )
+                dc_param[param] = s2c.get_class_with_defaults(schema_section[param]["type"], schema_json=schema)
+                dc_param["schema"][param] = schema_section[param]
+
+
+def get_default_config_from_schema(path_to_schema,
+                                   schema_node=True,
+                                   as_rod=False,
+                                   output_filename=None):
+    """
+    This returns a default config object as defined from reading a schema file.
+
+    Parameters:
+        output_filename (str): if not None, the path to write the loaded config to
+    """
+    default_config = {"parameters": dict()}
+    dc_param = default_config["parameters"]
+    dc_param["schema"] = dict()
+
+    with open(path_to_schema) as fid01:
+        schema = json.load(fid01)
+
+    for group in schema["config"]:
+        _set_defaults_for_schema_group(dc_param, schema["config"][group], schema)
+
+    if not schema_node:
+        print("Removing schema node.")
+        dc_param.pop("schema")
+
+    if as_rod:
+        default_config = json.loads(json.dumps(default_config), object_hook=s2c.ReadOnlyDict)
+
+    if output_filename is not None:
+        with open(output_filename, "w") as outfile:
+            json.dump(default_config, outfile, sort_keys=True, indent=4)
+        print(f"Wrote '{output_filename}' file.")
+
+    return default_config
+
+
+def write_default_from_schema(path_to_schema,
+                              output_filename='default_config.json',
+                              schema_node=True):
+    """
+    DEPRECATED: This function simply calls get_default_config_from_schema with specific arguments.
+
+    This function writes out a default config file as defined from reading a schema file.
+    It's as good as the schema it's given. Note that this is designed to work with a schema from
+    a disease-specific build, otherwise it may contain a lot of params from other disease types.
+    """
+    warnings.warn("Calls to write_default_from_schema() should be updated to use get_default_config_from_schema()",
+                  DeprecationWarning)
+    get_default_config_from_schema(path_to_schema=path_to_schema, output_filename=output_filename,
+                                   schema_node=schema_node)
+    return output_filename
+
+
+def load_default_config_as_rod(config) -> s2c.ReadOnlyDict:
+    """
+    Parameters:
+        config (string/path): path to default or base config.json
+
+    Returns:
+        config (as ReadOnlyDict) with schema ready for schema-verified param sets.
+    """
+    if not os.path.exists(config):
+        print(f"{config} not found.")
+        return None
+    config_rod = None
+    with open(config) as conf:
+        config_rod = json.load(conf, object_hook=s2c.ReadOnlyDict)
+    return config_rod
+
+
+def get_config_from_default_and_params(config_path: Union[str, os.PathLike, None] = None,
+                                       set_fn=None,
+                                       config: s2c.ReadOnlyDict = None,
+                                       verbose: bool = False) -> s2c.ReadOnlyDict:
+    """
+    Use this function to create a valid config.json file from a schema-derived
+    base config, a callback that sets your parameters of interest
+
+    Parameters:
+        config_path (string/path): Path to valid config.json
+        set_fn (function): Callback that sets params with implicit schema enforcement.
+        config: Read-only dict configuration object. Pass this XOR the config_path.
+        verbose: Flag to print debug statements
+
+    Returns:
+        config: read-only dict
+    """
+    if not ((config_path is None) ^ (config is None)):
+        raise Exception('Must specify either a default config_path or config, not neither or both.')
+
+    if verbose:
+        print(f"DEBUG: get_config_from_default_and_params invoked with "
+              f"config_path: {config_path}, config: {config is not None}, {set_fn}.")
+
+    # load default config from file if a path was given
+    if config_path is not None:
+        config = load_default_config_as_rod(config_path)
+        if verbose:
+            print("DEBUG: Calling set_fn.")
+
+    # now that we have a config (either given or loaded from file), call the (possibly given) callback on it
+    if set_fn is not None:
+        config = set_fn(config)
+
+    return config
+
+
+def write_config_from_default_and_params(config_path,
+                                         set_fn,
+                                         config_out_path: Union[str, os.PathLike],
+                                         verbose: bool = False):
+    """
+    Use this function to create a valid config.json file from a schema-derived
+    base config, a callback that sets your parameters of interest, and an output path.
+
+    Parameters:
+        config_path (string/path): Path to valid config.json
+        set_fn (function): Callback that sets params with implicit schema enforcement
+        config_out_path: Path to write new config.json
+        verbose: Flag to print debug statements
+
+    Returns:
+
+    """
+    if verbose:
+        print(f"DEBUG: write_config_from_default_and_params invoked with {config_path}, {set_fn}, and {config_out_path}.")
+    config = get_config_from_default_and_params(config_path=config_path, set_fn=set_fn)
+
+    if verbose:
+        print("DEBUG: Calling finalize.")
+    config.parameters.finalize()
+
+    if verbose:
+        print("DEBUG: Writing output file.")
+    with open(config_out_path, "w") as outfile:
+        json.dump(config, outfile, sort_keys=True, indent=4)

emod_api/config/from_overrides.py

@@ -0,0 +1,135 @@
+#!/usr/bin/python
+
+import sys
+import os
+import json
+from pathlib import Path
+
+
+def _load_json(filepath, post_process=None, ignore_notfound=True):
+    """Load json from a file, with optional post processing of contents prior to parsing"""
+    if os.path.exists(filepath):
+        try:
+            with open(filepath, 'r', encoding='utf-8') as json_file:
+                if post_process:
+                    return json.loads(post_process(json_file.read()))
+                else:
+                    return json.loads(json_file.read())
+        except ValueError:
+            print(f"JSON decode error from file {filepath} ")
+            raise
+        except IOError:
+            print(f"Error accessing json file {filepath} ")
+            raise
+    else:
+        if not ignore_notfound:
+            # should this raise an error?
+            print(f"JSON file not found: {filepath}")
+            raise ValueError
+    return None
+
+
+def _recursive_json_overrider(ref_json, flat_input_json):
+    """
+    Useful function that recursively navigates a pretty arbitrarily structured json config looking
+    for key-value parameters in the leaves.
+    """
+    special_nodes = ["Vector_Species_Params", "Malaria_Drug_Params", "TB_Drug_Params", "HIV_Drug_Params", "STI_Network_Params_By_Property", "TBHIV_Drug_Params"]
+    if ref_json is None:
+        print("Null ref_json (param1) passed into _recursive_json_overrider.")
+        raise ValueError
+
+    for val in ref_json:
+        # if not leaf, call recursive_json_leaf_reader
+        if isinstance(ref_json[val], dict) and val not in special_nodes:
+            _recursive_json_overrider(ref_json[val], flat_input_json)
+        # do VSP and MDP as special case. Sigh sigh sigh. Also TBHIV params now, also sigh.
+        elif val in special_nodes:
+            # could "genericize" this if we need to... happens to work for now, since both VSP and MDP are 3-levels deep...
+            if val not in flat_input_json:
+                flat_input_json[val] = {}
+            elif val == "STI_Network_Params_By_Property" and not ("NONE" in flat_input_json[val].keys()):
+                continue
+
+            for species in ref_json[val]:
+                if species not in flat_input_json[val]:
+                    if (isinstance(ref_json[val][species], dict)):
+                        flat_input_json[val][species] = {}
+                for param in ref_json[val][species]:
+                    if (isinstance(ref_json[val][species], dict)):
+                        if param not in flat_input_json[val][species]:
+                            flat_input_json[val][species][param] = ref_json[val][species][param]
+                    else:
+                        flat_input_json[val][species] = ref_json[val][species]
+        else:
+            if val not in flat_input_json:
+                flat_input_json[val] = ref_json[val]
+
+
+def flattenConfig(configjson_path, new_config_name="config.json", use_full_out_path=False):
+    """
+    Historically called 'flattening' but really a function that takes a parameter override
+    json config that includes a Default_Config_Path and produces a config.json from the two.
+    """
+    if not os.path.exists(configjson_path):
+        raise
+
+    configjson_flat = {}
+    configjson = _load_json(configjson_path)
+
+    _recursive_json_overrider(configjson, configjson_flat)
+
+    # get defaults from config.json and synthesize output from default and overrides
+    if "Default_Config_Path" in configjson_flat:
+        default_config_path = configjson_flat["Default_Config_Path"]
+        stripped_path = default_config_path.strip()
+        if stripped_path != default_config_path:
+            print(f"Warning: config parameter 'Default_Config_Path' has leading or trailing whitespace in value \"{default_config_path}\"."
+                  f" Trimming whitespace and continuing.")
+            default_config_path = stripped_path
+
+        try:
+            # This code has always worked by treating the default_configpath as relative the Regression directory.
+            # No longer doing that, but preserving that capability for back-compat. Going forward, relative to the
+            # configjson_path.
+            simdir = Path(configjson_path).parent
+            default_config_json = None
+            if Path(os.path.join(str(simdir), default_config_path)).exists():
+                default_config_json = _load_json(os.path.join(str(simdir), default_config_path))
+            else:
+                default_config_json = _load_json(os.path.join('.', default_config_path))
+            _recursive_json_overrider(default_config_json, configjson_flat)
+        except Exception as ex:
+            print(f"Exception opening default config {default_config_path}: {ex}.")
+            raise ex
+
+    else:
+        print(f"Didn't find 'Default_Config_Path' in '{configjson_path}'")
+        raise RuntimeError("Bad Default_Config_Path!!!")
+
+    # still need that parameter top level node
+    configjson = {}
+    configjson["parameters"] = configjson_flat
+
+    # don't need backslashes in the default config path
+    # messing with anything else downstream now that it is flattened
+    if "Default_Config_Path" in configjson["parameters"]:
+        configjson["parameters"].pop("Default_Config_Path")
+
+    # let's write out a flat version in case someone wants
+    # to use regression examples as configs for debug mode
+    outfile = new_config_name
+    if not use_full_out_path:
+        outfile = configjson_path.replace(os.path.basename(configjson_path), new_config_name)
+
+    with open(outfile, 'w') as fid01:
+        json.dump(configjson, fid01, sort_keys=True, indent=4)
+
+    return configjson
+
+
+if __name__ == '__main__':
+    if len(sys.argv) > 1:
+        flattenConfig(sys.argv[1])
+    else:
+        print('usage:', sys.argv[0], 'configFile')

emod_api/demographics/age_distribution.py

@@ -0,0 +1,163 @@
+import emod_api.demographics.demographic_exceptions as demog_ex
+
+from emod_api.demographics.updateable import Updateable
+from emod_api.utils import check_dimensionality
+
+
+class AgeDistribution(Updateable):
+    def __init__(self,
+                 ages_years: list[float],
+                 cumulative_population_fraction: list[float]):
+        """
+        A cumulative population age distribution in fraction units 0 to 1. This is used as part of initializing the
+        population in an EMOD simulation.
+
+        The AgeDistribution provides a probability each agent at the beginning of a simulation will be
+        initialized with a given age. A uniform random number is drawn for each agent and checked against the
+        provided cumulative population fractions directly, with the corresponding age entry selected for the agent. If
+        the drawn number lies between two values, the selected agent age is linearly interpolated from the two closest
+        corresponding ages. If the drawn number lies beyond the provided cumulative population fraction range, the
+        closest corresponding age will be selected.
+
+        Args:
+            ages_years: (list[float]) A list of ages (in years) that population fraction data will be provided for.
+                Must be a list of monotonically increasing floats within range 0 <= age <= 200 .
+            cumulative_population_fraction: (list[float]) A list of cumulative population fractions corresponding to
+                the provided ages_years list. Must be a list of monotonically increasing floats within range
+                0 <= fraction <= 1 .
+
+        Example:
+            ages_years: [5, 10, 20, 50, 100]
+            cumulative_population_fraction: [0.1, 0.2, 0.5, 0.8, 1.0]
+
+            Uniform random number draw: 0.8
+                Selected age: 50 years
+            Uniform random number draw: 0.35
+                Selected age: 10 + (0.35 - 0.2) * ((20-10) / (0.5-0.2)) = 15 years
+            Uniform random number draw: 0.05 (beyond provided fraction range)
+                Selected age: 1 year (nearest corresponding age)
+        """
+        super().__init__()
+        self.ages_years = ages_years
+        self.cumulative_population_fraction = cumulative_population_fraction
+        # This will convert the object to an age distribution dictionary and then validate it reporting object-relevant
+        # messages
+        self._validate(distribution_dict=self.to_dict(validate=False), source_is_dict=False)
+
+    @classmethod
+    def _rate_scale_factor(cls):
+        return 365.0  # convert ages in years to days
+
+    def to_dict(self, validate: bool = True) -> dict:
+        distribution_dict = {
+            'ResultValues': self.ages_years,
+            'DistributionValues': self.cumulative_population_fraction,
+            'ResultScaleFactor': self._rate_scale_factor()
+        }
+        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['ResultValues'],
+                   cumulative_population_fraction=distribution_dict['DistributionValues'])
+
+    _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
+        },
+        'data_dimensionality_check_ages': {
+            True: 'ResultValues must be a 1-d array of floats',
+            False: 'ages_years must be a 1-d array of floats'
+        },
+        'data_dimensionality_check_distributions': {
+            True: 'DistributionValues must be a 1-d array of floats',
+            False: 'cumulative_population_fraction must be a 1-d array of floats'
+        },
+        'age_and_distribution_length_check': {
+            True: 'ResultValues and DistributionValues must be the same length but are not',
+            False: 'ages_years and cumulative_population_fraction must be the same length but are not'
+        },
+        'age_range_check': {
+            True: "ResultValues 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}"
+        },
+        'distribution_range_check': {
+            True: "DistributionValues cumulative fractions must be: 0 <= fraction <= 1. "
+                  "Out-of-range index:values : {0}",
+            False: "All cumulative_population_fraction values must be: 0 <= fraction <= 1. "
+                   "Out-of-range index:values : {0}"
+        },
+        'age_monotonicity_check': {
+            True: "ResultValues 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}"
+        },
+        'distribution_monotonicity_check': {
+            True: "DistributionValues cumulative fractions must monotonically increase but do not, index: {0} value: {1}",
+            False: "cumulative_population_fraction values must monotonically increase but do not, index: {0} value: {1}"
+        },
+    }
+
+    @classmethod
+    def _validate(cls, distribution_dict: dict, source_is_dict: bool):
+        """
+        Validate an AgeDistribution in dict form
+
+        Args:
+            distribution_dict: (dict) the age distribution 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 = {
+                'ResultScaleFactor': cls._rate_scale_factor()
+            }
+            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 ages and distribution values are both 1-d iterables of the same length
+        ages = distribution_dict['ResultValues']
+        distribution_values = distribution_dict['DistributionValues']
+
+        is_1d = check_dimensionality(data=ages, dimensionality=1)
+        if not is_1d:
+            message = cls._validation_messages['data_dimensionality_check_ages'][source_is_dict]
+            raise demog_ex.InvalidDataDimensionality(message)
+        is_1d = check_dimensionality(data=distribution_values, dimensionality=1)
+        if not is_1d:
+            message = cls._validation_messages['data_dimensionality_check_distributions'][source_is_dict]
+            raise demog_ex.InvalidDataDimensionality(message)
+
+        if len(ages) != len(distribution_values):
+            message = cls._validation_messages['age_and_distribution_length_check'][source_is_dict]
+            raise demog_ex.InvalidDataDimensionLength(message)
+
+        # ensure the age and distribution value 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)
+        out_of_range = [f"{index}:{value}" for index, value in enumerate(distribution_values)
+                        if (value < 0) or (value > 1)]
+        if len(out_of_range) > 0:
+            oor_str = ', '.join(out_of_range)
+            message = cls._validation_messages['distribution_range_check'][source_is_dict].format(oor_str)
+            raise demog_ex.DistributionOutOfRangeException(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(distribution_values)):
+            if distribution_values[i] - distribution_values[i - 1] <= 0:
+                message = cls._validation_messages['distribution_monotonicity_check'][source_is_dict].format(i, distribution_values[i])
+                raise demog_ex.NonMonotonicDistributionException(message)

emod_api/demographics/base_input_file.py

@@ -0,0 +1,28 @@
+from abc import ABCMeta, abstractmethod
+from datetime import datetime
+
+import getpass
+
+
+class BaseInputFile:
+    __metaclass__ = ABCMeta
+
+    DEFAULT_ID_REFERENCE = "default_id_reference"
+
+    def __init__(self, idref: str = None):
+        self.idref = self.DEFAULT_ID_REFERENCE if idref is None else idref
+
+    @abstractmethod
+    def generate_file(self, name):
+        pass
+
+    def generate_headers(self, extra=None):
+        meta = {
+            "DateCreated": datetime.today().strftime("%m/%d/%Y"),
+            "Tool": "emod-api",
+            "Author": getpass.getuser(),  # LocalOS.username,
+            "IdReference": self.idref,
+            "NodeCount": 0,
+        }
+        meta.update(extra or {})
+        return meta

emod_api/demographics/calculators.py

@@ -0,0 +1,159 @@
+import math
+import numpy as np
+import pandas as pd
+import os
+
+from scipy import sparse as sp
+from scipy.sparse import linalg as la
+from typing import Union
+
+from emod_api.demographics.age_distribution import AgeDistribution
+from emod_api.demographics.mortality_distribution import MortalityDistribution
+
+
+def generate_equilibrium_age_distribution(birth_rate: float = 40.0, mortality_rate: float = 20.0) -> AgeDistribution:
+    """
+    Create an AgeDistribution object representing an equilibrium for birth and mortality rates.
+
+    Args:
+        birth_rate: (float) The birth rate in units of births/year/1000-women
+        mortality_rate: (float) The mortality rate in units of deaths/year/1000 people
+
+    Returns:
+        an AgeDistribution object
+    """
+    from emod_api.demographics.age_distribution import AgeDistribution
+
+    # convert to daily rate per person, EMOD units
+    birth_rate = (birth_rate / 1000) / 365  # what is actually used below
+    mortality_rate = (mortality_rate / 1000) / 365  # what is actually used below
+
+    birth_rate = math.log(1 + birth_rate)
+    mortality_rate = -1 * math.log(1 - mortality_rate)
+
+    # It is important for the age distribution computation that the age-spacing be very fine; I've used 30 days here.
+    # With coarse spacing, the computation in practice doesn't work as well.
+    age_dist_tuple = _computeAgeDist(birth_rate, [i * 30 for i in range(1200)], 1200 * [mortality_rate], 12 * [1.0])
+
+    # The final demographics file, though, can use coarser binning interpolated from the finely-spaced computed distribution.
+    age_bins = list(range(16)) + [20 + 5 * i for i in range(14)]
+    cum_pop_fraction = np.interp(age_bins, [i / 365 for i in age_dist_tuple[2]], age_dist_tuple[1]).tolist()
+    age_bins.extend([90])
+    cum_pop_fraction.extend([1.0])
+    distribution = AgeDistribution(ages_years=age_bins, cumulative_population_fraction=cum_pop_fraction)
+    return distribution
+
+
+def _computeAgeDist(bval, mvecX, mvecY, fVec, max_yr=90):
+    """
+    Compute equilibrium age distribution given age-specific mortality and crude birth rates
+
+    Args:
+        bval: crude birth rate in births per day per person
+        mvecX: list of age bins in days
+        mvecY: List of per day mortality rate for the age bins
+        fVec: Seasonal forcing per month
+        max_yr : maximum agent age in years
+
+    returns EquilibPopulationGrowthRate, MonthlyAgeDist, MonthlyAgeBins
+    author: Kurt Frey
+    """
+
+    bin_size = 30
+    day_to_year = 365
+
+    # Age brackets
+    avecY = np.arange(0, max_yr * day_to_year, bin_size) - 1
+
+    # Mortality sampling
+    mvecX = [-1] + mvecX + [max_yr * day_to_year + 1]
+    mvecY = [mvecY[0]] + mvecY + [mvecY[-1]]
+    mX = np.arange(0, max_yr * day_to_year, bin_size)
+    mX[0] = 1
+    mval = 1.0 - np.interp(mX, xp=mvecX, fp=mvecY)
+    r_n = mval.size
+
+    # Matrix construction
+    BmatRC = (np.zeros(r_n), np.arange(r_n))
+    Bmat = sp.csr_matrix(([bval * bin_size] * r_n, BmatRC), shape=(r_n, r_n))
+    Mmat = sp.spdiags(mval[:-1] ** bin_size, -1, r_n, r_n)
+    Dmat = Bmat + Mmat
+
+    # Math
+    (gR, popVec) = la.eigs(Dmat, k=1, sigma=1.0)
+    gR = np.abs(gR ** (float(day_to_year) / float(bin_size)))
+    popVec = np.abs(popVec) / np.sum(np.abs(popVec))
+
+    # Apply seasonal forcing
+    mVecR = [-2.0, 30.5, 30.6, 60.5, 60.6, 91.5, 91.6, 121.5,
+             121.6, 152.5, 152.6, 183.5, 183.6, 213.5, 213.6, 244.5,
+             245.6, 274.5, 274.6, 305.5, 305.6, 333.5, 335.6, 364.5]
+    fVec = np.flipud([val for val in fVec for _ in (0, 1)])
+    wfVec = np.array([np.mean(np.interp(np.mod(range(val + 1, val + 31), 365),
+                                        xp=mVecR, fp=fVec)) for val in avecY]).reshape(-1, 1)
+    popVec = popVec * wfVec / np.sum(popVec * wfVec)
+
+    # Age sampling
+    avecY[0] = 0
+    avecX = np.clip(np.around(np.cumsum(popVec), decimals=7), 0.0, 1.0)
+    avecX = np.insert(avecX, 0, np.zeros(1))
+
+    return gR.tolist()[0], avecX[:-1].tolist(), avecY.tolist()
+
+
+def generate_mortality_over_time_from_data(data_csv: Union[str, os.PathLike],
+                                           base_year: int) -> MortalityDistribution:
+    """
+    Generate a MortalityDistribution object from a data csv file.
+
+    Args:
+        data_csv: Path to csv file with the mortality rates by calendar year and age bucket.
+        base_year: The calendar year the sim is treating as the base.
+
+    Returns:
+        a MortalityDistribution object.
+    """
+    if base_year < 0:
+        raise ValueError(f"User passed negative value of base_year: {base_year}.")
+    if base_year > 2050:
+        raise ValueError(f"User passed too large value of base_year: {base_year}.")
+
+    # Load csv. Convert rate arrays into DTK-compatiable JSON structures.
+    rates = []  # array of arrays, but leave that for a minute
+    df = pd.read_csv(data_csv)
+    header = df.columns
+    year_start = int(header[1]) # someone's going to come along with 1990.5, etc. Sigh.
+    year_end = int(header[-1])
+    if year_end <= year_start:
+        raise ValueError(f"Failed check that {year_end} is greater than {year_start} in csv dataset.")
+    num_years = year_end - year_start + 1
+    rel_years = list()
+    for year in range(year_start, year_start + num_years):
+        mort_data = list(df[str(year)])
+        rel_years.append(year - base_year)
+
+    age_key = None
+    for trykey in df.keys():
+        if trykey.lower().startswith("age"):
+            age_key = trykey
+            raw_age_bins = list(df[age_key])
+
+    if age_key is None:
+        raise ValueError("Failed to find 'Age_Bin' (or similar) column in the csv dataset. Cannot process.")
+
+    age_bins = list()
+    try:
+        for age_bin in raw_age_bins:
+            left_age = float(age_bin.split("-")[0])
+            age_bins.append(left_age)
+
+    except Exception as ex:
+        raise ValueError(f"Ran into error processing the values in the Age-Bin column. {ex}")
+
+    for idx in range(len(age_bins)):  # 18 of these
+        # mort_data is the array of mortality rates (by year bin) for age_bin
+        mort_data = list(df.transpose()[idx][1:])
+        rates.append(mort_data)  # 28 of these, 1 for each year, eg
+
+    distribution = MortalityDistribution(ages_years=age_bins, mortality_rate_matrix=rates, calendar_years=rel_years)
+    return distribution