Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/GEUS-Glaciology-and-Climate/freshwater

Greenland liquid water runoff from 1958 through 2019
https://github.com/GEUS-Glaciology-and-Climate/freshwater

grass-gis greenland org-mode scientific-workflows water

Last synced: 3 months ago
JSON representation

Greenland liquid water runoff from 1958 through 2019

Awesome Lists containing this project

README

        

* Table of contents :toc_5:noexport:
- [[#greenland-liquid-water-discharge-from-1950-through-2021][Greenland liquid water discharge from 1950 through 2021]]
- [[#updates-since-last-publication][Updates since last publication]]
- [[#v-2023][v 2023]]
- [[#v-2022-10][v 2022-10]]
- [[#v-2022-08][v 2022-08]]
- [[#warning][WARNING]]
- [[#related-work][Related Work]]
- [[#citation][Citation]]
- [[#funding][Funding]]
- [[#accessing-this-data][Accessing this data]]
- [[#introduction][Introduction]]
- [[#database-format][Database Format]]
- [[#notes][Notes]]
- [[#requirements][Requirements]]
- [[#examples][Examples]]
- [[#command-line-interface][Command line interface]]
- [[#usage-instructions][Usage Instructions]]
- [[#outlets-and-basins][Outlets and basins]]
- [[#one-point][One point]]
- [[#polygon-covering-multiple-land-and-ice-outlets][Polygon covering multiple land and ice outlets]]
- [[#discharge][Discharge]]
- [[#one-point-1][One point]]
- [[#polygon-covering-multiple-land-and-ice-outlets-1][Polygon covering multiple land and ice outlets]]
- [[#python-api][Python API]]
- [[#outlets-and-basins-1][Outlets and basins]]
- [[#one-point-2][One point]]
- [[#polygon-covering-multiple-land-and-ice-outlets-2][Polygon covering multiple land and ice outlets]]
- [[#discharge-1][Discharge]]
- [[#one-point-3][One point]]
- [[#polygon-covering-multiple-land-and-ice-outlets-3][Polygon covering multiple land and ice outlets]]

* Greenland liquid water discharge from 1950 through 2021

This is the source for "Greenland liquid water discharge from 1958 through 2019" and subsequent versions.

+ The paper is located at https://doi.org/10.5194/essd-12-2811-2020.
+ The data sets are located at [[https://doi.org/10.22008/promice/freshwater][doi:10.22008/promice/freshwater]]
+ Companion paper: "Greenland Ice Sheet solid ice discharge from 1986 through 2019"
+ Publication: [[https://doi.org/10.5194/essd-12-1367-2020][doi:10.5194/essd-12-1367-2020]]
+ Source: https://github.com/GEUS-PROMICE/ice_discharge/
+ Data: [[https://doi.org/10.22008/promice/data/ice_discharge][doi:10.22008/promice/data/ice_discharge]]
+ Contains basins for [[https://doi.org/10.22008/FK2/KIDYD1][k=0.8]] (ice only), [[https://doi.org/10.22008/FK2/TARK8O][0.9]] (ice only), and [[https://doi.org/10.22008/FK2/XKQVL7][1.0]] (ice and land) scenarios
+ Discharge data is included in the [[https://doi.org/10.22008/FK2/XKQVL7][Streams, Outlets, and Basins (k=1.0)]]

The source for this work is hosted on GitHub at https://github.com/GEUS-PROMICE/freshwater. GitHub [[https://github.com/mankoff/freshwater/issues?utf8=%E2%9C%93&q=is%3Aissue][issues]] are used to collect suggested improvements to the paper or problems that made it through review. The work may be under be under active development, including updating data (and therefore tables) within the source document.
+ This [[https://github.com/mankoff/freshwater/compare/10.5194/essd-12-2811-2020...main][diff]] shows changes between the published version of the paper and the current (active) development version.
+ Issues tagged [[https://github.com/GEUS-Glaciology-and-Climate/freshwater/issues?q=label%3Amajor_change][major change]] are worth noting and may be significant enough to update to the paper.
+ The source for the active development version can be viewed at https://github.com/GEUS-PROMICE/freshwater/tree/main
+ The source for the published paper can be viewed at https://github.com/GEUS-PROMICE/freshwater/tree/10.5194/essd-12-2811-2020

** Updates since last publication

*** v 2023

[[https://github.com/GEUS-Glaciology-and-Climate/freshwater/tree/release_2023][release_2023]] has the following changes from [[https://github.com/GEUS-Glaciology-and-Climate/freshwater/tree/release_2022][v2022-08]]. See [[https://github.com/GEUS-Glaciology-and-Climate/freshwater/milestone/1][2023 Milestone]], https://github.com/GEUS-Glaciology-and-Climate/freshwater/compare/release_2022...release_2023, and git log for more details

+ Added 2022 RACMO data
+ Added 2022 MAR data
+ Updated MAR data from 3.12 to 3.13
+ Updated BedMachine from v4 to v5
+ Updated ArcticDEM from v3.0 to v4.1

*** v 2022-10

v 2022-10 has the following changes:
+ No change to the data values
+ Data product has been reformatted to 4 NetCDF files: One per RCM (2) and domain (2), each containing all years of data
+ E.g., MAR_ice, MAR_land, RACMO_ice, RACMO_Land
+ Data files are now part of the dataset that contains the Geopackages of streams, outlets, and basins, rather than their own dataset on the dataverse
+ DOI: 10.22008/FK2/AA6MTB has been Deaccesioned
+ DOI: [[https://doi.org/10.22008/FK2/XKQVL7][10.22008/FK2/XKQVL7]] now contains the discharge data
+ The README has been updated to show some additional examples using the metadata added in v3

*** v 2022-08

v 2022-08 has the following changes (see GitHub diff above for more details):
+ Update from BedMachine v3 to v4
+ Data now spans 1950 through 2021, instead of 1958 through 2019
+ Internal NetCDF variable renamed from 'runoff' to 'discharge'
+ Significant improvement in metadata supporting better query by basin, region, or sector
+ Recognition that land runoff with depth << 0 is valid

* WARNING

#+BEGIN_QUOTE
[!WARNING]
+ Bugs may exist in this data or the [[./discharge.py]] access script. All known bugs will be documented at [[https://github.com/GEUS-PROMICE/freshwater/issues]]. Before using this software or finalizing results, you should check if any [[https://github.com/mankoff/freshwater/issues][open issues]] impact your results, or if any issue have been [[https://github.com/mankoff/freshwater/issues?q=is%3Aissue+is%3Aclosed][closed]] since you downloaded the data or script.
#+END_QUOTE

* Related Work

+ Companion paper: "Greenland ice sheet mass balance from 1840 through next week"
+ Publication: [[https://doi.org/10.5194/essd-13-5001-2021][doi:10.5194/essd-13-5001-2021]]
+ Source: https://github.com/GEUS-Glaciology-and-Climate/mass_balance
+ Data: https://doi.org/10.22008/FK2/OHI23Z

+ Companion paper: "Greenland Ice Sheet solid ice discharge from 1986 through March 2020"
+ Publication: [[https://doi.org/10.5194/essd-12-1367-2020][doi:10.5194/essd-12-1367-2020]]
+ Source: https://github.com/GEUS-PROMICE/ice_discharge/
+ Data: [[https://doi.org/10.22008/promice/data/ice_discharge][doi:10.22008/promice/data/ice_discharge]]

* Citation

#+BEGIN_EXAMPLE
@article{mankoff_2020_liquid,
author = {Mankoff, Kenneth D. and Noël, Brice and Fettweis, Xavier and Ahlstrøm, Andreas P. and
Colgan, William and Kondo, Ken and Langley, Kirsty and Sugiyama, Shin and van As,
Dirk and Fausto, Robert S.},
title = {{G}reenland liquid water discharge from 1958 through 2019},
journal = {Earth System Science Data},
year = 2020,
volume = 12,
number = 4,
pages = {2811–2841},
month = 11,
DOI = {10.5194/essd-12-2811-2020},
publisher = {Copernicus GmbH}
}
#+END_EXAMPLE

* Funding

| Dates | Organization | Program | Effort |
|--------------+--------------+-------------------------------------------+----------------------------------------|
| 2023 -- | NASA GISS | Modeling Analysis and Prediction program. | Maintenance |
| 2022 -- | GEUS | PROMICE | Distribution (data hosting) |
| 2018 -- 2022 | GEUS | PROMICE | Development; publication; distribution |

#+BEGIN_HTML





#+END_HTML

* Accessing this data
** Introduction

NOTE: Data can be accessed directly from the NetCDF files. Querying the NetCDF files directly allows more advanced queries on the metadata, for example, `all outlets with Jakobshavn Isbræ as the nearest discharge gate, excluding outlets more than 5 km away`. The `5 km` filter removes stream discharge from Disko Island which has Jakobshavn Isbræ as the nearest discharge gate, but should not be counted as discharge from that basin.

As an example, it is easiest to begin working with the outlets, save subsetted data, visually check in QGIS, and then when your algorithm appears to work, apply the same query to the discharge NetCDF files. Example:

#+BEGIN_SRC jupyter-python :exports code
import pandas as pd
import geopandas as gp

df = pd.read_csv('./freshwater/ice/outlets.csv', index_col=0)
gdf = gp.GeoDataFrame(df, geometry=gp.points_from_xy(df['lon'],df['lat']))

# select subglacial discharge within 2.5 km of basins
gdf = gdf[(gdf['elev'] < -10) &
(gdf['M2019_ID_dist'] < 2500)]

gdf.to_file("foo.gpkg", driver="GPKG")
#+END_SRC

Similar queries might include:
+ Pandas =groupby= to combine outlets per gate, basin, sector, or region
+ Examining the ice outlet location, and the downstream coastal outlet location. If the two are the same, then the outlet is marine terminating. This may give better results than querying based on the BedMachine provided =elev= metadata.

If you prefer to not access the NetCDF files directly, after the data have been downloaded the =discharge.py= script allows access to outlets, basins, and their discharge within a region of interest (ROI). The ROI can be a point, a list describing a polygon, or a file. Optionally, upstream outlets, basins, and discharge from any land outlet(s) can be included. The script can be called from the command line (CLI) or within Python.

The ROI coordinate units can be either EPSG:4326 (lon,lat) or EPSG:3413. The units for the coordinates are guessed using the range of values. If the ROI is a point, basins that contain that point are selected. Either 1 (if the point is on land) or two (ice and the downstream land, if the point is on the ice) basins are selected, and optionally, all ice basins upstream from the one land basin. If the ROI is a polygon, all outlets within the polygon are selected. The polygon does not have to be closed - a convex hull is wrapped around it. If the argument is a file (e.g. KML file) then the first polygon is selected and used.

When the script is run from the command line, CSV data is written to =stdout= and can be redirected to a file. When the API is accessed from within Python, if the script is used to access outlets, a =GeoPandas= =GeoDataFrame= is returned and can be used for further analysis within Python, or written to any file format supported by =GeoPandas= or =Pandas=, for example =CSV=, or =GeoPackage= for =QGIS=. If the script is used to access discharge, an =xarray= =Dataset= is returned, and can be used for further analysis within Python, or written to any file format supported by =xarray=, for example =CSV= or =NetCDF=.

*** Database Format

+ The =cat= column in the CSVs file links to the =station= vector in the NetCDF.

This script queries two database:

+ land :: The land coast outlets and land basins.
+ ice :: ice margin outlets and ice basins.

The folder structure required is a =root= folder (named =freshwater= in the examples below, but can be anything) and then a =land= and =ice= sub-folder. The geospatial files for =land= and =ice= must be in these folders (i.e. the k=1.0 Streams, Outlets, and Basins dataset from https://dataverse.geus.dk/dataverse/freshwater), along with a =MAR.nc= and =RACMO.nc= in each of the =land= and =ice= folders.

Example:

#+BEGIN_SRC bash :results verbatim :exports results
find ./freshwater/land/ ./freshwater/ice/ -maxdepth 1 | sort
#+END_SRC

#+RESULTS:
#+begin_example
./freshwater/ice/
./freshwater/ice/basins.csv
./freshwater/ice/basins_filled.gpkg
./freshwater/ice/basins.gpkg
./freshwater/ice/MAR.nc
./freshwater/ice/outlets.csv
./freshwater/ice/outlets.gpkg
./freshwater/ice/RACMO.nc
./freshwater/ice/streams.csv
./freshwater/ice/streams.gpkg
./freshwater/land/
./freshwater/land/basins.csv
./freshwater/land/basins_filled.gpkg
./freshwater/land/basins.gpkg
./freshwater/land/MAR.nc
./freshwater/land/outlets.csv
./freshwater/land/outlets.gpkg
./freshwater/land/RACMO.nc
./freshwater/land/streams.csv
./freshwater/land/streams.gpkg
#+end_example

*** Notes

+ The script takes a few seconds to query the outlets and basins. The script takes ~10s of seconds to query each of the discharge time series datasets. Because there may be up to 6 discharge queries (2 RCMs for each of 1 land domain + ice domain + upstream ice), it can several minutes on a fast laptop to extract the data. To track progress, do not set the =quiet= flag to =True=.

+ If a polygon includes ice outlets, and the ~upstream~ flag is set, some ice outlets, basins, and discharge may be included twice, once as a "direct" selection within the polygon and once as an upstream outlet and basin from the land polygon. Further processing by the user can remove duplicates (see examples below).

+ The =id= column may not be unique for multiple reasons:
+ As above, the same outlet may be included twice.
+ =id='s are unique within a dataset (i.e. =land=, and =ice=), but not between datasets.

+ Due to bash command-line parsing behavior, the syntax =--roi -60,60= does not work. Use ~--roi=-60,06~.

+ Longitude is expected in degrees East, and should therefore probably be negative.

+ The =cat= column in the CSVs file links to the =station= vector in the NetCDF.

+ If possible, avoid using index-based lookups, and query based on location or =station=.

*** Requirements
:PROPERTIES:
:header-args:jupyter-python: :kernel freshwater_user :session using :eval no-export
:END:

See =environment.yml= file in Git repository, or

#+BEGIN_SRC bash
mamba create -n freshwater_user python=3.7 xarray=0.20.2 fiona=1.8.21 shapely=1.8.2 geopandas=0.7.0 netcdf4=1.6.0 dask=2.15.0
mamba activate freshwater_user
#+END_SRC

** Examples
:PROPERTIES:
:header-args:jupyter-python: :kernel freshwater :session using :eval no-export :exports both
:header-args:bash: :eval no-export :session "*freshwater-shell*" :results verbatim :exports both :prologue conda activate freshwater_user
:END:

*** Command line interface
**** Usage Instructions

# (setq org-babel-min-lines-for-block-output 100)

#+BEGIN_SRC bash :exports both
python ./discharge.py -h
#+END_SRC

#+RESULTS:
#+begin_example
usage: discharge.py [-h] --base BASE --roi ROI [-u] (-o | -d) [-q]

Discharge data access

optional arguments:
-h, --help show this help message and exit
--base BASE Folder containing freshwater data
--roi ROI x,y OR lon,lat OR x0,y0 x1,y1 ... xn,yn OR lon0,lat0 lon1,lat1 ... lon_n,lat_n. [lon: degrees E]
-u, --upstream Include upstream ice outlets draining into land basins
-o, --outlets Return outlet IDs (same as basin IDs)
-d, --discharge Return RCM discharge for each domain (outlets merged)
-q, --quiet Be quiet
#+end_example

**** Outlets and basins
***** One point

The simplest example is a point, in this case near the Watson River outlet. Because we select one point over land and do not request upstream outlets and basins, only one row should be returned.

#+BEGIN_SRC bash :exports both :results table
python ./discharge.py --base ./freshwater --roi=-50.5,67.2 -o -q
#+END_SRC

#+RESULTS:
| index | id | lon | lat | x | y | elev | Z2012_sector | Z2012_sector_dist | M2019_ID | M2019_ID_dist | M2019_basin | M2019_region | M2020_gate | M2020_gate_dist | B2015_name | B2015_dist | domain | upstream | coast_id | coast_lon | coast_lat | coast_x | coast_y |
| 0 | 121108 | -51.219 | 67.153 | -271550 | -2492150 | 4 | 62 | 38320 | 71 | 38035 | ISUNNGUATA-RUSSELL | SW | 195 | 193828 | Isunnguata Sermia | 45930 | land | False | -1 | | | -1 | -1 |

If we move 10° east to somewhere over the ice, there should be four rows: one for the land outlet and basin, and three more for the three ice scenario:

#+BEGIN_SRC bash :exports both :results table
python ./discharge.py --base ./freshwater --roi=-40.5,67.2 -o -q
#+END_SRC

#+RESULTS:
| index | id | lon | lat | x | y | elev | Z2012_sector | Z2012_sector_dist | M2019_ID | M2019_ID_dist | M2019_basin | M2019_region | M2020_gate | M2020_gate_dist | B2015_name | B2015_dist | domain | upstream | coast_id | coast_lon | coast_lat | coast_x | coast_y |
| 0 | 126875 | -38.071 | 66.330 | 313650 | -2580750 | -187 | 41 | 5796 | 63 | 0 | HELHEIMGLETSCHER | SE | 231 | 9650 | Helheim Gletsjer | 11776 | land | False | -1 | | | -1 | -1 |
| 1 | 67985 | -38.110 | 66.333 | 311850 | -2580650 | -244 | 41 | 4177 | 63 | 0 | HELHEIMGLETSCHER | SE | 231 | 7850 | Helheim Gletsjer | 10042 | ice | False | 126875 | -38.071 | 66.330 | 313650 | -2580750 |

***** Polygon covering multiple land and ice outlets

Here a polygon covers several land outlets near the end of a fjord, and several ice outlets of the nearby ice margin. In addition, we request all ice outlets upstream of all selected land basins.

We use the following simple KML file for our ROI (this can be copied-and-pasted into the Google Earth side-bar to see it). Rather than use this file with ~--roi=/path/to/file.kml~, we use the coordinates directly, and demonstrate dropping the last coordinate because the code will wrap any polygon in a convex hull.

#+BEGIN_SRC xml

Ice and Land Sample

ice and land

1
-51.50,66.93 -51.21,66.74 -49.44,66.91 -49.84,67.18 -51.50,66.93

#+END_SRC

In this example, we query for upstream outlets, and for brevity show just the first three and last three lines.

#+BEGIN_SRC bash :results table :exports both
python ./discharge.py --base ./freshwater --roi="-51.50,66.93 -51.21,66.74 -49.44,66.91 -49.84,67.18" -q -u -o | (head -n3 ;tail -n4)
#+END_SRC

#+RESULTS:
| index | id | lon | lat | x | y | elev | Z2012_sector | Z2012_sector_dist | M2019_ID | M2019_ID_dist | M2019_basin | M2019_region | M2020_gate | M2020_gate_dist | B2015_name | B2015_dist | domain | upstream | coast_id | coast_lon | coast_lat | coast_x | coast_y |
| 0 | 122055 | -50.713 | 67.002 | -251250 | -2511450 | 20 | 62 | 22184 | 71 | 22906 | ISUNNGUATA-RUSSELL | SW | 195 | 207779 | Isunnguata Sermia | 31644 | land | False | -1 | | | -1 | -1 |
| 1 | 122222 | -50.735 | 66.988 | -252350 | -2512850 | 7 | 62 | 23683 | 71 | 24427 | ISUNNGUATA-RUSSELL | SW | 195 | 209355 | Isunnguata Sermia | 33360 | land | False | -1 | | | -1 | -1 |
| 203 | 67946 | -49.521 | 66.438 | -203950 | -2579550 | 767 | 62 | 0 | 40 | 0 | SAQQAP-MAJORQAQ-SOUTHTERRUSSEL_SOUTHQUARUSSEL | SW | 262 | 199999 | Quantum Gletsjer | 80065 | ice | True | 123466 | -50.652 | 66.868 | -250050 | -2526750 |
| 204 | 68014 | -49.544 | 66.419 | -205150 | -2581550 | 825 | 62 | 0 | 40 | 184 | SAQQAP-MAJORQAQ-SOUTHTERRUSSEL_SOUTHQUARUSSEL | SW | 262 | 197830 | Quantum Gletsjer | 78386 | ice | True | 123466 | -50.652 | 66.868 | -250050 | -2526750 |
| 205 | 68056 | -49.535 | 66.407 | -204850 | -2582950 | 859 | 62 | 0 | 40 | 0 | SAQQAP-MAJORQAQ-SOUTHTERRUSSEL_SOUTHQUARUSSEL | SW | 262 | 196497 | Quantum Gletsjer | 78340 | ice | True | 123466 | -50.652 | 66.868 | -250050 | -2526750 |

**** Discharge

The discharge examples here use the same code as the "outlets and basins" examples above, except we use =--discharge= rather than =--outlet=.

***** One point

The simplest example is a point, in this case near the Watson River outlet. Because we select one point over land and do not request upstream outlets and basins, two time series should be returned: =MAR_land= and =RACMO_land=. Rather than showing results for every day from 1958 through 2019, we limit to the header and the first 10 days of June, 2012.

#+BEGIN_SRC bash :exports both :results table
python ./discharge.py --base ./freshwater --roi=-50.5,67.2 -q -d | (head -n1; grep -A9 "^2012-06-01")
#+END_SRC

#+RESULTS:
| time | MAR_land | RACMO_land |
| 2012-06-01 | 11.893755 | 0.029936 |
| 2012-06-02 | 10.126999 | 0.001237 |
| 2012-06-03 | 8.114753 | 0.001323 |
| 2012-06-04 | 3.970580 | 0.000000 |
| 2012-06-05 | 0.313908 | -0.001191 |
| 2012-06-06 | 0.478592 | 0.303289 |
| 2012-06-07 | 0.330184 | 0.007452 |
| 2012-06-08 | 2.857732 | 0.193424 |
| 2012-06-09 | 0.308489 | 0.087070 |
| 2012-06-10 | 0.308755 | 0.024483 |

+ If we move 10° east to somewhere over the ice we add two columns: One for each of the two RCMs over the ice domain.
+ If the =--upstream= flag is set, we add two columns: One for each of the RCMs over the *upstream* ice domains. Results are summed across outlets per domain.
+ Results are therefore one of the following
+ Two columns: 2 RCM * 1 land domain
+ Four columns: 2 RCM * (1 land + 1 ice domain)
+ Four columns: 2 RCM * (1 land + 1 upstream ice domain)
+ Six columns: 2 RCM * (1 land + 1 ice + 1 upstream ice domain)

***** Polygon covering multiple land and ice outlets

When querying using an ROI that covers multiple outlets, discharge is summed by domain. Therefore, even if 100s of outlets are within the ROI, either two columns, eight, eight, or fourteen columns are returned depending on the options.

*** Python API

The python API is similar to the command line interface, but rather than printing results to =stdout=, returns a =GeoPandas= =GeoDataFrame= of outlets, an =xarray= =Dataset= of discharge. The discharge is not summed by domain, but instead contains discharge for each outlet.

**** Outlets and basins

***** One point

The simplest example is a point, in this case near the Watson River outlet. Because we select one point over land and do not request upstream outlets and basins, only one row should be returned.

#+BEGIN_SRC jupyter-python :session using
from discharge import discharge
df = discharge(base="./freshwater", roi="-50.5,67.2", quiet=True).outlets()
#+END_SRC

#+RESULTS:

The =df= variable is a =Pandas= =GeoDataFrame=.

It includes two geometry columns
+ =outlet= :: A point for the location of the outlet (also available as the =x= and =y= columns)
+ =basin= :: A polygon describing this basin

Because the geometry columns do not display well in tabular form, we drop them.

#+BEGIN_SRC jupyter-python :session using
df.drop(columns=["outlet","basin"])
#+END_SRC

#+RESULTS:
| index | id | lon | lat | x | y | elev | Z2012_sector | Z2012_sector_dist | M2019_ID | M2019_ID_dist | M2019_basin | M2019_region | M2020_gate | M2020_gate_dist | B2015_name | B2015_dist | domain | upstream | coast_id | coast_lon | coast_lat | coast_x | coast_y |
|-------+--------+----------+---------+---------+----------+------+--------------+-------------------+----------+---------------+--------------------+--------------+------------+-----------------+-------------------+------------+--------+----------+----------+-----------+-----------+---------+---------|
| 0 | 121108 | -51.2185 | 67.1535 | -271550 | -2492150 | 4 | 62 | 38320 | 71 | 38035 | ISUNNGUATA-RUSSELL | SW | 195 | 193828 | Isunnguata Sermia | 45930 | land | False | -1 | nan | nan | -1 | -1 |

***** Polygon covering multiple land and ice outlets

Here a polygon covers several land outlets near the end of a fjord, and several ice outlets of the nearby ice margin. In addition, we request all ice outlets upstream of all selected land basins. Results are shown in tabular form and written to geospatial file formats.

#+BEGIN_SRC jupyter-python :session using
from discharge import discharge
df = discharge(base="./freshwater", roi="-51.50,66.93 -51.21,66.74 -49.44,66.91 -49.84,67.18", quiet=True, upstream=True).outlets()
#+END_SRC

#+RESULTS:

View the first few rows, excluding the geometry columns

#+BEGIN_SRC jupyter-python :session using
df.drop(columns=["outlet","basin"]).head()
#+END_SRC

#+RESULTS:
| index | id | lon | lat | x | y | elev | Z2012_sector | Z2012_sector_dist | M2019_ID | M2019_ID_dist | M2019_basin | M2019_region | M2020_gate | M2020_gate_dist | B2015_name | B2015_dist | domain | upstream | coast_id | coast_lon | coast_lat | coast_x | coast_y |
|-------+--------+----------+---------+---------+----------+------+--------------+-------------------+----------+---------------+--------------------+--------------+------------+-----------------+-------------------+------------+--------+----------+----------+-----------+-----------+---------+---------|
| 0 | 122055 | -50.713 | 67.0017 | -251250 | -2511450 | 20 | 62 | 22184 | 71 | 22906 | ISUNNGUATA-RUSSELL | SW | 195 | 207779 | Isunnguata Sermia | 31644 | land | False | -1 | nan | nan | -1 | -1 |
| 1 | 122222 | -50.7346 | 66.9884 | -252350 | -2512850 | 7 | 62 | 23683 | 71 | 24427 | ISUNNGUATA-RUSSELL | SW | 195 | 209355 | Isunnguata Sermia | 33360 | land | False | -1 | nan | nan | -1 | -1 |
| 2 | 122251 | -50.7748 | 66.985 | -254150 | -2513050 | -1 | 62 | 25444 | 71 | 26179 | ISUNNGUATA-RUSSELL | SW | 195 | 209887 | Isunnguata Sermia | 34934 | land | False | -1 | nan | nan | -1 | -1 |
| 3 | 122275 | -50.8707 | 66.9767 | -258450 | -2513550 | 4 | 62 | 29682 | 71 | 30397 | ISUNNGUATA-RUSSELL | SW | 195 | 211236 | Isunnguata Sermia | 38789 | land | False | -1 | nan | nan | -1 | -1 |
| 4 | 122285 | -50.8569 | 66.9764 | -257850 | -2513650 | 15 | 62 | 29141 | 71 | 29862 | ISUNNGUATA-RUSSELL | SW | 195 | 211209 | Isunnguata Sermia | 38336 | land | False | -1 | nan | nan | -1 | -1 |

View the last few rows:

Note that the =domain= and =upstream= columns can be used to subset the table.

#+BEGIN_SRC jupyter-python :session using
df.drop(columns=["outlet","basin"]).tail()
#+END_SRC

#+RESULTS:
| index | id | lon | lat | x | y | elev | Z2012_sector | Z2012_sector_dist | M2019_ID | M2019_ID_dist | M2019_basin | M2019_region | M2020_gate | M2020_gate_dist | B2015_name | B2015_dist | domain | upstream | coast_id | coast_lon | coast_lat | coast_x | coast_y |
|-------+-------+----------+---------+---------+----------+------+--------------+-------------------+----------+---------------+-----------------------------------------------+--------------+------------+-----------------+------------------+------------+--------+----------+----------+-----------+-----------+---------+----------|
| 201 | 67919 | -49.4996 | 66.4435 | -202950 | -2578950 | 791 | 62 | 0 | 40 | 6 | SAQQAP-MAJORQAQ-SOUTHTERRUSSEL_SOUTHQUARUSSEL | SW | 262 | 200758 | Quantum Gletsjer | 81191 | ice | True | 123466 | -50.6517 | 66.8677 | -250050 | -2526750 |
| 202 | 67935 | -49.5385 | 66.4378 | -204750 | -2579450 | 764 | 62 | 0 | 40 | 0 | SAQQAP-MAJORQAQ-SOUTHTERRUSSEL_SOUTHQUARUSSEL | SW | 262 | 199967 | Quantum Gletsjer | 79323 | ice | True | 123466 | -50.6517 | 66.8677 | -250050 | -2526750 |
| 203 | 67946 | -49.5206 | 66.4375 | -203950 | -2579550 | 767 | 62 | 0 | 40 | 0 | SAQQAP-MAJORQAQ-SOUTHTERRUSSEL_SOUTHQUARUSSEL | SW | 262 | 199999 | Quantum Gletsjer | 80065 | ice | True | 123466 | -50.6517 | 66.8677 | -250050 | -2526750 |
| 204 | 68014 | -49.5436 | 66.419 | -205150 | -2581550 | 825 | 62 | 0 | 40 | 184 | SAQQAP-MAJORQAQ-SOUTHTERRUSSEL_SOUTHQUARUSSEL | SW | 262 | 197830 | Quantum Gletsjer | 78386 | ice | True | 123466 | -50.6517 | 66.8677 | -250050 | -2526750 |
| 205 | 68056 | -49.5346 | 66.4068 | -204850 | -2582950 | 859 | 62 | 0 | 40 | 0 | SAQQAP-MAJORQAQ-SOUTHTERRUSSEL_SOUTHQUARUSSEL | SW | 262 | 196497 | Quantum Gletsjer | 78340 | ice | True | 123466 | -50.6517 | 66.8677 | -250050 | -2526750 |

Finally, write data to various file formats. GeoPandas DataFrames can only have one geometry, so we must select one and drop the other before writing the file.

#+BEGIN_SRC jupyter-python :session using
df.drop(columns=["outlet","basin"]).to_csv("outlets.csv")
df.set_geometry("outlet").drop(columns="basin").to_file("outlets.gpkg", driver="GPKG")
df.set_geometry("basin").drop(columns="outlet").to_file("basins.gpkg", driver="GPKG")
#+END_SRC

**** Discharge

The code here is the same as above from the "Outlets and basins" section, but we call =discharge()= rather than =outlets()=.

***** One point

The simplest example is a point, in this case near the Watson River outlet. Because we select one point over land and do not request upstream outlets and basins, only one row should be returned.

#+BEGIN_SRC jupyter-python :session using
from discharge import discharge
ds = discharge(base="./freshwater", roi="-50.5,67.2").discharge()
#+END_SRC

Print the =xarray= =Dataset=:

#+BEGIN_SRC jupyter-python :session using :exports both
print(ds)
#+END_SRC

#+RESULTS:
:
: Dimensions: (land: 1, time: 26663)
: Coordinates:
: * time (time) datetime64[ns] 1950-01-01 1950-01-02 ... 2022-12-31
: * land (land) uint64 121108
: Data variables:
: MAR_land (time, land) float64 0.0007218 0.0007235 ... 0.6995 0.7007
: RACMO_land (time, land) float64 nan nan nan nan ... 0.1555 0.1591 0.1549

Display the time series. Unlike the command line interface, here the outlets are not merged.

#+BEGIN_SRC jupyter-python :session using
ds.sel(time=slice('2012-06-01','2012-06-10')).to_dataframe()
#+END_SRC

#+RESULTS:
| | MAR_land | RACMO_land |
|------------------------------------------------------+----------+------------|
| (121108, Timestamp('2012-06-01 00:00:00', freq='D')) | 11.8938 | 0.029936 |
| (121108, Timestamp('2012-06-02 00:00:00', freq='D')) | 10.127 | 0.00123702 |
| (121108, Timestamp('2012-06-03 00:00:00', freq='D')) | 8.11475 | 0.00132286 |
| (121108, Timestamp('2012-06-04 00:00:00', freq='D')) | 3.97058 | 0 |
| (121108, Timestamp('2012-06-05 00:00:00', freq='D')) | 0.313908 | -0.0011907 |
| (121108, Timestamp('2012-06-06 00:00:00', freq='D')) | 0.478592 | 0.303289 |
| (121108, Timestamp('2012-06-07 00:00:00', freq='D')) | 0.330184 | 0.00745243 |
| (121108, Timestamp('2012-06-08 00:00:00', freq='D')) | 2.85773 | 0.193424 |
| (121108, Timestamp('2012-06-09 00:00:00', freq='D')) | 0.308489 | 0.0870701 |
| (121108, Timestamp('2012-06-10 00:00:00', freq='D')) | 0.308755 | 0.0244829 |

In order to merge the outlets, select all coordinates that are *not time* and merge them. Also, apply a rolling mean:

#+BEGIN_SRC jupyter-python :session using
dims = [_ for _ in ds.dims.keys() if _ != 'time'] # get all dimensions except the time dimension
ds.sum(dim=dims)\
.rolling(time=7)\
.mean()\
.sel(time=slice('2012-06-01','2012-06-10'))\
.to_dataframe()
#+END_SRC

#+RESULTS:
| time | MAR_land | RACMO_land |
|---------------------+----------+------------|
| 2012-06-01 00:00:00 | 30.644 | 1.39377 |
| 2012-06-02 00:00:00 | 31.1031 | 1.2407 |
| 2012-06-03 00:00:00 | 27.5909 | 0.458691 |
| 2012-06-04 00:00:00 | 21.0425 | 0.157925 |
| 2012-06-05 00:00:00 | 14.3486 | 0.0893565 |
| 2012-06-06 00:00:00 | 8.40202 | 0.0880673 |
| 2012-06-07 00:00:00 | 5.03268 | 0.0488637 |
| 2012-06-08 00:00:00 | 3.74182 | 0.0722192 |
| 2012-06-09 00:00:00 | 2.33918 | 0.084481 |
| 2012-06-10 00:00:00 | 1.22403 | 0.0877896 |

***** Polygon covering multiple land and ice outlets

Here a polygon covers several land outlets near the end of a fjord, and several ice outlets of the nearby ice margin. In addition, we request all ice outlets upstream of all selected land basins.

#+BEGIN_SRC jupyter-python :session using
from discharge import discharge
ds = discharge(base="./freshwater", roi="-51.50,66.93 -51.21,66.74 -49.44,66.91 -49.84,67.18", quiet=True, upstream=True).discharge()
#+END_SRC

What are the dimensions (i.e. how many outlets in each domain?)

#+BEGIN_SRC jupyter-python :session using :exports both
print(ds)
#+END_SRC

#+RESULTS:
#+begin_example

Dimensions: (ice: 33, ice_upstream: 85, land: 88, time: 26663)
Coordinates:
,* ice_upstream (ice_upstream) uint64 66407 66414 66416 ... 68014 68056
,* time (time) datetime64[ns] 1950-01-01 ... 2022-12-31
,* land (land) uint64 122055 122222 122251 ... 123897 123926
,* ice (ice) uint64 66425 66427 66444 ... 66595 66596 66639
Data variables:
MAR_land (time, land) float64 0.0002109 1.244e-06 ... 0.005236
MAR_ice (time, ice) float64 2.94e-16 2.026e-17 ... 2.785e-18
RACMO_land (time, land) float64 nan nan nan ... 0.001346 0.1365
RACMO_ice (time, ice) float64 nan nan nan ... 0.0001123 0.004071
MAR_ice_upstream (time, ice_upstream) float64 1.261e-17 ... 1.855e-17
RACMO_ice_upstream (time, ice_upstream) float64 nan nan ... 5.79e-05
#+end_example

With these results:
+ Sum all outlets within each domain
+ Drop the land discharge and the upstream domains (keep only ice discharge explicitly within our ROI)
+ Apply a 5-day rolling mean
+ Plot 2012 discharge season

#+BEGIN_SRC jupyter-python :session using
d = [_ for _ in ds.dims.keys() if _ != 'time'] # dims for summing (don't sum time dimension)
v = [_ for _ in ds.data_vars if ('land' in _) | ('_u' in _)] # vars containing '_u'

r = ds.sum(dim=d)\
.drop_vars(v)\
.rolling(time=5).mean()

import matplotlib.pyplot as plt
plt.style.use('seaborn')

for d in r.data_vars: r[d].sel(time=slice('2012-04-01','2012-11-15')).plot(drawstyle='steps', label=d)
_ = plt.legend()
plt.savefig("./fig/api_example.png", bbox_inches='tight')
#+END_SRC

#+RESULTS:

[[./fig/api_example.png]]