Merge pull request #778 from starsimhub/rc2.2

Version 2.2

CHANGELOG.rst

@@ -7,6 +7,15 @@ 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 2.2.0 (2024-11-18)
+---------------------------
+- Starsim is now available for R! See https://r.starsim.org for details.
+- The ``Calibration`` class has been completely rewritten. See the calibration tutorial for more information.
+- A negative binomial distribution is now available as ``ss.nbinom()``.
+- ``ss.Births()`` now uses a binomial draw of births per timestep, rather than the expected value.
+- Added ``ss.load()`` and ``ss.save()`` functions, and removed ``ss.Sim.load()``.
+- *GitHub info*: PR `778 <https://github.com/starsimhub/starsim/pull/778>`_
+
 
 Version 2.1.1 (2024-11-08)
 ---------------------------

README.rst

@@ -7,25 +7,35 @@ Examples of diseases that have already been implemented in Starsim include sexua
 
 Note: Starsim is a general-purpose, multi-disease framework that builds on our previous suite of disease-specific models, which included `Covasim <https://covasim.org>`_, `HPVsim <https://hpvsim.org>`_, and `FPsim <https://fpsim.org>`_. In cases where a distinction needs to be made, Starsim is also known as the "Starsim framework", while this collection of other models is known as the "Starsim suite".
 
-For more information about Starsim, please see the `documentation <https://docs.starsim.org>`__.
+For more information about Starsim, please see the `documentation <https://docs.starsim.org>`__. Information about Starsim for R is available at `r.starsim.org <https://r.starsim.org>`__.
 
 
 Requirements
 ------------
 
-Python 3.9-3.12.
+Python 3.9-3.12 or R.
 
 We recommend, but do not require, installing Starsim in a virtual environment, such as `Anaconda <https://www.anaconda.com/products>`__.
 
 
 Installation
 ------------
 
+Python
+~~~~~~
+
 Starsim is most easily installed via PyPI: ``pip install starsim``.
 
 Starsim can also be installed locally. To do this, clone first this repository, then run ``pip install -e .`` (don't forget the dot at the end!).
 
-*Note:* Starsim leverages Intel's `short vector math library <https://numba.readthedocs.io/en/stable/user/performance-tips.html#intel-svml>`_. If you want to use this (for a ~10% speed improvement), install via `conda install intel-cmplr-lib-rt`.
+R
+~
+R-Starsim is still under development. You can install it with::
+
+  # install.packages("devtools")
+  devtools::install_github("starsimhub/rstarsim")
+  library(starsim)
+  init_starsim()
 
 
 Usage and documentation

docs/tutorials.rst

@@ -12,6 +12,7 @@ User tutorials
     tutorials/tut_diseases.ipynb
     tutorials/tut_transmission.ipynb
     tutorials/tut_interventions.ipynb
+    tutorials/tut_calibration.ipynb
 
 Developer tutorials
 -------------------

docs/tutorials/clean_outputs

@@ -1,7 +1,7 @@
 #!/bin/bash
 # Remove auto-generated files; use -f in case they don't exist
 echo 'Deleting:'
-echo `ls -1 ./my-*.* 2> /dev/null`
-echo '...in 1 second'
-sleep 1
-rm -vf ./my-*.*
+echo `ls -1 ./my-*.* ./example*.* 2> /dev/null`
+echo '...in 2 seconds'
+sleep 2
+rm -vf ./my-*.* ./example*.* 

docs/tutorials/tut_buildsim.ipynb

@@ -126,7 +126,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": 3,
    "id": "d17dd68a",
    "metadata": {
     "collapsed": false,
@@ -186,6 +186,82 @@
     "sim.run().plot()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "f75fdf7e",
+   "metadata": {},
+   "source": [
+    "## Loading and saving\n",
+    "You can save a sim to disk with `sim.save()`, and then reload it:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "7357b64b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sim.save('example.sim')\n",
+    "new_sim = ss.load('example.sim')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a4fc66bf",
+   "metadata": {},
+   "source": [
+    "By default, to save space, this saves a \"shrunken\" version of the sim with most of the large objects (e.g. the `People`) removed. To save everything (for example, if you want to save a partially run sim, then reload it and continue running), you can use `shrink=False`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a682778f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sim.save('example-big.sim', shrink=False)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "591e58ff",
+   "metadata": {},
+   "source": [
+    "All Starsim objects can also be saved via `ss.save()`; this will save the entire object. This is useful for quickly storing objects for use by other Python functions, for example:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "id": "36a48fa5",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df = sim.to_df()\n",
+    "ss.save('example.df', df)\n",
+    "new_df = ss.load('example.df')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9429232c",
+   "metadata": {},
+   "source": [
+    "However, for a human-readable format, you may want to use a different format. For example, if you've exported the results as a dataframe, you can then save as an Excel file:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "id": "383c1c1b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df.to_excel('example.xlsx')"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "c42bb5d0",