update

.github/workflows/ci_template.yml

@@ -16,6 +16,27 @@ on:
         type: string
 
 jobs:
+  paper:
+    runs-on: ubuntu-latest
+    needs: publish-PyPI
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Build draft PDF
+        uses: openjournals/openjournals-draft-action@master
+        with:
+          journal: joss
+          # This should be the path to the paper within your repo.
+          paper-path: docs/paper/paper.md
+      - name: Upload
+        uses: actions/upload-artifact@v4
+        with:
+          name: paper
+          # This is the output path where Pandoc will write the compiled
+          # PDF. Note, this should be the same directory as the input
+          # paper.md
+          path: docs/paper/paper.pdf
+
   test:
     runs-on: ${{ matrix.os }}
     strategy:

docs/index.md

@@ -6,7 +6,7 @@ derive a synthetic urban drainage network anywhere in the world.
 ## Table of contents
 <!-- markdownlint-disable MD007 -->
 - [Home](index.md)
-- [About](./paper/paper.md)
+- [About](./paper/paper.pdf)
 - [Quickstart](quickstart.md)
 - Guides:
     - [Configuration file](config_guide.md)

docs/paper/paper.bib

@@ -285,3 +285,45 @@ @ARTICLE{Khurelbaatar2021-sp
   year      =  2021,
   copyright = "https://creativecommons.org/licenses/by/4.0/"
 }
+
+@misc{VIDA2023,
+author = {VIDA},
+title = {{Google-Microsoft Open Buildings}},
+url = {https://beta.source.coop/repositories/vida/google-microsoft-open-buildings},
+urldate = {2024-07-30},
+year = {2023}
+}
+
+@article{Crippen2016,
+abstract = {Abstract. NASADEM is a near-global elevation model that is being produced primarily by completely reprocessing the Shuttle Radar Topography Mission (SRTM) radar data and then merging it with refined ASTER GDEM elevations. The new and improved SRTM elevations in NASADEM result from better vertical control of each SRTM data swath via reference to ICESat elevations and from SRTM void reductions using advanced interferometric unwrapping algorithms. Remnant voids will be filled primarily by GDEM3, but with reduction of GDEM glitches (mostly related to clouds) and therefore with only minor need for secondary sources of fill.},
+author = {Crippen, R. and Buckley, S. and Agram, P. and Belz, E. and Gurrola, E. and Hensley, S. and Kobrick, M. and Lavalle, M. and Martin, J. and Neumann, M. and Nguyen, Q. and Rosen, P. and Shimada, J. and Simard, M. and Tung, W.},
+doi = {10.5194/isprs-archives-XLI-B4-125-2016},
+issn = {2194-9034},
+journal = {The International Archives of the Photogrammetry, Remote Sensing and Spatial Information Sciences},
+month = {jun},
+pages = {125--128},
+title = {{NASADEM GLOBAL ELEVATION MODEL: METHODS AND PROGRESS}},
+url = {https://isprs-archives.copernicus.org/articles/XLI-B4/125/2016/},
+volume = {XLI-B4},
+year = {2016}
+}
+
+@article{Boeing2017,
+author = {Boeing, Geoff},
+doi = {10.1016/j.compenvurbsys.2017.05.004},
+issn = {01989715},
+journal = {Computers, Environment and Urban Systems},
+month = {sep},
+pages = {126--139},
+title = {{OSMnx: New methods for acquiring, constructing, analyzing, and visualizing complex street networks}},
+url = {https://linkinghub.elsevier.com/retrieve/pii/S0198971516303970},
+volume = {65},
+year = {2017}
+}
+
+ @misc{OpenStreetMap,
+   author = {{OpenStreetMap contributors}},
+   title = {{Planet dump retrieved from https://planet.osm.org }},
+   howpublished = "\url{ https://www.openstreetmap.org }",
+   year = {2017},
+ }

docs/paper/paper.md

@@ -30,13 +30,34 @@ bibliography: paper.bib
 
 ---
 
-# Summary
+## Summary
 
 Urban drainage network models (UDMs) are useful for a variety of purposes, most notably simulating and alleviating pluvial flooding. Despite the clear usefulness of UDMs, they are often not used owing to the difficulty and expense of creating them. This creates a significant gap for users attempting to generate UDMs if they are not able to perform an expensive underground survey. A variety of literature exists to derive such UDMs from GIS data, producing hydraulically feasible models that closely approximate real-world systems [@Blumensaat2012-hd;@Chahinian2019-lg;@Reyes-Silva2022-pr]. We identify some key limitations of these approaches, most notably the lack of automatic data acquisition and preprocessing, that all approaches are closed-source to date, and that a key feature of such an approach should be to facilitate extension and customisation.
 
-# Statement of need
+## Statement of need
+
+SWMManywhere is an open-source Python package designed for the global synthesis of urban drainage networks. SWMManywhere integrates publicly available geospatial data and automates data acquisition and preprocessing, reducing the technical burden on users. The CLI offers a flexible workflow, providing an accessible entry point to using and customising synthesis. Its parameterized design enables detailed sensitivity analyses, allowing users to understand and manage uncertainties inherent in urban drainage modelling [@Dobson2024-dv]. By emphasizing user control, SWMManywhere allows tuning of outputs with parameters to meet local requirements, making it adaptable to a wide range of scenarios. Designed for both researchers and practitioners in urban water management, SWMManywhere responds to the limitations of existing methods by providing an end-to-end, open-source, and customisable solution.
+
+### Data
+
+A variety of datasets were selected to enable SWMManywhere to be applied globally. 
+
+| Data Source | Description | Reference |
+|-------------|-------------| --------- |
+| **OpenStreetMap (OSM)** | Provides global street and river data, used to define potential pipe locations and outfall points for drainage networks. | [@Boeing2017;@OpenStreetMap] |
+| **Google-Microsoft Open Buildings** | A dataset of global building footprints, used for estimating impervious surfaces essential for runoff calculations. | [@VIDA2023] |
+| **NASADEM** | Provides 30m resolution global digital elevation model (DEM) data to support sub-catchment delineation and slope calculation. | [@Crippen2016] |
+
+These datasets are global in their coverage, and we consider them of sufficient quality in locations that we have tested [@Dobson24-dv], however, we urge users to check data in their specific case study.
+
+### Approach and customisation
+
+The core task in SWMManywhere is to begin with a 'starting graph' (e.g., an OSM street graph), refine this graph first into manhole locations and potential pipe locations, eliminate pipes from unnecessary locations, and then dimension the resulting pipe network so that it can be simulated in a software such as [SWMM](https://www.epa.gov/sites/default/files/2019-02/documents/epaswmm5_1_manual_master_8-2-15.pdf). These operations take place in an iterative approach, where each function takes a graph, and returns the transformed graph, thus each operation is referred to as a 'graph function'. The use of graph functions in SWMManywhere enables modular packaging of functions, easy customisation of the approach (e.g., by adding/removing/reordering graph functions), and explicit definition of parameters for each graph function. Explanations for making these customisations are available in the [documentation](https://imperialcollegelondon.github.io/SWMManywhere/). Ultimately, this customisability facilitates exploring uncertainty in urban drainage modelling in a way that reflects not just the model itself but the model creation process, as is demonstrated in [@Dobson2024-dv].
+
+We visualise the example from the [extended demonstration](https://imperialcollegelondon.github.io/SWMManywhere/notebooks/extended_demo/) in the documentation to illustrate how changing relatively few parameter values in a strategic way can dramatically change the nature of the synthesised network \autoref{fig:fig1}.
+
+![Figure 1: Example of output customisation with SWMManywhere. Black nodes are manholes, black lines are pipes, red nodes are outfalls.\label{fig:fig1}](extended_demo.svg)
 
-`SWMManywhere` is an open-source Python package designed for the global synthesis of urban drainage networks. SWMManywhere integrates publicly available geospatial data and automates data acquisition and preprocessing, reducing the technical burden on users. The CLI offers a flexible workflow, providing an accessible entry point to using and customising synthesis. Its parameterized design enables detailed sensitivity analyses, allowing users to understand and manage uncertainties inherent in urban drainage modelling [@Dobson2024-dv]. By emphasizing user control, SWMManywhere allows tuning of outputs with parameters to meet local requirements, making it adaptable to a wide range of scenarios. Designed for both researchers and practitioners in urban water management, SWMManywhere responds to the limitations of existing methods by providing an end-to-end, open-source, and customisable solution.
 
 ## Outlook
 

mkdocs.yml

@@ -41,7 +41,7 @@ extra_javascript:
 
 nav:
   - Home: index.md
-  - About: ./paper/paper.md
+  - About: ./paper/paper.pdf
   - Quickstart: quickstart.md
   - Guides:
     - Configuration guide: config_guide.md