diff --git a/.github/workflows/static_html_deploy.yml b/.github/workflows/static_html_deploy.yml index fce9f7d..cf1b41a 100644 --- a/.github/workflows/static_html_deploy.yml +++ b/.github/workflows/static_html_deploy.yml @@ -46,6 +46,7 @@ jobs: # which you find below to build all documents git fetch --tags cd docs + poetry run ipython kernel install --name "boario" --user poetry run python ./source/build_docs.py - name: Setup Pages uses: actions/configure-pages@v5 diff --git a/README.rst b/README.rst index 93e101b..6cc2c65 100644 --- a/README.rst +++ b/README.rst @@ -42,17 +42,17 @@ hesitate to contact the author when using the model ! What is BoARIO ? ================= -BoARIO, is a python implementation project of the Adaptative Regional Input Output (ARIO) model [`Hallegatte 2013`_]. +BoARIO, is a python implementation project of the Adaptative Regional Input Output (ARIO) model [`Hal13`_]. Its objectives are to give an accessible and inter-operable implementation of ARIO, as well as tools to visualize and analyze simulation outputs and to evaluate the effects of many parameters of the model. -This implementation would not have been possible without the `Pymrio`_ module and amazing work of [`Stadler 2021`_] ! +This implementation would not have been possible without the `Pymrio`_ module and amazing work of [`Sta21`_]. -It is still an ongoing project (in parallel of a PhD project). +It is still an ongoing project (in parallel with a PhD project). -.. _`Stadler 2021`: https://openresearchsoftware.metajnl.com/articles/10.5334/jors.251/ -.. _`Hallegatte 2013`: https://doi.org/10.1111/j.1539-6924.2008.01046.x +.. _`Sta21`: https://openresearchsoftware.metajnl.com/articles/10.5334/jors.251/ +.. _`Hal13`: https://doi.org/10.1111/j.1539-6924.2008.01046.x .. _`Pymrio`: https://pymrio.readthedocs.io/en/latest/intro.html You can find most academic literature using ARIO or related models `here `_ @@ -63,15 +63,37 @@ What is ARIO ? ARIO stands for Adaptive Regional Input-Output. It is an hybrid input-output / agent-based economic model, designed to compute indirect costs from economic shocks. Its first version dates back to 2008 and has originally -been developed to assess the indirect costs of natural disasters (Hallegatte 2008). +been developed to assess the indirect costs of natural disasters [`Hal08`_]. In ARIO, the economy is modelled as a set of economic sectors and a set of regions. Each economic sector produces its generic product and draws inputs from an inventory. Each sector answers to a total demand consisting of a final demand (household consumption, public spending and private investments) of all regions (local demand and exports) and intermediate demand (through inputs inventory resupply). An initial equilibrium state of -the economy is built based on multi-regional input-output tables (MRIO tables). +the economy is built based on multi-regional input-output tables (MRIOTs). +For a more detailed description, please refer to the `Mathematical documentation`_ of the model. + +Multi-Regional Input-Output tables +------------------------------------- + +Multi-Regional Input-Output tables (MRIOTs) are comprehensive economic data sets +that capture inter-regional trade flows, production activities, and consumption +patterns across different regions or countries. These tables provide a detailed +breakdown of the flows of goods and services between industries within each +region and between regions themselves. MRIOTs are constructed through a +combination of national or regional input-output tables, international trade +data, and other relevant economic statistics. By integrating data from multiple +regions, MRIOTs enable the analysis of global supply chains, international trade +dependencies, and the estimation of economic impacts across regions. However, +they also come with limitations, such as data inconsistencies across regions, +assumptions about trade patterns and production technologies, and the challenge +of ensuring coherence and accuracy in the aggregation of data from various +sources. + +.. _`Mathematical documentation`: https://spjuhel.github.io/BoARIO/boario-math.html + +.. _`Hal08`: https://doi.org/10.1111/risa.12090 Where to get BoARIO ? ========================== @@ -98,18 +120,21 @@ How does BoARIO work? In a nutshell, BoARIO takes the following inputs : -- an IO table (such as EXIOBASE3 or EORA26) in the form of an ``pymrio.IOSystem`` object, using the `Pymrio`_ python package. +- a (possibly Environmentally Extended) Multi-Regional IO table (such as `EXIOBASE 3`_ or `EORA26`_) in the form of an ``pymrio.IOSystem`` object, using the `Pymrio`_ python package. Please reference the `Pymrio documentation `_ for details on methods available to pymrio objects. - multiple parameters which govern the simulation, - event(s) description(s), which are used as the perturbation to analyse during the simulation -And produce the following outputs: +And produces the following outputs: - the step by step, sector by sector, region by region evolution of most of the variables involved in the simulation (`production`, `demand`, `stocks`, ...) - aggregated indicators for the whole simulation (`shortages duration`, `aggregated impacts`, ...) +.. _`EXIOBASE 3`: https://www.exiobase.eu/ +.. _`EORA26`: https://worldmrio.com/eora26/ + Example of use ================= diff --git a/boario/__init__.py b/boario/__init__.py index c855108..fd1d058 100644 --- a/boario/__init__.py +++ b/boario/__init__.py @@ -30,22 +30,58 @@ __version__ = importlib.metadata.version("boario") __author__ = "sjuhel " -# __minimum_python_version__ = "3.8" - -# Create a logger object. -logger = logging.getLogger(__name__) -logger.addHandler(logging.NullHandler()) - DEBUGFORMATTER = logging.Formatter( - fmt="%(asctime)s [%(levelname)s] - [%(filename)s > %(funcName)s() > %(lineno)s] - %(message)s", + fmt="%(asctime)s - boario - [%(levelname)s] - [%(filename)s > %(funcName)s() > %(lineno)s] - %(message)s", datefmt="%H:%M:%S", ) - """Debug file formatter.""" + INFOFORMATTER = logging.Formatter( - fmt="%(asctime)s [%(levelname)s] - %(message)s", + fmt="%(asctime)s - boario - [%(levelname)s] - %(message)s", datefmt="%H:%M:%S", ) +"""Info file formatter.""" + + +# Create a logger object. +logger = logging.getLogger(__name__) +logger.setLevel(logging.INFO) + +# Console logger +ch = logging.StreamHandler() +ch.setLevel(logging.INFO) +ch.setFormatter(INFOFORMATTER) + +# Avoid adding multiple handlers in case of repeated imports +if not logger.handlers: + logger.addHandler(ch) + + +# Functions to activate/deactivate logging +def deactivate_logging(): + """Deactivate logging for the package.""" + logger.disabled = True + + +def activate_logging(): + """Activate logging for the package.""" + logger.disabled = False + + +# Functions to disable/enable console logging +def disable_console_logging(): + """Disable console logging for the package.""" + logger.info( + "Disabling logging. You can reenable it with `boario.enable_console_logging()`" + ) + logger.removeHandler(ch) + + +def enable_console_logging(): + """Enable console logging for the package.""" + if ch not in logger.handlers: + logger.addHandler(ch) + try: import pygit2 @@ -55,12 +91,17 @@ logger.info("You are using boario from branch %s", __git_branch__) except pygit2.GitError: logger.info( - "Could not find git branch, this is normal if you installed boario from pip." + "Could not find git branch, this is normal if you installed boario from pip/conda." ) except ModuleNotFoundError: logger.info("Unable to tell git branch as pygit2 was not found.") +logger.info( + "Loaded boario module. You can disable logging in console with `boario.disable_console_logging()`." +) + + @lru_cache(10) def warn_once(logger, msg: str): logger.warning(msg) diff --git a/boario/event.py b/boario/event.py index d5a3978..092cabe 100644 --- a/boario/event.py +++ b/boario/event.py @@ -494,8 +494,11 @@ def from_scalar_regions_sectors( Event An Event object or one of its subclass. """ + if not isinstance(impact, (int, float)): + raise ValueError("Impact is not scalar.") + if impact <= 0: - raise ValueError("Impact is null") + raise ValueError("Impact is null.") if isinstance(regions, str): regions = [regions] diff --git a/boario/model_base.py b/boario/model_base.py index 5f53619..f06d2d2 100644 --- a/boario/model_base.py +++ b/boario/model_base.py @@ -895,7 +895,7 @@ def production_cap(self) -> npt.NDArray: production_cap = production_cap * self.overprod if (production_cap < 0).any(): raise ValueError( - "Production capacity was found negative for at least on industry" + "Production capacity was found negative for at least on industry. It may be caused by an impact being to important for a sector." ) return production_cap diff --git a/boario/simulation.py b/boario/simulation.py index 261754d..58b2706 100644 --- a/boario/simulation.py +++ b/boario/simulation.py @@ -303,13 +303,14 @@ def __init__( "n_temporal_units_by_step": self.model.n_temporal_units_by_step, "year_to_temporal_unit_factor": self.model.iotable_year_to_temporal_unit_factor, "inventory_restoration_tau": ( - list(self.model.restoration_tau) + list(np.reciprocal(self.model.restoration_tau)) if isinstance(self.model, ARIOPsiModel) else None ), "alpha_base": self.model.overprod_base, "alpha_max": self.model.overprod_max, - "alpha_tau": self.model.overprod_tau, + "alpha_tau": self.model.overprod_tau + * self.model.iotable_year_to_temporal_unit_factor, "rebuild_tau": self.model.rebuild_tau, } """dict: A dictionary saving the parameters the simulation was run with.""" @@ -416,7 +417,7 @@ def loop(self, progress: bool = True): self.model.write_index(self.results_storage / "jsons" / "indexes.json") self.params_dict["n_temporal_units_simulated"] = self.n_temporal_units_simulated - self.has_crashed = self.has_crashed + self.params_dict["has_crashed"] = self.has_crashed if self._save_params: with ( @@ -432,7 +433,10 @@ def loop(self, progress: bool = True): indent=4, cls=CustomNumpyEncoder, ) - logger.info("Loop complete") + if self.has_crashed: + logger.info("Loop crashed before completion.") + else: + logger.info("Loop complete") def next_step( self, @@ -551,7 +555,7 @@ def next_step( ): self._write_rebuild_prod() except RuntimeError: - logger.exception("An exception happened:") + logger.exception("An exception happened: ") self.model.matrix_stock.dump( self.results_storage / "matrix_stock_dump.pkl" ) diff --git a/docs/source/_static/switcher.json b/docs/source/_static/switcher.json index 40a0cd1..c7c9e7d 100644 --- a/docs/source/_static/switcher.json +++ b/docs/source/_static/switcher.json @@ -1,10 +1,15 @@ [ { "name": "latest", - "version": "v0.5.9", + "version": "v0.5.10", "url": "https://spjuhel.github.io/BoARIO/", "preferred": true }, + { + "name": "v0.5.9", + "version": "v0.5.9", + "url": "https://spjuhel.github.io/BoARIO/v0.5.9/en" + }, { "name": "v0.5.8", "version": "v0.5.8", diff --git a/docs/source/boario-math.rst b/docs/source/boario-math.rst index 762ad11..4134008 100644 --- a/docs/source/boario-math.rst +++ b/docs/source/boario-math.rst @@ -6,12 +6,12 @@ Model description Background and overview ======================= - + Adaptive Regional Input-Output (ARIO) is an I-O model, designed to compute indirect costs from exogenous shocks. Its first version dates back to 2008 and has originally -been developed to assess the indirect costs of natural disasters (Hallegatte 2008). +been developed to assess the indirect costs of natural disasters :cite:`2008:hallegatte`. In this paper we present BoARIO, a generic python implementation, similar to the one -described in (Hallegatte 2014) with some additions (e.g. inspired by Guan et al. 2020). +described in :cite:`2013:hallegatte` with some additions (e.g. inspired by :cite:`2020:guan`). The economy is modelled as a set of economic sectors and a set of regions. In the following, we call an industry a specific (sector, region) couple. @@ -23,11 +23,11 @@ An initial equilibrium state of the economy is built based on multi-regional input-output tables (MRIO tables). Apart from parameters specific to the MRIOT region-sector typology, BoARIO supposedly handles any MRIOT in the same manner. -Multiple kinds of shocks can be implemented: +Multiple kinds of shocks can be implemented: * On the production capacity directly (one or multiple industries are arbitrarily forced to produce less) -* On the productive capital (one or multiple industries arbitrarily +* On the productive capital (one or multiple industries arbitrarily lose some part of their factors of production and are thus forced to both produce less and to build back their capital stock). * On the households (households of affected regions lose some part of their goods and @@ -45,7 +45,7 @@ industries adjust their production and orders based on both demand and their inv Direct economic impact consists in the valuation of the initial exogenous shock, while total economic impact includes also indirect costs consequent to the propagation. -Total economic impact can be measured in two ways: +Total economic impact can be measured in two ways: * Final demand not met, i.e. goods that households couldn’t buy due to rationing. * Relative production change, i.e. diminished or increased production of industries relative to their initial production. diff --git a/docs/source/conf.py b/docs/source/conf.py index d045fd9..fc557cc 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -54,6 +54,8 @@ napoleon_use_param = False napoleon_use_ivar = False +nbsphinx_kernel_name = "boario" + # automatically generate api references autosummary_generate = ["boario-api-reference.rst"] diff --git a/docs/source/notebooks/boario-quickstart.ipynb b/docs/source/notebooks/boario-quickstart.ipynb index 5f98aa2..bee27d9 100644 --- a/docs/source/notebooks/boario-quickstart.ipynb +++ b/docs/source/notebooks/boario-quickstart.ipynb @@ -1,32 +1,31 @@ { "cells": [ { - "attachments": {}, "cell_type": "markdown", - "id": "ea635dab-2c7f-40e5-b24e-f2ca9ae00de8", + "id": "b4f2960c", "metadata": {}, "source": [ "# Quickstart example\n", "\n", "In the following example, we use the \"test\" MRIOT of the pymrio module,\n", - "which doesn't require to load additional data and has a low number of sectors and\n", + "which doesn't require loading additional data and has a low number of sectors and\n", "regions, allowing fast computation." ] }, { "cell_type": "markdown", - "id": "e3347cab-34e3-46df-8bb2-ff280010b220", + "id": "268d8c43", "metadata": {}, "source": [ "## Instantiating a model from a MRIOT system\n", "\n", - "First import the required elements. We use the ARIOPsiModel version here (which you probably should)." + "First import the required elements. We use the ARIOPsiModel version here (which you probably should as well)." ] }, { "cell_type": "code", - "execution_count": 1, - "id": "dc3e74db-72e0-4dde-bac2-4e6be2d61885", + "execution_count": null, + "id": "9bc7e315", "metadata": {}, "outputs": [], "source": [ @@ -38,16 +37,16 @@ }, { "cell_type": "markdown", - "id": "75869ca2-834e-4605-b8aa-e50e2bfa0a31", + "id": "132749ea", "metadata": {}, "source": [ - "Some attributes of the test MRIOT are not computed. Calling calc_all() insure all required tables are present in the IOSystem object." + "Some attributes of the test MRIOT are not computed. Calling calc_all() ensures all required tables are present in the IOSystem object. This ``pymrio.IOSystem`` method automatically identifies which tables are missing and calculates them following the IO formal framework. (See [here](https://pymrio.readthedocs.io/en/latest/math.html) for more details.)" ] }, { "cell_type": "code", "execution_count": null, - "id": "d05964f3-46c6-4a18-ace2-1245b387dfdf", + "id": "347595c0", "metadata": {}, "outputs": [], "source": [ @@ -56,19 +55,19 @@ }, { "cell_type": "markdown", - "id": "d72c86bb-7f99-427c-8ffb-761d4a48c0ae", + "id": "b5284dae", "metadata": {}, "source": [ - "If you see multiple: ``FutureWarning: DataFrame.groupby with axis=1 is deprecated. Do `frame.T.groupby(...)` without axis instead.``\n", - "Don't panic, this comes from `pymrio` but it is not an error, just a synthax warning.\n", + "If you see multiple: ``FutureWarning: DataFrame.groupby with axis=1 is deprecated. Do \\`frame.T.groupby(...)\\` without axis instead.``\n", + "don't panic, this comes from `pymrio` but it is not an error, just a syntax warning.\n", "\n", "In case you find it annoying, you can use the following beforehand:" ] }, { "cell_type": "code", - "execution_count": 3, - "id": "e8cb2f4a-90db-45c2-a843-2584b933c67a", + "execution_count": null, + "id": "7a568ae5", "metadata": {}, "outputs": [], "source": [ @@ -78,7 +77,7 @@ }, { "cell_type": "markdown", - "id": "fdd322f4-801d-4529-9d36-361d682d78ae", + "id": "453afa0d", "metadata": {}, "source": [ "Instantiating the model is very straightforward:" @@ -86,8 +85,8 @@ }, { "cell_type": "code", - "execution_count": 4, - "id": "dbbaf28c-1395-40b9-8827-b4a67719d530", + "execution_count": null, + "id": "47d4962d", "metadata": {}, "outputs": [], "source": [ @@ -96,7 +95,7 @@ }, { "cell_type": "markdown", - "id": "b02e17f9-0c8f-4f2a-bc43-d46689f75990", + "id": "1d504000", "metadata": {}, "source": [ "This sets the model with all the default parameters. We highly recommand you to study the different parameters and their options for actual use. See [Changing the model parameters](../tutorials/model-params.rst)." @@ -104,7 +103,7 @@ }, { "cell_type": "markdown", - "id": "e1032274-d90b-4d0c-bcfc-7187f4faa2d6", + "id": "b69c3e85", "metadata": {}, "source": [ "Similarly, instantiating a simulation is also quite easy:" @@ -112,8 +111,8 @@ }, { "cell_type": "code", - "execution_count": 5, - "id": "05fd6465-4f25-41a2-9ef6-b87089b4ea2e", + "execution_count": null, + "id": "3faa2992", "metadata": {}, "outputs": [], "source": [ @@ -124,7 +123,7 @@ }, { "cell_type": "markdown", - "id": "ec170d85-0ce8-42e9-836b-d340c2c0bfad", + "id": "32d06777", "metadata": {}, "source": [ "Once the model and simulation have been instantiated, you can now define an event:" @@ -132,8 +131,8 @@ }, { "cell_type": "code", - "execution_count": 6, - "id": "e1039d30-5394-49fb-8755-fb830192f947", + "execution_count": null, + "id": "649d8dc8", "metadata": {}, "outputs": [], "source": [ @@ -153,10 +152,10 @@ }, { "cell_type": "markdown", - "id": "70453532-ec2c-4065-a571-25cee5d0977f", + "id": "64f06955", "metadata": {}, "source": [ - "Here we define an event happening in region ``reg1`` impacting the productive capital of the ``manufactoring``[^note-1] and ``mining`` sectors. The impact is distributed among the two sectors proportional to their participation to ``reg1``'s GDP. \n", + "Here we define an event happening in region ``reg1`` impacting the productive capital of the ``manufactoring``[^note-1] and ``mining`` sectors. The impact is distributed among the two sectors proportional to their participation to ``reg1``'s GDP.\n", "\n", "Here the entire impact is translated into a reconstruction demand, handled by the ``construction`` (55%) and ``manufactoring`` (45%) sectors. This reconstruction has a characteristic time of 90 unit steps.\n", "\n", @@ -167,7 +166,7 @@ }, { "cell_type": "markdown", - "id": "ffe4839a-906f-48bd-bcaa-29fe6b728d16", + "id": "1981ad4e", "metadata": {}, "source": [ "The event can then be added to the simulation:" @@ -175,8 +174,8 @@ }, { "cell_type": "code", - "execution_count": 7, - "id": "ba833cbb-5ed0-46c9-bdc5-6cfc38eb919d", + "execution_count": null, + "id": "d200e2e2", "metadata": {}, "outputs": [], "source": [ @@ -186,7 +185,7 @@ }, { "cell_type": "markdown", - "id": "79689367-1a04-4b43-a2fc-81d8b3c4ddb5", + "id": "526824cc", "metadata": {}, "source": [ "And the loop can be run:" @@ -194,27 +193,18 @@ }, { "cell_type": "code", - "execution_count": 8, - "id": "e99a88ca-9c0e-4d73-b513-3e0af572a35d", + "execution_count": null, + "id": "c07b1032", "metadata": {}, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "Processed: Step: 730 ~ \u001b[38;2;0;255;0m100%\u001b[39m Time: 0:00:01 \n", - "Processed: Step: 730 ~ \u001b[38;2;0;255;0m100%\u001b[39m Time: 0:00:01 " - ] - } - ], + "outputs": [], "source": [ "# Launch the simulation\n", - "sim.loop()" + "sim.loop(progress=False)" ] }, { "cell_type": "markdown", - "id": "2abf3a49-5e1c-4d55-bf5e-0db81129b6e0", + "id": "e1eb4f5f", "metadata": {}, "source": [ "Once the simulation ran, you can access and plot the timeseries of the variables (see [Monitoring the variables](../tutorials/simulation-context.rst#monitoring-the-model-variables) for a list of accessible variables).\n", @@ -224,33 +214,12 @@ }, { "cell_type": "code", - "execution_count": 9, - "id": "2c2add52-72fb-45d7-9f7b-ade044acc0f9", + "execution_count": null, + "id": "0945f5f9", "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "" - ] - }, - "execution_count": 9, - "metadata": {}, - "output_type": "execute_result" - }, - { - "data": { - "image/png": "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", - "text/plain": [ - "
" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], + "outputs": [], "source": [ - "# You should be able to generate a dataframe of\n", + "# You can generate a dataframe of\n", "# the production with the following line\n", "df = sim.production_realised\n", "# This allows to normalize production at its initial level\n", @@ -265,20 +234,8 @@ "display_name": "boario", "language": "python", "name": "boario" - }, - "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.11.8" } }, "nbformat": 4, "nbformat_minor": 5 -} +} \ No newline at end of file diff --git a/docs/source/tutorials/model-params.rst b/docs/source/tutorials/model-params.rst index 59d80b5..e8bcece 100644 --- a/docs/source/tutorials/model-params.rst +++ b/docs/source/tutorials/model-params.rst @@ -36,17 +36,17 @@ Parameters are set when instantiating the model. The following block shows all c ) -Here a quick description of each parameters. Please refer to both :ref:`the mathematical description` and the :ref:`api-ref` for further details. +Here is a quick description of each parameters. Please refer to both :ref:`the mathematical description` and the :ref:`api-ref` for further details. * ``order_type`` : Setting it to ``"alt"`` makes the model use the intermediate order mechanism described in :cite:`2020:guan`. Any other value makes the model use the `classic` order mechanism used in :cite:`2013:hallegatte` (see :ref:`alt_orders`) -* ``alpha_base``, ``alpha_max``, ``alpha_tau`` respectively set the base overproduction, the maximum overproduction, and its characteristic time (in `temporal unit`). +* ``alpha_base``, ``alpha_max``, ``alpha_tau`` respectively set the base overproduction, the maximum overproduction, and its characteristic time (in `temporal units`). * ``rebuild_tau`` sets the default rebuilding or recovering characteristic time for events (this value is overridden if specified directly in the Event object) * ``inventory_dict`` should be a dictionary of ``sector:duration`` format, where all sector are present and ``duration`` is both the initial and goal duration for this input stock. -* ``main_inv_dur`` sets the default initial/goal inventory duration in `temporal unit` for all sectors if inventory_dict is not given. +* ``main_inv_dur`` sets the default initial/goal inventory duration in `temporal units` for all sectors if inventory_dict is not given. * ``infinite_inventories_sect`` should be a list of inputs never constraining production (the stocks for these input will be virtually infinite when considering stock constraints) (overridden by ``inventory_dict``) @@ -77,7 +77,7 @@ Focus on the temporal dimension .. warning:: These features have not been extensively tested and should be handled with great care. - Feedbacks are welcome! + Feedback is welcome! The temporal dimension is an important aspect of dynamically modeling indirect economic impacts. @@ -85,14 +85,14 @@ Historically, ARIO has been used both using weekly and daily steps, but mostly t BoARIO's implementation of ARIO aims at being independent of the ``temporal unit`` considered, notably to study how this aspect influences the results. -This means it is virtually possible to run ARIO on any temporal granularity of your choosing. +This means it is possible to run ARIO on virtually any temporal granularity of your choosing. -Furthermore, for efficiency purpose, this implementation allows to simulate only some ``temporal unit`` -and interpolate state variables in between. +Furthermore, for efficiency purposes, this implementation allows you to simulate only some ``temporal units`` +and interpolate state variables between them. -Hence a ``step`` can represent multiple ``temporal units``. Although by default, a ``step`` equals a ``temporal unit`` equals a `day` and -defaults values of characteristic times and other time related variable are accordingly expressed in number of days, these three terms are conceptually -different. For this reason we will favor the term ``temporal unit`` to designate the atomic period in the model throughout this documentation. +Hence a ``step`` can represent multiple ``temporal units``. By default, a ``step`` equals a ``temporal unit`` equals a `day` and +defaults values of characteristic times and other time related variable are accordingly expressed in number of days. +However, because it is customisable, we favor the term ``temporal unit`` to designate the atomic period in the model throughout this documentation. The number of ``temporal units`` to simulate can be set when instantiating the ``Simulation`` object like so: diff --git a/docs/source/tutorials/mriot-input.rst b/docs/source/tutorials/mriot-input.rst index eeee143..c99bb31 100644 --- a/docs/source/tutorials/mriot-input.rst +++ b/docs/source/tutorials/mriot-input.rst @@ -14,6 +14,10 @@ vector ``x`` as attributes, and to be balanced. This should be the case for all MRIOT parsed with the ``pymrio`` package. Refer to its `documentation `_ for more details. +In particular, if you want to build your own MRIOT based on your own data source, you should read +`this part `_ +of pymrio's documentation. + .. attention:: Note that the (region,sector) Multiindexes for the matrices and vector are reordered by BoARIO to be in lexicographic order. diff --git a/docs/source/tutorials/simulation-context.rst b/docs/source/tutorials/simulation-context.rst index 08eadc4..a474744 100644 --- a/docs/source/tutorials/simulation-context.rst +++ b/docs/source/tutorials/simulation-context.rst @@ -21,7 +21,7 @@ The length of the simulation can be set by the ``n_temporal_units_to_sim`` argum Running multiple simulations _______________________________ -At the moment we recommend redefining both a model and a simulation object when running multiple simulation. Running multiple simulations with the same model and simulation wrapper, using :py:meth:`Simulation.reset_sim_full()` has not been extensively tested yet, and some unwanted behavior may remain. +At the moment we recommend redefining both a model and a simulation object when running multiple simulations. Running multiple simulations with the same model and simulation wrapper, using :py:meth:`Simulation.reset_sim_full()` has not been extensively tested yet, and some unwanted behavior may remain. Reading the outputs and saving files @@ -76,7 +76,7 @@ Here is a commented list of the different variables accessible: # byte, -1 for False, 1 for True sim.limiting_inputs -It is also possible to record the inputs stocks, but this is disabled by defaults as its shape is the same as +It is also possible to record the inputs stocks, but this is disabled by default as its shape is the same as ``limiting_inputs``, but its ``dtype`` is ``float64``, which can very rapidly lead to huge arrays difficult to have in memory. .. code:: python diff --git a/docs/source/versions.yaml b/docs/source/versions.yaml index e4a1ed6..12932f8 100644 --- a/docs/source/versions.yaml +++ b/docs/source/versions.yaml @@ -1,3 +1,8 @@ +"v0.5.9": + tag: 'v0.5.9' + languages: + - "en" + "v0.5.8": tag: 'v0.5.8' languages: diff --git a/paper.md b/paper.md index a121ca1..6bf0cac 100644 --- a/paper.md +++ b/paper.md @@ -8,7 +8,6 @@ tags: authors: - name: Samuel Juhel orcid: 0000-0001-8801-3890 - equal-contrib: true affiliation: "1, 2" # (Multiple affiliations must be quoted) affiliations: - name: CIRED, France @@ -23,26 +22,27 @@ bibliography: paper.bib # Summary The impacts of economic shocks (caused by natural or technological disasters for -instance) often extend far beyond the cost of their local, direct -consequences, as the economic perturbations they cause propagate along supply -chains. Understanding the additional impacts and costs stemming from this -propagation is key to design efficient risk management policies. The interest is rising -for the evaluation of these "indirect risks" in the context of -climate change--which leads to an increase in the average risk of weather extremes +instance) often extend far beyond the cost of their local, direct consequences. +Part of these indirect consequences are caused by the propagation of the economic perturbations along supply chains. +Understanding the additional impacts and costs stemming from this propagation is +key to design efficient risk management policies. The interest is rising for the +evaluation of these "indirect risks" in the context of climate change--which +leads to an increase in the average risk of weather extremes [@lange-2020-projec-expos], and globalized-just-in-time production processes. Such evaluations rely on dynamic economic models that represent the interactions between multiple regions and sectors. Recent research in the field argues in favor of using more Agent-Based oriented model, associated with an increase in the complexity of the mechanisms represented [@coronese-2022-econom-impac]. However, the assumptions and hypotheses underlying these economic mechanisms -vary a lot, and sometime lack transparency, making it difficult to properly +vary a lot, and sometimes lack transparency, making it difficult to properly interpret and compare results across models, even more so when the code used is not published or undocumented. The Adaptive Regional Input-Output model (or ARIO) is an hybrid input-output / agent-based economic model, designed to compute indirect costs consequent to -economic shocks. Its first version dates back to 2008 and was originally developed to assess the indirect costs of natural disasters -[@hallegatte-2008-adapt-region]. ARIO is now a well-established and pivotal +economic shocks. Its first version dates back to 2008 and was originally +developed to assess the indirect costs of natural disasters +[@hallegatte-2008-adapt-region]. ARIO is now a well-established and a pivotal model in its field, has been used in multiple studies, and has seen several extensions or adaptations [@wu-2011-region-indir; @ranger-2010-asses-poten; @henriet-2012-firm-networ; @hallegatte-2013-model-role; @@ -51,14 +51,14 @@ extensions or adaptations [@wu-2011-region-indir; @ranger-2010-asses-poten; @wang-2020-econom-footp; @wang-2018-quant-spatial]. In ARIO, the economy is modelled as a set of economic sectors and regions, and -we call a specific (region,sector) couple an *industry*. Each industry produces +we call a specific (region, sector) couple an *industry*. Each industry produces a unique product which is assumed to be the same for all industries of the same sector. Each industry keeps an inventory of inputs it requires for production. Each industry answers a total demand consisting of the final demand (from households, public spendings and private investments) and of the intermediate demand (from other industries). An initial equilibrium state for the economy is built based on a multi-regional input-output table. The model can then describe -how the economic, as depicted, responds to a shock (or multiple ones). +how the economy, as depicted, responds to a shock (or multiple ones). `BoARIO` is an open-source Python package implementing the ARIO model. Its core purpose is to help support better accessibility, transparency, replicability and @@ -67,20 +67,19 @@ comparability in the field of indirect economic impacts modeling. # Statement of need Although the ARIO model has been used in multiple studies, and several extensions -exists, only a few implementation of the model or similar ones are openly available. +exists, only a few implementations of the model or similar ones are openly available. We found the following existing implementations: - - A python implementation of MRIA [@koks-2016-multir-impac], is available on the [personal GitHub repository of E. Koks](https://github.com/ElcoK/MRIA). - - [C. Colon repository](https://github.com/ccolon/disrupt-supply-chain-model/) holds a python implementation of Disrupt Supply Chain [@colon-2020-critic-analy]. - - A C++ implementation of the Acclimate model [@otto-2017-model-loss], is available [here](https://github.com/acclimate/acclimate). - - A Matlab implementation of C. Shughrue's model [@shughrue-2020-global-spread], is available on [his repository](https://github.com/chrisshughrue/GlobalUrbanCycloneImpactSimulation). - - The ARIO models version used in [@wang-2020-econom-footp, @guan-2020-global-suppl] are both available on [D. Wang personal repository](https://github.com/DaopingW/) + - A Python implementation of MRIA [@koks-2016-multir-impac]. + - A Python implementation of Disrupt Supply Chain [@colon-2020-critic-analy]. + - A C++ implementation of the Acclimate model [@otto-2017-model-loss]. + - A Matlab implementation of C. Shughrue's model [@shughrue-2020-global-spread]. + - The ARIO models version used in [@wang-2020-econom-footp, @guan-2020-global-suppl]. -We found that none of these implementation offers a comprehensive documentation, and are generally -specific to the case study there were used for. The purpose of the `BoARIO` package is to offer +We found that none of these implementations offer a comprehensive documentation, and are generally +specific to the case study they were used for. The purpose of the `BoARIO` package is to offer a generic, documented, easy to use, easy to extend, and replicability-oriented model for indirect impact assessment. - The `BoARIO` package allows to easily run simulations with the ARIO model, via simple steps: @@ -91,22 +90,23 @@ simple steps: The ARIO model relies on Multi-Regional Input-Output Tables (MRIOTs) to define the initial state of the economy. `BoARIO` was designed to be entirely agnostic of the MRIOT used, thanks to the `pymrio` package [@stadler2021_Pymrio]. This -aspect notably allows to fully benefit from the increasing number of such tables -are becoming available [@stadler18-exiob; @oecd-2021-oecd-inter; +aspect notably permits full benefit from the increasing availability of such tables [@stadler18-exiob; @oecd-2021-oecd-inter; @thissen-2018-eureg; @lenzen-2012-mappin-struc]. -The package allows for different shocking events to be defined (shock on demand, -shock on production, shock on both, shock involving reconstruction or not, etc). -As such, different types of case-study can be conducted (at different scope, for +The package allows for different shocking events to be defined (currently, +shocks on production or shocks on both production and demand, by including a +demand stemming from the reconstruction effort, the inclusion of shocks on demand only +and other types of shock will be added in future versions). +As such, different types of case studies can be conducted (at different scope, for multiple or singular events). Users benefit from a precise control on aspects such as the distribution of the impact towards the different sectors and -regions, the recovery of from the impact, etc. but also from the default -modeling choices common in the corresponding literature. The rationale for detailed +regions, the recovery from the impact, and also from the default +modeling choices common in the corresponding literature. The rationale for the detailed configuration of the model is "allowing for, but not require". Simulations log the evolution of each variable of interest (production, production capacity, intermediate demand, reconstruction demand, etc.) at each -step and for each industry, in `pandas DataFrames` objects, allowing in depth +step and for each industry, in `pandas DataFrame` objects, allowing in depth descriptions and understanding of the economic responses. The package can be used "live", e.g. in a Jupyter Notebook, as well as in large simulation pipelines, for instance using the `Snakemake` package from @koester-2012-snakem-scalab[^1]. @@ -119,24 +119,15 @@ better understand the dynamics associated with the propagation of economic impacts, for more applied-oriented case studies in risk management, or simply as a pedagogical tool to introduce the indirect impact modeling field. -The Python implementation, accompanied by the extensive [online +The Python implementation, accompanied by the [online documentation](https://spjuhel.github.io/BoARIO/) (where a more in depth description is available), offers an accessible interface for researchers with limited programming knowledge. It also aims to be modular and extensible to include additional economic mechanisms in future versions. Finally, its API aims -at making it inter-operable with other modeling software: for instance the `CLIMADA` +at making it interoperable with other modeling software: for instance the `CLIMADA` platform [@gabriela-aznar-siguan-2023-8383171] to which `BoARIO` is in the process of being integrated. -`BoARIO` is at the core of its author's PhD thesis, and was notably used in -[@juhel-2023-robus], recently submitted to Risk Analysis. Other notable ongoing projects, -are: -- an evaluation of the indirect costs of future floods at the global scope and -comparing its to similar studies using the Acclimate and MRIA models -[@willner-2018-global-econom; @koks-2019-macroec-impac] -- a study on the compounding effect of indirect impacts from multiple events. -- a technical paper on the coupling of `BoARIO` with the `CLIMADA` platform. - # Status `BoARIO` is released under the open-source GPL-3.0 license and is currently @@ -144,15 +135,11 @@ developed by Samuel Juhel. The core of its development was made over the course of a PhD at CIRED and LMD, under the supervision of Vincent Viguié and Fabio D'Andrea, and funded by ADEME (the french agency for transition). -`BoARIO` can be installed from pip using: +`BoARIO` can be installed from PyPi or Conda-Forge using: pip install boario -Integration tests can be run using `pytest` - -Although its current version is fully operational, further improvements, notably -the implementation of additional economic mechanisms or variations of existing -ones are already planned. + conda install -c conda-forge boario # Acknowledgements @@ -160,8 +147,7 @@ I wish to acknowledge Vincent Viguié and Fabio D'Andrea for their support in th development of `BoARIO` during his PhD, as well as Adrien Delahais for his feedbacks on the model use. I also want to thank David N. Bresch for indirectly inspiring me to develop a package for more than just my personal use, and -Alessio Ciullo, for its interest in the package, its valuable suggestions and +Alessio Ciullo, for their interest and valuable suggestions as well as the work done to integrate `BoARIO` to `CLIMADA`. - # References diff --git a/pyproject.toml b/pyproject.toml index e199129..888fae9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "boario" -version = "0.5.9" +version = "0.5.10" description = "BoARIO : The Adaptative Regional Input Output model in python." authors = ["Samuel Juhel "] license = "GNU General Public License v3 or later (GPLv3+)" diff --git a/tests/test_events.py b/tests/test_events.py index 6b69cee..683cbc3 100644 --- a/tests/test_events.py +++ b/tests/test_events.py @@ -20,6 +20,7 @@ EventKapitalRecover, ) # A class defining a shock on capital +boario.disable_console_logging() @pytest.fixture def test_mrio(): diff --git a/tests/test_models.py b/tests/test_models.py index 87f4c80..9d90c6f 100644 --- a/tests/test_models.py +++ b/tests/test_models.py @@ -11,8 +11,10 @@ import numpy.testing as nptest # import the different classes +import boario from boario.utils.recovery_functions import * +boario.disable_console_logging() @pytest.fixture def test_mrio(): diff --git a/tests/test_simulation.py b/tests/test_simulation.py index daa70cb..3d68b08 100644 --- a/tests/test_simulation.py +++ b/tests/test_simulation.py @@ -21,6 +21,7 @@ ) # A class defining a shock on capital from boario.utils.recovery_functions import * +boario.disable_console_logging() @pytest.fixture def test_mrio():