Merge pull request #14 from OceanParcels/documentation-start

erikvansebille · web-flow · commit f3ea956ebe43 · 2024-05-03T13:45:34.000+02:00
Adding documentation
diff --git a/.gitignore b/.gitignore
@@ -4,3 +4,5 @@ input_data/
 **.pyc**
 **.nc
 **.zarr
+docs/_build/*
+docs/_downloads
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,14 @@
+version: 2
+build:
+  os: ubuntu-22.04
+  tools:
+    python: mambaforge-22.9
+  jobs:
+    pre_build:
+      - sphinx-build -b linkcheck docs/ _build/linkcheck
+
+sphinx:
+  configuration: docs/conf.py
+
+conda:
+  environment: docs/environment_docs.yml
diff --git a/README.md b/README.md
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/_static/plasticparcelslogo.png b/docs/_static/plasticparcelslogo.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -0,0 +1,121 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+import datetime
+import inspect
+import os
+import sys
+import warnings
+
+project = 'PlasticParcels'
+copyright = f'{datetime.datetime.now().year}, The OceanParcels Team'
+author = 'The OceanParcels Team'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = []
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'pydata_sphinx_theme'
+html_static_path = ['_static']
+
+html_theme_options = {
+    "logo": {
+        "image_light": "plasticparcelslogo.png",
+        "image_dark": "plasticparcelslogo-inverted.png",  # TODO create this
+    },
+    # "use_edit_page_button": True,
+    "github_url": "https://github.com/OceanParcels/plasticparcels",
+    "icon_links": [
+        {
+            "name": "Conda Forge",
+            "url": "https://anaconda.org/conda-forge/plasticparcels",  # required
+            "icon": "fa-solid fa-box",
+            "type": "fontawesome",
+        }
+    ]
+}
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.todo',
+    "sphinx.ext.linkcode",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.napoleon",
+    "myst_parser",
+    "nbsphinx",
+    "numpydoc",
+]
+
+myst_enable_extensions = ["dollarmath", "amsmath"]
+
+# based on pandas doc/source/conf.py
+def linkcode_resolve(domain, info):
+    """Determine the URL corresponding to Python object."""
+    if domain != "py":
+        return None
+
+    modname = info["module"]
+    fullname = info["fullname"]
+
+    submod = sys.modules.get(modname)
+    if submod is None:
+        return None
+
+    obj = submod
+    for part in fullname.split("."):
+        try:
+            with warnings.catch_warnings():
+                # Accessing deprecated objects will generate noisy warnings
+                warnings.simplefilter("ignore", FutureWarning)
+                obj = getattr(obj, part)
+        except AttributeError:
+            return None
+
+    try:
+        fn = inspect.getsourcefile(inspect.unwrap(obj))
+    except TypeError:
+        try:  # property
+            fn = inspect.getsourcefile(inspect.unwrap(obj.fget))
+        except (AttributeError, TypeError):
+            fn = None
+    if not fn:
+        return None
+
+    try:
+        source, lineno = inspect.getsourcelines(obj)
+    except TypeError:
+        try:  # property
+            source, lineno = inspect.getsourcelines(obj.fget)
+        except (AttributeError, TypeError):
+            lineno = None
+    except OSError:
+        lineno = None
+
+    if lineno:
+        linespec = f"#L{lineno}-L{lineno + len(source) - 1}"
+    else:
+        linespec = ""
+
+    fn = os.path.relpath(fn, start=os.path.dirname(parcels.__file__))
+
+    if "-" in parcels.__version__:
+        return f"https://github.com/OceanParcels/plasticparcels/blob/master/parcels/{fn}{linespec}"
+    else:
+        return (
+            f"https://github.com/OceanParcels/plasticparcels/blob/"
+            f"{parcels.__version__}/parcels/{fn}{linespec}"
+        )
diff --git a/docs/environment_docs.yml b/docs/environment_docs.yml
@@ -0,0 +1,33 @@
+name: plasticparcels
+channels:
+  - conda-forge
+dependencies:
+  - python>=3.8
+  - parcels>=3.0.2
+  - shapely
+  - geopandas
+
+
+  # Formatting
+  - black
+  - isort
+
+  # Testing
+  - pytest
+  - pytest-html
+  - coverage
+
+  # Linting
+  - flake8>=2.1.0
+  - pre_commit
+  - pydocstyle
+
+  # Docs
+  - ipython
+  - numpydoc
+  - nbsphinx
+  - sphinx<6
+  - pandoc>1.12.1,<3
+  - pydata-sphinx-theme
+  - sphinx-autobuild
+  - myst-parser
diff --git a/docs/examples.rst b/docs/examples.rst
@@ -0,0 +1,12 @@
+Examples
+========
+
+PlasticParcels has a few example notebooks, see below.
+
+
+
+.. nbgallery::
+   :caption: Running simulations
+   :name: running-simulations
+
+   examples/example_Italy_coast.ipynb
diff --git a/docs/examples/example_Italy_coast.ipynb b/docs/examples/example_Italy_coast.ipynb
@@ -4,8 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# PlasticParcels Example\n",
-    "## The pathways and fate of Italian coastal plastic pollution\n",
+    "# The pathways and fate of Italian coastal plastic pollution\n",
     "In this example, we will use `plasticparcels` to run a basic simulation of microplastic pollution along the Italian coastline."
    ]
   },
diff --git a/docs/index.rst b/docs/index.rst
@@ -0,0 +1,22 @@
+.. plasticparcels documentation master file, created by
+   sphinx-quickstart on Fri May  3 09:55:52 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+PlasticParcels documentation
+============================
+
+Welcome to the documentation of PlasticParcels.
+
+``plasticparcels`` is a python package for simulating the transport and dispersion of plastics in the ocean. The tool is based on the ``parcels`` computational Lagrangian ocean analysis framework, providing a modular and customisable collection of methods, notebooks, and tutorials for advecting virtual plastic particles with a wide range of physical properties.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+
+   Home <self>
+   Examples <examples>
+   Physics kernels <physicskernels>
+   Plastic initialisation maps <initialisationmaps>
+   OceanParcels website <https://oceanparcels.org/>
diff --git a/docs/initialisationmaps.md b/docs/initialisationmaps.md
@@ -0,0 +1,71 @@
+# Description of algorithms for particle initialisation maps
+Included in the `PlasticParcels` package are four algorithms to create particle initialisation maps, which represent best estimates for plastic pollution emissions along with the current state of plastic concentrations in our oceans globally. Below we describe each of these algorithms. Each initialisation map, however, requires that particles be placed in ocean grid cells, hence we provide algorithms to generate these initialisation maps, rather than the maps themselves. These maps are land mask dependent, we include scripts to generate a land mask file, as well as a coast mask file, if the model does not provide one.
+
+
+### Coastal mismanaged plastic waste emissions <a name="coastalrelease"></a>
+To generate a particle initialisation map of plastic pollution that enters the ocean from coastal communities, we use a global mismanaged plastic waste dataset provided per country [@Jambeck2015](http://dx.doi.org/10.1126/science.1260352). Specifically, for each country, we use the 'Mismanaged plastic waste [kg/person/day]' data to identify the amount of plastic entering the ocean along a coastline. The algorithm is as follows:
+
+
+**Coastal emissions initialisation map algorithm**
+1. Load (or generate) the coast mask file from the selected ocean model.
+2. Load the Natural Earth country boundaries shapefile at 1:50m resolution [@NaturalEarth] **(add reference to .bib)**.
+3. Load the Gridded Population of the World dataset [@NASA] **(add reference to .bib)**.
+4. For each country in the country boundaries shapefile:
+    1. Extract the coordinates of the vertices of the country border (border vertices).
+    2. ~~Compute the distance between each border vertex, and every coastal model grid-cell center.~~ <mark>Remove this?</mark>
+    3. Create a list of coastal model grid-cells that are within $r$ km of a border vertex.
+    4. For each identified coastal model grid-cell, identify the maximum population density from the GPW data within a specified distance $\phi$ (in degrees) north/south or east/west from the coastal model grid-cell center.
+    5. Create an array with the coastal model grid-cell and its associated area, the country name, continent name, region name, and subregion name from the shapefile, and the identified population density.
+5. Combine all entries generated in Step 4.i. into one array.
+6. Load the global mismanaged plastic waste data [@Jambeck2015](http://dx.doi.org/10.1126/science.1260352), and join it to the array generated in Step 5, by 'left joining' on country name$`^*`$. Create an additional column 'MPW_cell', mismanaged plastic waste across the grid cell by multiplying the mismanaged plastic waste per kilogram per day with the population density and the grid-cell area.
+7. Save the data into a `.csv` file, to be read and processed by `PlasticParcels`.
+
+
+$`^*`$We pre-process the country names in the [@Jambeck2015](http://dx.doi.org/10.1126/science.1260352) data to account for small differences in the naming conventions of each country. Here, we use $`r=50`$ km, and $`\phi`$ is chosen as the model grid width in degrees. A sample plot of the initialisation map is shown in Figure X **add link**.
+
+### Riverine mismanaged plastic waste emissions <a name="riverrelease"></a>
+To generate a particle initialisation map of plastic pollution that enters the ocean from river sources, we use a global riverine input dataset [@Meijer2021](http://dx.doi.org/10.1126/sciadv.aaz5803). This dataset is provided in the form of a shapefile, providing a location (latitude and longitude) and amount of plastic emissions (in units of tonnes per year). The algorithm is as follows:
+
+**Riverine emissions initialisation map algorithm**
+1. Load (or generate) the coast mask file from the selected ocean model.
+2. Load the Natural Earth country boundaries shapefile at 1:50m resolution [@NaturalEarth] **(add reference to .bib)**, and extract the coordinates of the vertices of every country border.
+3. Load the riverine emissions shapefile.
+4. For each location in the riverine emissions shapefile:
+    1. Compute the distance from the emission source to the center of every coastal grid cell, and identify the closest coastal grid cell.
+    2. Compute the distance from the emission source to every country border point, and identify the closest country border point.
+    3. Create an array with the coastal model grid-cell, the country name, continent name, region name, and subregion name of the closest border point from the Natural Earth shapefile, and the associated emissions amount.
+5. Save the data into a `.csv` file, to be read and processed by `PlasticParcels`.
+
+
+### Open-sea fishing-related plastic emissions <a name="fishingrelease"></a>
+To generate a particle initialisation map of plastic pollution emitted into the ocean from fishing-related activities, we use the global fishing watch dataset, first described in [@Kroodsma2018](http://dx.doi.org/10.1126/science.aao5646). Assuming plastic emissions from fishing activity is proportional to the amount of fishing hours in a given location, we generate a fishing-related plastic emissions initialisation map using the following algorithm:
+
+**Fishing-related emissions initialisation map algorithm**
+**(currently we store as monthly, to discuss what we should do, an average over the months? keep the seasonality? etc.)**
+1. Load the global fishing watch dataset.
+2. Aggregate the dataset by summing the fishing hours over the latitude, longitude, flag, geartype, and date columns, creating a daily dataset.
+3. Create a new column containing the month and year of each row, and again aggregate over all columns, replacing the date with the month and year column.
+4. Load the Natural Earth country boundaries shapefile at 1:50m resolution [@NaturalEarth] **(add reference to .bib)**, and extract a unique list of country name, continent name, region name, subregion name, country name, and country flag (using the ISO standard, or if this is missing/invalid, using the SU_A3 column).
+5. Join the country information dataset from Step 4) onto the aggregated dataset from Step 3, by 'left joining' on the flag columns.
+6. Load (or generate) the coast mask file from the selected ocean model.
+7. Find the closest ocean grid cell for each entry in the aggregated dataset from Step 5 using a KD-Tree approach.
+8. Aggregate the data by summing the fishing hours over the following columns: country name, continent name, flag, gear type, date (month and year), ocean grid cell.
+9. Save the data into a `.csv` file, to be read and processed by `PlasticParcels`.
+
+
+
+### Current global ocean plastic concentrations <a name="staterelease"></a>
+**TODO once implemented [@Kaandorp2023](http://dx.doi.org/10.1038/s41561-023-01216-0)**
+
+
+
+![Particle initialisations maps based on a) current global surface concentrations, b) coastal plastic emissions, c) river plastic emissions, d) fishing activity plastic emissions.](paper/initialisation_maps.png){width=80%}
+
+
+
+TODO:
+1. ~~change references to DOI Links~~ -- add links to non-published papers
+2. Update algorithms to be clearer
+3. Include additional kernels explanations
+4. Include release dataset explanations that are missing
+5. Include installation instructions
diff --git a/docs/make.bat b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/physicskernels.md b/docs/physicskernels.md
