Merge pull request #127 from spjuhel/develop

Update from develop
spjuhel · Jul 12, 2024 · ecd7baf · ecd7baf
2 parents 2e90e58 + 163a481
commit ecd7baf
Show file tree

Hide file tree

Showing 7 changed files with 114 additions and 60 deletions.
diff --git a/CITATION.cff b/CITATION.cff
@@ -0,0 +1,11 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+- family-names: "Juhel"
+  given-names: "Samuel"
+  orcid: "https://orcid.org/0000-0001-8801-3890"
+title: "BoARIO"
+version: 0.5.10
+doi: 10.5281/zenodo.11580697
+date-released: 2024-06-11
+url: "https://github.com/spjuhel/BoARIO"
diff --git a/boario/event.py b/boario/event.py
@@ -555,6 +555,64 @@ def _from_scalar_regions_sectors(
         )
 
     @classmethod
+    def from_scalar_regions_sectors(
+        cls,
+        impact: ScalarImpact,
+        *,
+        regions: RegionsList,
+        sectors: SectorsList,
+        impact_regional_distrib: Optional[npt.ArrayLike] = None,
+        impact_sectoral_distrib: Optional[Union[str, npt.ArrayLike]] = None,
+        occurrence: int = 1,
+        duration: int = 1,
+        name: Optional[str] = None,
+        **kwargs,
+    ) -> Event:
+        """Creates an Event from a scalar, a list of regions and a list of sectors affected.
+
+        Parameters
+        ----------
+        impact : ScalarImpact
+            The scalar impact.
+        regions : RegionsList
+            The list of regions affected.
+        sectors : SectorsList
+            The list of sectors affected in each region.
+        impact_regional_distrib : Optional[npt.ArrayLike], optional
+            A vector of equal size to the list of regions affected, stating the
+            share of the impact each industry should receive. Defaults to None.
+        impact_sectoral_distrib : Optional[Union[str, npt.ArrayLike]], optional
+            Either:
+
+            * ``\"gdp\"``, the impact is then distributed using the gross value added of each sector as a weight.
+            * A vector of equal size to the list of sectors affected, stating the share of the impact each industry should receive. Defaults to None.
+
+        occurrence : int, optional
+            The ordinal of occurrence of the event (requires to be > 0). Defaults to 1.
+        duration : int, optional
+            The duration of the event (entire impact applied during this number of steps). Defaults to 1.
+        name : Optional[str], optional
+            A possible name for the event, for convenience. Defaults to None.
+        **kwargs :
+            Keyword arguments
+            Other keyword arguments to pass to the instantiate method (depends on the type of event)
+
+        Raises
+        ------
+        ValueError
+            Raise if Impact is null, if len(regions) or len(sectors) < 1,
+
+        Returns
+        -------
+        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.")
+
     def _build_industries_idx(cls, regions: RegionsList, sectors: SectorsList):
         # TODO: Move this in utils?
         if isinstance(regions, str):

diff --git 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/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.bib b/paper.bib
@@ -36,11 +36,9 @@ @article{coronese-2022-econom-impac
   Title = {Economic Impacts of Natural Hazards and Complexity Science: a Critical Review},
   Author = {Matteo Coronese and Davide Luzzati},
   DOI = {10.2139/ssrn.4101276},
-  Journal = {SSRN Electronic Journal},
-  Number = {nil},
-  Pages = {nil},
+  Journal = {LEM Working Paper},
+  number = {2022/13},
   URL = {http://dx.doi.org/10.2139/ssrn.4101276},
-  Volume = {nil},
   Year = {2022},
   date_added = {Thu Nov 23 17:17:22 2023},
 }
@@ -109,7 +107,6 @@ @article{lange-2020-projec-expos
   DOI = {10.1029/2020ef001616},
   JournalTitle = {Earth's Future},
   Number = {12},
-  Pages = {nil},
   URL = {https://doi.org/10.1029/2020ef001616},
   Volume = {8},
   Year = {2020},
@@ -140,13 +137,11 @@ @software{gabriela-aznar-siguan-2023-8383171
                   Nicolas Colombi and
                   wjan262 and
                   Simona Meiler and
-                  leonie-villiger and
-                  climada-jenkins and
+                  Leonie Villiger and
                   Rachel\_B and
-                  raphael-portmann and
-                  veronicabozzini and
-                  DarioStocker and
-                  scem},
+                  Raphael Portmann and
+                  Veronica Bozzini and
+                  Dario Stocker},
   title        = {CLIMADA-project/climada\_python: v4.0.1},
   month        = sep,
   year         = 2023,
@@ -157,7 +152,7 @@ @software{gabriela-aznar-siguan-2023-8383171
 }
 
 @article{guan-2020-global-suppl,
-  Title = {Global Supply-Chain Effects of Covid-19 Control Measures},
+  Title = {Global Supply-Chain Effects of {COVID}-19 Control Measures},
   Author = { Dabo Guan and Daoping Wang and Stephane Hallegatte and Steven J. Davis and Jingwen Huo and Shuping Li and Yangchun Bai and Tianyang Lei and Qianyu Xue and D'Maris Coffman and Danyang Cheng and Peipei Chen and Xi Liang and Bing Xu and Xiaosheng Lu and Shouyang Wang and Klaus Hubacek and Peng Gong },
   DOI = {10.1038/s41562-020-0896-8},
   JournalTitle = {Nature Human Behaviour},
@@ -170,7 +165,7 @@ @article{guan-2020-global-suppl
 }
 
 @article{ranger-2010-asses-poten,
-  Title = {An Assessment of the Potential Impact of Climate Change on Flood Risk in Mumbai},
+  Title = {An Assessment of the Potential Impact of Climate Change on Flood Risk in {M}umbai},
   Author = { Nicola Ranger and St{\'e}phane Hallegatte and Sumana Bhattacharya and Murthy Bachu and Satya Priya and K. Dhore and Farhat Rafique and P. Mathur and Nicolas Naville and Fanny Henriet and Celine Herweijer and Sanjib Pohit and Jan Corfee-Morlot },
   DOI = {10.1007/s10584-010-9979-2},
   JournalTitle = {Climatic Change},
@@ -196,7 +191,7 @@ @article{henriet-2012-firm-networ
 }
 
 @article{hallegatte-2010-asses-climat,
-  Title = {Assessing Climate Change Impacts, Sea Level Rise and Storm Surge Risk in Port Cities: a Case Study on Copenhagen},
+  Title = {Assessing Climate Change Impacts, Sea Level Rise and Storm Surge Risk in Port Cities: a Case Study on {C}openhagen},
   Author = {St{\'e}phane Hallegatte and Nicola Ranger and Olivier Mestre and Patrice Dumas and Jan Corfee-Morlot and Celine Herweijer and Robert Muir Wood},
   DOI = {10.1007/s10584-010-9978-3},
   JournalTitle = {Climatic Change},
@@ -209,7 +204,7 @@ @article{hallegatte-2010-asses-climat
 }
 
 @article{hallegatte-2008-adapt-region,
-  Title = {An Adaptive Regional Input-Output Model and Its Application To the Assessment of the Economic Cost of Katrina},
+  Title = {An Adaptive Regional Input-Output Model and Its Application To the Assessment of the Economic Cost of {K}atrina},
   Author = {St{\'e}phane Hallegatte},
   DOI = {10.1111/j.1539-6924.2008.01046.x},
   JournalTitle = {Risk Analysis},
@@ -235,7 +230,7 @@ @article{hallegatte-2013-model-role
 }
 
 @article{wu-2011-region-indir,
-  Title = {Regional Indirect Economic Impact Evaluation of the 2008 Wenchuan Earthquake},
+  Title = {Regional Indirect Economic Impact Evaluation of the 2008 {Wenchuan} Earthquake},
   Author = {Jidong Wu and Ning Li and St{\'e}phane Hallegatte and Peijun Shi and Aijun Hu and Xueqin Liu},
   DOI = {10.1007/s12665-011-1078-9},
   JournalTitle = {Environmental Earth Sciences},
@@ -294,7 +289,7 @@ @article{zhang-2018-analy-econom
 }
 
 @article{wang-2020-econom-footp,
-  Title = {Economic Footprint of California Wildfires in 2018},
+  Title = {Economic Footprint of {California} Wildfires in 2018},
   Author = { Daoping Wang and Dabo Guan and Shupeng Zhu and Michael Mac Kinnon and Guannan Geng and Qiang Zhang and Heran Zheng and Tianyang Lei and Shuai Shao and Peng Gong and Steven J. Davis },
   DOI = {10.1038/s41893-020-00646-7},
   JournalTitle = {Nature Sustainability},
@@ -307,7 +302,7 @@ @article{wang-2020-econom-footp
 }
 
 @article{wang-2018-quant-spatial,
-  Title = {Quantifying the Spatial Ripple Effect of the Bohai Sea Ice Disaster in the Winter of 2009/2010 in 31 Provinces of China},
+  Title = {Quantifying the Spatial Ripple Effect of the {B}ohai Sea Ice Disaster in the Winter of 2009/2010 in 31 Provinces of {C}hina},
   Author = {Cailin Wang and Jidong Wu and Xin He and Mengqi Ye and Yu Liu},
   DOI = {10.1080/19475705.2018.1489312},
   JournalTitle = {Geomatics, Natural Hazards and Risk},
@@ -376,9 +371,6 @@ @article{thissen-2018-eureg
   title =        {Euregio: the Construction of a Global Io Database With
                   Regional Detail for Europe for 2000-2010},
   journal =      {SSRN Electronic Journal},
-  volume =       {nil},
-  number =       {nil},
-  pages =        {nil},
   year =         2018,
   doi =          {10.2139/ssrn.3285818},
   url =          {http://dx.doi.org/10.2139/ssrn.3285818},
@@ -416,7 +408,6 @@ @article{otto-2017-model-loss
   Author = {C. Otto and S.N. Willner and L. Wenz and K. Frieler and A. Levermann},
   DOI = {10.1016/j.jedc.2017.08.001},
   JournalTitle = {Journal of Economic Dynamics and Control},
-  Number = {nil},
   Pages = {232--269},
   URL = {http://dx.doi.org/10.1016/j.jedc.2017.08.001},
   Volume = {83},

diff --git 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
@@ -35,15 +34,15 @@ 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
+[@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;
@@ -52,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
@@ -68,16 +67,16 @@ 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
+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.
 
@@ -91,24 +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 (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-study can be conducted (at different scope, for
+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].
@@ -126,44 +124,30 @@ 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], in review process. Other notable ongoing projects,
-are:
-- an evaluation of the indirect costs of future floods at the global scope and
-comparing its results 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,
-using time-series of tropical cyclones generated with `CLIMADA`, and comparing
-the effect of considering events as isolated or consecutive.
-
 # Status
 
 `BoARIO` is released under the open-source GPL-3.0 license and is currently
 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).
+D'Andrea, and funded by ADEME (the French agency for transition).
 
-`BoARIO` can be installed from pip or conda using:
+`BoARIO` can be installed from PyPi or Conda-Forge using:
 
     pip install boario
 
     conda install -c conda-forge boario
 
-Integration tests can be run using `pytest`.
-
-Further improvements, notably the implementation of additional economic mechanisms or variations of existing ones are already planned.
-
 # Acknowledgements
 
 I wish to acknowledge Vincent Viguié and Fabio D'Andrea for their support in the
 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
@@ -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 <pro@sjuhel.org>"]
 license = "GNU General Public License v3 or later (GPLv3+)"