What’s new#

All notable changes to the codebase are documented in this file. Changes that may result in differences in model output, or are required in order to run an old parameter set with the current version, are flagged with the term “Regression information”.

Version 1.0.4 (2024-08-19)#

Version 1.0.3 (2024-07-26)#

Version 1.0.2 (2024-07-25)#

Version 1.0.1 (2024-06-17)#

Version 1.0.0 (2024-06-07)#

Version 0.28.3 (2024-04-30)#

Version 0.28.2 (2024-04-20)#

  • Refactoring of location directory, such that there is a country folder under locations/ dir containing the data, model script(s), and figs pertaining to that location only

  • Modifies these new paths accordingly in all relevant files

  • GitHub info: PR `https://github.com/fpsim/fpsim/pull/316>`_

Version 0.28.1 (2024-04-11)#

  • Updates regional parameters to calibrate subnationally in Ethiopia

  • Revises subnational calibration script to run for all regions and includes a new multisim script for subnational comparisons

  • GitHub info: PR `https://github.com/fpsim/fpsim/pull/319>`_

Version 0.27.0 (2024-02-09)#

  • Builds out new regional attribute and parameters for subnational dynamics in Ethiopia

  • Creates new subnational calibration script and subfolder for regional datasets and figures

  • GitHub info: PR `https://github.com/fpsim/fpsim/pull/241>`_

Version 0.26.8 (2024-02-08)#

  • Removed unused timeseries_recorder and verbose_sim analyzers.

  • GitHub info: PR 257

Version 0.26.7 (2023-10-24)#

  • Created two scripts in data_processing dir to scrape UN and World Bank country calibration data

  • Updated location_template.txt with logic to pull this scraped data for future contexts

  • GitHub info: PR 213

Version 0.26.6 (2023-9-27)#

  • Renamed the country data filenames to be standardized across contexts

  • Updated references to these updated country data files

  • GitHub info: PR 196

Version 0.26.5 (2023-9-27)#

  • Adds Tutorial for manual calibration to docs/tutorials/ directory

  • GitHub info: PR 166

Version 0.26.4 (2023-9-27)#

  • Refactoring of Experiment class to run with the latest country data formats

  • Country files have updated references to these updated country data files

  • Senegal country data files updated to latest standard format (based on Kenya)

  • GitHub info: PR 193

Version 0.26.3 (2023-9-27)#

  • Updates Senegal files in locations/senegal to be in the same format as Kenya for standardization purposes

  • Minor updates to calibrate_manual.py to be able to run with Senegal data (in addition to Kenya and other contexts)

  • GitHub info: PR 165

Version 0.26.2 (2023-7-25)#

  • Updates code for manual calibration

  • Adds folder to create figures for manual calibration runs

  • GitHub info: PR 164

Version 0.26.1 (2023-6-29)#

  • Updates code for contraceptive matrices

  • Adds contraceptive matrices for Ethiopia to run manual calibration

  • GitHub info: PR 161

Version 0.26.0 (2023-5-31)#

  • Builds out new parameters file for Ethiopia

  • Adds camparison data for Ethiopia calibration

  • GitHub info: PR 156

Version 0.25.0 (2023-5-13)#

  • Adds to sim.py to track sexual inactivity in agents

  • Restricts method use to only those women sexually active over the last 12 months and debuted

  • GitHub info: PR 157

Version 0.24.1 (2023-4-14)#

  • Fixes example_calib.py and example_exp.py to run with fpsim library

  • Updates manual_calibration.py to be flexible to take any location with identically structured data as Kenya

  • GitHub info: PR 133

Version 0.24.0 (2023-3-17)#

  • Finish a manual calibration script for plotting model outcomes vs data for Kenya

  • Goal is to make this script more flexible for other locations, still needs some tweaks for data import

  • Compares ASFR, TFR, age/parity mix, contraceptive use and mix, CPR, pop growth rate, age at first birth, and birth spacing bins

  • GitHub info: PR 133

Version 0.23.2 (2023-3-6)#

  • Add duration of a short birth interval between live births (short_int) to senegal.py

  • Track number of short interval births an agent has had over their life and number are happening at each time step in sim.py

  • Add age limit parameters (age_low, age_high) to senegal.py to track age-specific short interval births.

  • Create a time series plot of all short births interval during a sim as well as the age-specific time series.

  • GitHub info: PR 107

Version 0.23.1 (2023-2-28)#

  • Add location folder for Ethiopia calibration

  • Add comparison data to Ethiopia folder

  • GitHub info: PR 118

Version 0.23.0 (2023-2-10)#

  • Add optimize-space-prefs.py using Calibration class to algorithmically find best birth space params

  • GitHub info: PR 119

Version 0.22.1 (2023-2-03)#

  • Update contraceptive matrices to be weighted

  • GitHub info: PR 113

Version 0.22.0 (2023-1-24)#

  • Add calibrate_manual.py to compare sim runs to data with new data structures

  • Add plot_birth_spacing.py under senegal location to fine tune this calibration

  • GitHub info: PR 109

Version 0.21.2 (2022-12-16)#

  • Updates Kenya, 2nd pass, completed 1st draft

  • Starts calibrate_manual.py for Kenya with ASFR plot

  • GitHub info: PR 76

Version 0.21.1 (2022-12-09)#

  • Updates calibrated data to compare for Kenya, 1st pass

  • Adds raw data to kenya folder

  • GitHub info: PR 70

Version 0.21.0 (2022-12-06)#

  • Updates contraceptive matrices in kenya.py to be from Kenya PMA 2019-2020

  • Adds raw data to kenya folder and processing code to data_processing folder

  • GitHub info: PR 51

Version 0.20.0 (2022-11-30)#

  • Builds out new parameters file for Kenya

  • Adds and reorganizes directories for external data files and data processing scripts

  • GitHub info: PR 37

Version 0.19.2 (2022-10-28)#

  • Added user guide

  • GitHub info: PR 4

Version 0.19.1 (2022-10-26)#

  • Moved to new repository location (fpsim/fpsim)

  • Updated documentation in README

  • Created new tutorials in tutorials folder

  • Ordered tutorials by complexity through T1, T2, T3… Tn numbering system

  • GitHub info: PR 1

Version 0.19.0 (2022-09-01)#

  • Added age-specific plotting for tfr, pregnancies, imr, mmr, stillbirths, and births to Sim, MultiSim, and Scenarios

  • Added ability to plot channels by age over the course of an interval of time (one year, for example)

  • Added yearly age-specific plotting for pregnancies, imr and mmr

  • GitHub info: PR 590

Version 0.18.2 (2022-08-12)#

  • Added age specific plotting for cpr, mcpr, and acpr to Sim, MultiSim, and Scenarios

  • GitHub info: PR 584

Version 0.18.1 (2022-08-08)#

  • Added y-axis scaling to Sim.plot and MultiSim.plot()

  • GitHub info: PR 583

Version 0.18.0 (2022-08-01)#

  • Adjusted stillbirth rates from Nori et al., which was conducted June 2022

  • GitHub info: PR 560

Version 0.17.5 (2022-07-28)#

  • Refactored ExperimentVerbose and verbose_sim and related parts of test suite

  • GitHub info: PR 471

Version 0.17.4 (2022-07-27)#

  • Added new test suite for the Scenarios API

  • GitHub info: PR 527

Version 0.17.3 (2022-07-18)#

  • Added tutorial jupyter notebook to showcase Scenarios features

  • GitHub info: PR 484

Version 0.17.2 (2022-07-15)#

  • Switched method mix plotting from line chart to stacked area chart for all classes

  • GitHub info: PR 568

Version 0.17.1 (2022-07-14)#

  • Added example_scens.py for a quick debug of adding a novel method when developing new features

  • Updated README with new debugging guidance

  • GitHub info*: PR 570

Version 0.17.0 (2022-07-08)#

  • Added method mix timeseries plotting to Sim, MultiSim, and Scenarios through plot(to_plot=’method’)

  • Added some test coverage for method mix plotting

  • GitHub info: PR 554

Version 0.16.2 (2022-07-01)#

  • Refactors channel aggregation in Scenarios.analyze_sims()

  • GitHub info: PR 561

Version 0.16.1 (2022-06-30)#

  • Add tracking of pregnancies

  • Add cumulative sum of pregnancies to plotting functionality (see plot(‘apo’))

  • GitHub info: PR 555

Version 0.16.0 (2022-06-28)#

  • Split matrix age category >25 into 26-35 and >35

  • Baseline contraceptive behavior remains the same, but interventions can differentiate now

  • GitHub info: PR 551

Version 0.15.0 (2022-06-13)#

  • Added new plotting functionality Scenarios.plot('mortality')

  • Added new plotting functionality Scenarios.plot('apo') for adverse pregnancy outcomes

  • Added stillbirths_over_year to keys, tracking, and plotting

  • Added tracking of miscarriage, abortion, corresponding keys and plotting

  • Temporarily commented out plot_interventions in sim.py to fix x-axis and vline issues in plotting

  • GitHub info: PR 549

Version 0.14.2 (2022-06-06)#

  • Adding 3 new columns to the results dataframe in Scenarios

Version 0.14.2 (2022-05-31)#

  • Fixed bug in fp.snapshot() missing non-exact timesteps.

  • Fixed bug with fp.timeseries_recorder() not being capable of being added as a kwarg.

  • Tidied output of SimVerbose.story().

  • Added sim.get_analyzer() and sim.get_intervention() methods (along with the plural versions).

  • Renamed Experiment.dhs_data to Experiment.data; likewise for model_to_calib → model.

  • Fixed bug with MCPR year plotting in Experiment.

  • Fixed bug with analyzers being applied only at the end of the sim instead of at every timestep.

  • Fixed bug with interventions not plotting with simulations.

  • Fixed bug with finalize() not being called for interventions.

  • Increased code coverage of tests from 67% to 80%.

  • GitHub info: PR 533

Version 0.14.1 (2022-05-27)#

  • Fixed bugs in how copy_from is implemented in scenarios.

  • GitHub info: PR 526

Version 0.14.0 (2022-05-26)#

  • Adds an options module, allowing things like DPI to be set via fp.options(dpi=150).

  • Updates plotting options and allows more control over style.

  • Adds more control to plots, including start_year and end_year.

  • Adds a copy_from keyword to method probability update scenarios.

  • Renames years to par_years in scenarios.

  • Changes the logic of the People update step so that lactational amenorrhea is calculated after breastfeeding is updated.

  • Changes the Sim representation to e.g. Sim("My sim"; n=10,000; 1960-2020; results: b=69,541 ☠=11,920 pop=62,630)

  • GitHub info: PR 522

Version 0.13.2 (2022-05-25)#

  • Added ASFR as an output of Experiments.

  • MultiSim.run() now automatically labels un-labeled sims; this fixes bugs in MultiSim plotting functions.

  • MultiSims also have additional error checking (e.g., they cannot be rerun).

  • Refactored data files to be in “tall” instead of “wide” format.

  • Removed years and age bins from summary statistics.

  • GitHub info: PR 517

Version 0.13.1 (2022-05-25)#

  • Changed MultiSim.plot_method_mix() to be able to work with Scenarios

  • GitHub info: PR 513

Version 0.13.0 (2022-05-23)#

  • Changed parameters from a dictionary to a class and added parameters.py. This class has additional validation, the ability to import from/export to JSON, etc.

  • Restructured methods, including renaming pars['method_efficacy'] to pars['methods']['eff'], plus a new entry, pars['methods']['modern'], to specify which are modern methods used for calculating MCPR.

  • Methods have been reordered, grouping traditional and modern methods and sorting modern methods by longevity (e.g. condoms → pill → implants → IUDs).

  • Added ability to add/remove contraceptive methods via pars.add_method() and pars.rm_method().

  • Added a method to run a single scenario.

  • GitHub info: PR 503

Version 0.12.0 (2022-05-22)#

  • Split FPsim repository from analyses scripts.

  • Refactors experiment.py to load files for a specific location rather than being hard-coded.

  • GitHub info: PR 504

Version 0.11.5 (2022-05-21)#

  • Improvements to the scenarios, including more helpful docstrings and error messages.

  • Improved error checking of sims.

  • GitHub info: PR 502

Version 0.11.4 (2022-05-20)#

  • Renamed parameter n to n_agents, and adds parameter scaled_pop.

  • Tracking of switch events is disabled by default; set pars['track_switching'] = True to re-enable.

  • Update default end year from 2019 to 2020.

  • GitHub info: PR 496

Version 0.11.3 (2022-05-20)#

  • Tidied tests folder.

  • Removed the calibration database by default (to keep, use fp.Calibration(keep_db=True).

  • GitHub info: PR 495

Version 0.11.2 (2022-05-20)#

  • Added a people.make_pregnant() method.

  • GitHub info: PR 494

Version 0.11.1 (2022-05-20)#

  • Replaced high and low breastfeeding duration parameters with Gumbel distribution parameters mu and beta.

  • GitHub info: PR 493

Version 0.11.0 (2022-05-20)#

  • Major refactor of senegal.py, organizing parameters into groups and renaming.

  • Parameter names made more consistent, e.g. exposure_correction → exposure_factor, maternal_mortality_multiplier → maternal_mortality_factor.

  • Added comprehensive parameter checking.

  • Updates to the default representation: print(sim) is now a very brief representation; use sim.disp() to get the old behavior.

  • GitHub info: PR 492

Version 0.10.7 (2022-05-19)#

  • Updated fp.Scenarios() API.

  • Added a new fp.Scenario() class, with a convenience function fp.make_scen() for creating new scenarios, for later use with fp.Scenarios().

  • GitHub info: PR 488

Version 0.10.6 (2022-05-19)#

  • Adds fp.parallel() to quickly run multiple sims in parallel and return a MultiSim object.

  • Adds an fp.change_par() intervention.

  • GitHub info: PR 487

Version 0.10.5 (2022-05-18)#

  • Changes how the matrices are implemented. For example, sim['methods']['probs']['18-25'] has been renamed sim['methods']['raw']['annual']['18-25']; sim['methods']['probs']['18-25'] has been renamed sim['methods']['adjusted']['annual']['18-25']; sim['methods_postpartum']['probs1to6']['18-25'] has been renamed sim['methods']['adjusted']['pp1to6']['18-25']; etc.

  • Various other parameters were renamed for consistency (e.g. years → year).

  • Various other methods were renamed for clarity (e.g. maternal_mortality() → check_maternal_mortality(); check_mcpr() → track_mcpr()).

  • Input validation has been added to the Scenarios class.

  • Fixed fp.update_methods() so it can no longer produce probabilities >1.

  • Removed a circular import in scenarios.py.

  • GitHub info: PR 482

Version 0.10.4 (2022-05-17)#

  • Fixes bugs with the MCPR growth implementation, as well as the wrong matrix being used.

  • Added three new parameters: mcpr_growth_rate, mcpr_max, and mcpr_norm_year, to control how MCPR growth is projected into the future.

  • Updated sim.run() to return self rather than self.results.

  • GitHub info: PR 480

Version 0.10.3 (2022-05-12)#

  • Move country-specific parameters from fpsim.data to fpsim.locations.

  • GitHub info: PR 464

Version 0.10.2 (2022-05-10)#

  • Refactored People.get_method() to use more efficient looping.

  • Numbafied n_multinomial() to get a ~20% speed increase.

  • Added a method_timestep parameter to allow skipping contraceptive matrix updates (saves significant time for small sims).

  • Added fp.pars(location='test') to use defaults for testing (e.g. small population size).

  • Fixed divide-by-zero bug for small population sizes in total fertility rate.

  • Refactored tests; they should now run locally in ~15 s.

  • GitHub info: PR 448

Version 0.10.1 (2022-05-09)#

  • Fix Scenarios class.

  • GitHub info: PR 433

Version 0.10.0 (2022-05-08)#

  • Moved Senegal parameters into FPsim.

  • Added age of sexual debut.

  • GitHub info: PR 427

Version 0.9.0 (2022-05-05)#

  • Added a new Scenarios class.

  • GitHub info: PR 416

Version 0.8.0 (2021-08-28)#

  • Refactored the People object to use a new filtering-based approach.

  • GitHub info: PR 219

Version 0.7.3 (2021-07-15)#

  • Fix bug to ensure that at least one process runs on each worker.

  • GitHub info: PR 163

Version 0.7.2 (2021-07-14)#

  • Allow total_trials to be passed to an fp.Calibration object.

  • GitHub info: PR 162

Version 0.7.1 (2021-07-14)#

  • Allow weights to be passed to an fp.Calibration object.

  • GitHub info: PR 161

Version 0.7.0 (2021-06-29)#

  • Added new calibration plotting methods.

  • Separated Experiment and Calibration into separate files, and renamed model.py to sim.py.

  • Fixed a bug where the age pyramid was being unintentionally modified in-place.

  • GitHub info: PR 144

Version 0.6.5 (2021-06-11)#

  • Added R support; see examples/example_sim.R.

  • Fixed a bug where the age pyramid was being unintentionally modified in-place.

  • GitHub info: PR 128

Version 0.6.4 (2021-06-10)#

  • Added a MultiSim class, which can handle parallel runs and uncertainty bounds.

  • GitHub info: PR 124

Version 0.6.3 (2021-06-10)#

  • Fixed a bug where exposure correction by age was accidentally being clipped to the range [0,1], restoring behavior of the array-based model to match the object-based model (notwithstanding stochastic effects and other bugfixes).

  • GitHub info: PR 119

Version 0.6.2 (2021-05-10)#

  • Added fp.Intervention and fp.Analyzer classes, which are much more flexible ways to modify and record the state of the simulation, respectively.

  • Fixed a bug with only females being born.

  • GitHub info: PR 100

Version 0.6.1 (2021-05-02)#

  • Renamed fp.Calibration to fp.Experiment, and added a new fp.Calibration class, using Optuna.

  • This allows the user to do e.g. calib = fp.Calibration(pars); calib.calibrate(calib_pars)

  • Calibrating a single parameter takes about 20 seconds for a single parameter and a small population size (500 people). Realistic calibrations should take roughly 10 - 60 minutes.

  • GitHub info: PR 93

Version 0.6.0 (2021-05-01)#

  • Refactored the model to use an array-based implementation, instead of a loop over individual people.

  • This results in a performance increase of roughly 20-100x, depending on the size of the simulation. In practice, this means that 50,000 people can be run in roughly the same amount of time as 500 could be previously.

  • GitHub info: PR 92

Version 0.5.2 (2021-04-30)#

  • Added a new script, preprocess_data.py, that takes large raw data files and preprocesses them down to only the essentials used in the model.

  • This increases the performance of calib.run() (not counting model runtime) by a factor of 1000.

  • GitHub info: PR 91

Version 0.5.1 (2021-04-29)#

  • Added summarize() and to_json() methods to Calibration. Also added an fp.diff_summaries() method for comparing them.

  • Added regression and benchmarking tests (current total time: 24 s).

  • Added a code coverage script (current code coverage: 59%).

  • Added default flags for which quantities to compute.

  • Split the logic of Calibration out into more detail: e.g., initialization, running, and post-processing.

  • GitHub info: PR 90