\n",
" \n",
"An interactive version of this notebook is available on [Google Colab](https://colab.research.google.com/github/fpsim/fpsim/blob/main/docs/tutorials/T1_intro.ipynb?install=fpsim) or [Binder](https://mybinder.org/v2/gh/fpsim/fpsim/HEAD?labpath=docs%2Ftutorials%2FT1_intro.ipynb).\n",
" \n",
"
"
]
},
{
"cell_type": "markdown",
"id": "68cf6d0c",
"metadata": {},
"source": [
"To create, run, and plot a sim with default options is just:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "5303a6e1",
"metadata": {},
"outputs": [],
"source": [
"import fpsim as fp\n",
"\n",
"sim = fp.Sim(location='kenya')\n",
"sim.run()\n",
"fig = sim.plot()"
]
},
{
"cell_type": "markdown",
"id": "0376ead0",
"metadata": {},
"source": [
"# Defining parameters\n",
"\n",
"Parameters are defined as a dictionary.\n",
"In FPsim, we categorize our parameters as:\n",
"\n",
"* Basic parameters \n", "* Age limits
\n", "* Demographics (urban/rural, wealth)
\n", "* Durations
\n", "* Pregnancy outcomes
\n", "* Fecundity and exposure
\n", "* Contraceptive use
\n", "* Education
\n", "\n", "The most common category of parameters to change in FPsim is the basic category, which includes the geographic location (i.e. Kenya, Senegal, northern India), the starting population, the starting year, and the initial number of agents. We can define these as: " ] }, { "cell_type": "code", "execution_count": null, "id": "2f4f119b", "metadata": {}, "outputs": [], "source": [ "pars = dict(\n", " n_agents = 10_000,\n", " location = 'kenya',\n", " start_year = 2000, \n", " end_year = 2020,\n", ")" ] }, { "cell_type": "markdown", "id": "4597f833", "metadata": {}, "source": [ "# Running simulations\n", "Running a simulation is pretty easy. In fact, running a sim with the parameters we defined above is just:" ] }, { "cell_type": "code", "execution_count": null, "id": "60984bd7", "metadata": {}, "outputs": [], "source": [ "sim = fp.Sim(pars)\n", "sim.run()" ] }, { "cell_type": "markdown", "id": "5b23ea7c-26f6-46d6-870f-0fa291b2c75d", "metadata": {}, "source": [ "# Inspecting results" ] }, { "cell_type": "markdown", "id": "aa7d6d27", "metadata": {}, "source": [ "Running the simulation will generate a results [dictionary] `sim.results`. A dictionary is simply collection of items, and you can access the values of results using different 'key' words. Almost all of the results relevant for FPsim are stored under the key 'fp'; for example, the number of pregnancies over time can be found using `sim.results.fp['pregnancies']`. Execute the code below:" ] }, { "cell_type": "code", "execution_count": null, "id": "97ebd3ed-5c6e-45a5-9b39-bffca34a01dc", "metadata": {}, "outputs": [], "source": [ "sim.results.fp['pregnancies']" ] }, { "cell_type": "markdown", "id": "14f89bf3-2966-4b77-a61e-f2381a8ec26d", "metadata": {}, "source": [ "If you want to see all the 'keys' that are available in the results dictionary you can use" ] }, { "cell_type": "code", "execution_count": null, "id": "b2b3e166-1e15-43b4-b3ba-0f9831e15c7b", "metadata": {}, "outputs": [], "source": [ "sim.list_available_results()" ] }, { "cell_type": "markdown", "id": "f94a8ce8-cbbd-4e76-a186-b8bd6762f563", "metadata": {}, "source": [ "# Slightly different way of defining parameters\n", "You can also specify different parameters by specifyuing them directly as arguments in the simulation object:" ] }, { "cell_type": "code", "execution_count": null, "id": "c355e3c2", "metadata": {}, "outputs": [], "source": [ "sim = fp.Sim(n_agents=10e3, location='kenya', start_year=2000, end_year=2020)\n", "sim.run()" ] }, { "cell_type": "markdown", "id": "e64a8814", "metadata": {}, "source": [ "You can mix and match too – pass in the parameter dictionary (`pars` defined above) with some default options, and then include other parameters as arguments to the sim. Doing this overrides the equally named parameters in `pars` because (keyword) arguments take precedence). For example:" ] }, { "cell_type": "code", "execution_count": null, "id": "8838ba31", "metadata": {}, "outputs": [], "source": [ "sim = fp.Sim(pars, n_agents=100) # Use parameters defined above, but overrides the value `n_agents` in pars, and uses instead 100 agents, not 10,000\n", "sim.run()" ] }, { "cell_type": "markdown", "id": "bc68c9c3", "metadata": {}, "source": [ "Now you know how to run a basic simulation in FPsim and change the parameters. Now let's take a look at the output of the sim." ] }, { "cell_type": "markdown", "id": "c367c231", "metadata": {}, "source": [ "# Explore plotting options for a single simulation\n", "\n", "Let's take a look at the basic suite of plotting options, once we've run our initial simulation.\n", "\n", "The basic plot function will plot births, deaths, and mcpr over the entire simulation.\n", "\n", "There are also pre-defined options that combine similar types of output. For instance, 'apo' stands for adverse pregnancy outcomes, and will plot infant deaths, stillbirths, and abortions.\n", "\n", "plot() will take any of the following options:\n", "\n", "* 'cpr' will plot three different ways to define contraceptive prevalence - mCPR, CPR (includes traditional), and aCPR (includes traditional and restricts denominator to sexually active non-pregnant women)
\n", "* 'apo' will plot adverse pregnancy outcomes, including abortion and miscarriage
\n", "* 'mortality' will plot mortality-related outcomes
\n", "* 'method' plots the method mix over time
" ] }, { "cell_type": "code", "execution_count": null, "id": "1229dd6e", "metadata": {}, "outputs": [], "source": [ "sim.plot() # the default\n", "sim.plot('cpr')" ] }, { "cell_type": "markdown", "id": "bfd61550", "metadata": {}, "source": [ "In the next tutorial, we will look at some of the new features of FPsim 2.0, including how to define different contraceptive choice options." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (Spyder)", "language": "python3", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.12.3" }, "vscode": { "interpreter": { "hash": "f989c29971a53096ab577f7316d908e668661d6c8d7746449c0b0a201f667d60" } } }, "nbformat": 4, "nbformat_minor": 5 }