JOSS paper

paper.bib

@@ -0,0 +1,209 @@
+@article{grooms2021diffusion,
+	title = {Diffusion-{Based} {Smoothers} for {Spatial} {Filtering} of {Gridded} {Geophysical} {Data}},
+	volume = {13},
+	copyright = {© 2021 The Authors. Journal of Advances in Modeling Earth Systems published by Wiley Periodicals LLC on behalf of American Geophysical Union.},
+	issn = {1942-2466},
+	url = {https://onlinelibrary.wiley.com/doi/abs/10.1029/2021MS002552},
+	doi = {10.1029/2021MS002552},
+	abstract = {We describe a new way to apply a spatial filter to gridded data from models or observations, focusing on low-pass filters. The new method is analogous to smoothing via diffusion, and its implementation requires only a discrete Laplacian operator appropriate to the data. The new method can approximate arbitrary filter shapes, including Gaussian filters, and can be extended to spatially varying and anisotropic filters. The new diffusion-based smoother's properties are illustrated with examples from ocean model data and ocean observational products. An open-source Python package implementing this algorithm, called gcm-filters, is currently under development.},
+	language = {en},
+	number = {9},
+	journal = {Journal of Advances in Modeling Earth Systems},
+	author = {Grooms, I. and Loose, N. and Abernathey, R. and Steinberg, J. M. and Bachman, S. D. and Marques, G. and Guillaumin, A. P. and Yankovsky, E.},
+	year = {2021},
+	keywords = {coarse graining, data analysis, spatial filtering},
+	pages = {e2021MS002552},
+}
+
+@article{hoyer2017xarray,
+  title={xarray: ND labeled arrays and datasets in Python},
+  author={Hoyer, Stephan and Hamman, Joe},
+  journal={Journal of Open Research Software},
+  volume={5},
+  number={1},
+  year={2017},
+  publisher={Ubiquity Press},
+  doi={10.5334/jors.148}
+}
+
+
+@Manual{dask,
+  title = {Dask: Library for dynamic task scheduling},
+  author = {{Dask Development Team}},
+  year = {2016},
+  url = {https://dask.org},
+}
+
+@misc{mom5,
+  title = {MOM 5: The Modular Ocean Model},
+  author = {{MOM 5 Development Team}},
+  year = {2012},
+  url = {https://github.com/mom-ocean/MOM5},
+}
+
+@misc{mom6,
+  title = {MOM 6: The Modular Ocean Model},
+  author = {{MOM 6 Development Team}},
+  url = {https://github.com/NOAA-GFDL/MOM6},
+}
+
+@manual{pop2,
+  title = {The Parallel Ocean Program (POP) reference manual},
+  year = {2010},
+  author = {Smith, R. and Jones, P. and  Briegleb, B. and Bryan, F. and  Danabasoglu, G. and Dennis, J. and Dukowicz, J. and Eden, C. and Fox-Kemper, B. and Gent, P. and Hecht, M. and Jayne, S. and Jochum, M. and Large, W. and Lindsay, K., Maltrud, M. and Norton, N. and Peacock, S. and Vertenstein, M. and Yeager, S.},
+  url = {http://www.cesm.ucar.edu/models/cesm1.0/pop2/doc/sci/POPRefManual.pdf},
+}
+
+@manual{pop2-cesm,
+  title = {POP2-CESM},
+  author = {{POP2-CESM Development Team}},
+  url = {https://github.com/ESCOMP/POP2-CESM},
+}
+
+
+@InProceedings{ matthew_rocklin-proc-scipy-2015,
+  author    = { Matthew Rocklin },
+  title     = { Dask: Parallel Computation with Blocked algorithms and Task Scheduling },
+  booktitle = { Proceedings of the 14th Python in Science Conference },
+  pages     = { 130 - 136 },
+  year      = { 2015 },
+  editor    = { Kathryn Huff and James Bergstra }
+}
+
+@ARTICLE{2020SciPy-NMeth,
+  author  = {Virtanen, Pauli and Gommers, Ralf and Oliphant, Travis E. and
+            Haberland, Matt and Reddy, Tyler and Cournapeau, David and
+            Burovski, Evgeni and Peterson, Pearu and Weckesser, Warren and
+            Bright, Jonathan and {van der Walt}, St{\'e}fan J. and
+            Brett, Matthew and Wilson, Joshua and Millman, K. Jarrod and
+            Mayorov, Nikolay and Nelson, Andrew R. J. and Jones, Eric and
+            Kern, Robert and Larson, Eric and Carey, C J and
+            Polat, {\.I}lhan and Feng, Yu and Moore, Eric W. and
+            {VanderPlas}, Jake and Laxalde, Denis and Perktold, Josef and
+            Cimrman, Robert and Henriksen, Ian and Quintero, E. A. and
+            Harris, Charles R. and Archibald, Anne M. and
+            Ribeiro, Ant{\^o}nio H. and Pedregosa, Fabian and
+            {van Mulbregt}, Paul and {SciPy 1.0 Contributors}},
+  title   = {{{SciPy} 1.0: Fundamental Algorithms for Scientific
+            Computing in Python}},
+  journal = {Nature Methods},
+  year    = {2020},
+  volume  = {17},
+  pages   = {261--272},
+  adsurl  = {https://rdcu.be/b08Wh},
+  doi     = {10.1038/s41592-019-0686-2},
+}
+
+@Article{         harris2020array,
+ title         = {Array programming with {NumPy}},
+ author        = {Charles R. Harris and K. Jarrod Millman and St{\'{e}}fan J.
+                 van der Walt and Ralf Gommers and Pauli Virtanen and David
+                 Cournapeau and Eric Wieser and Julian Taylor and Sebastian
+                 Berg and Nathaniel J. Smith and Robert Kern and Matti Picus
+                 and Stephan Hoyer and Marten H. van Kerkwijk and Matthew
+                 Brett and Allan Haldane and Jaime Fern{\'{a}}ndez del
+                 R{\'{i}}o and Mark Wiebe and Pearu Peterson and Pierre
+                 G{\'{e}}rard-Marchant and Kevin Sheppard and Tyler Reddy and
+                 Warren Weckesser and Hameer Abbasi and Christoph Gohlke and
+                 Travis E. Oliphant},
+ year          = {2020},
+ month         = sep,
+ journal       = {Nature},
+ volume        = {585},
+ number        = {7825},
+ pages         = {357--362},
+ doi           = {10.1038/s41586-020-2649-2},
+ publisher     = {Springer Science and Business Media {LLC}},
+ url           = {https://doi.org/10.1038/s41586-020-2649-2}
+}
+
+@inproceedings{cupy2017learningsys,
+  author       = "Okuta, Ryosuke and Unno, Yuya and Nishino, Daisuke and Hido, Shohei and Loomis, Crissman",
+  title        = "CuPy: A NumPy-Compatible Library for NVIDIA GPU Calculations",
+  booktitle    = "Proceedings of Workshop on Machine Learning Systems (LearningSys) in The Thirty-first Annual Conference on Neural Information Processing Systems (NIPS)",
+  year         = "2017",
+  url          = "http://learningsys.org/nips17/assets/papers/paper_16.pdf"
+}
+
+@Article{Hunter2007,
+  title   = {Matplotlib: A 2D graphics environment},
+  author  = {Hunter, J. D.},
+  journal = {Computing in Science \& Engineering},
+  volume  = {9},
+  number  = {3},
+  pages   = {90--95},
+  year    = {2007},
+  doi     = {10.1109/MCSE.2007.55}
+}
+
+@article{adcroft2019MOM6,
+author = {Adcroft, Alistair and Anderson, Whit and Balaji, V. and Blanton, Chris and Bushuk, Mitchell and Dufour, Carolina O. and Dunne, John P. and Griffies, Stephen M. and Hallberg, Robert and Harrison, Matthew J. and Held, Isaac M. and Jansen, Malte F. and John, Jasmin G. and Krasting, John P. and Langenhorst, Amy R. and Legg, Sonya and Liang, Zhi and McHugh, Colleen and Radhakrishnan, Aparna and Reichl, Brandon G. and Rosati, Tony and Samuels, Bonita L. and Shao, Andrew and Stouffer, Ronald and Winton, Michael and Wittenberg, Andrew T. and Xiang, Baoqiang and Zadeh, Niki and Zhang, Rong},
+title = {The GFDL Global Ocean and Sea Ice Model OM4.0: Model Description and Simulation Features},
+journal = {Journal of Advances in Modeling Earth Systems},
+volume = {11},
+number = {10},
+pages = {3167-3211},
+keywords = {ocean circulation model, CORE, hybrid coordinates},
+doi = {https://doi.org/10.1029/2019MS001726},
+url = {https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/2019MS001726},
+eprint = {https://agupubs.onlinelibrary.wiley.com/doi/pdf/10.1029/2019MS001726},
+abstract = {Abstract We document the configuration and emergent simulation features from the Geophysical Fluid Dynamics Laboratory (GFDL) OM4.0 ocean/sea ice model. OM4 serves as the ocean/sea ice component for the GFDL climate and Earth system models. It is also used for climate science research and is contributing to the Coupled Model Intercomparison Project version 6 Ocean Model Intercomparison Project. The ocean component of OM4 uses version 6 of the Modular Ocean Model and the sea ice component uses version 2 of the Sea Ice Simulator, which have identical horizontal grid layouts (Arakawa C-grid). We follow the Coordinated Ocean-sea ice Reference Experiments protocol to assess simulation quality across a broad suite of climate-relevant features. We present results from two versions differing by horizontal grid spacing and physical parameterizations: OM4p5 has nominal 0.5° spacing and includes mesoscale eddy parameterizations and OM4p25 has nominal 0.25° spacing with no mesoscale eddy parameterization. Modular Ocean Model version 6 makes use of a vertical Lagrangian-remap algorithm that enables general vertical coordinates. We show that use of a hybrid depth-isopycnal coordinate reduces the middepth ocean warming drift commonly found in pure z* vertical coordinate ocean models. To test the need for the mesoscale eddy parameterization used in OM4p5, we examine the results from a simulation that removes the eddy parameterization. The water mass structure and model drift are physically degraded relative to OM4p5, thus supporting the key role for a mesoscale closure at this resolution.},
+year = {2019}
+}
+
+@manual{Cartopy,
+author = {{Met Office}},
+title = {Cartopy: a cartographic python library with a matplotlib interface},
+year = {2010 - 2015},
+address = {Exeter, Devon },
+url = {http://scitools.org.uk/cartopy}
+}
+
+@article{adcroft_mitgcm_2018,
+	title = {MITgcm {User} {Manual}},
+	doi = {1721.1/117188},
+	journal = {Zenodo},
+	author = {Adcroft, A. and J.M. Campin and S. Dutkiewicz and C. Evangelinos and D. Ferreira and G. Forget and B. Fox-Kemper and P. Heimbach and C. Hill and E. Hill and H. Hill and O. Jahn and M. Losch and J. Marshall and G. Maze and D. Menemenlis and A. Molod},
+	year = {2018},
+}
+
+
+@software{mitgcm,
+  author       = {Jean-Michel Campin and
+                  Patrick Heimbach and
+                  Martin Losch and
+                  Gael Forget and
+                  edhill3 and
+                  Alistair Adcroft and
+                  amolod and
+                  Dimitris Menemenlis and
+                  dfer22 and
+                  Chris Hill and
+                  Oliver Jahn and
+                  Jeff Scott and
+                  stephdut and
+                  Matt Mazloff and
+                  Baylor Fox-Kemper and
+                  antnguyen13 and
+                  Ed Doddridge and
+                  Ian Fenty and
+                  Michael Bates and
+                  AndrewEichmann-NOAA and
+                  Timothy Smith and
+                  Torge Martin and
+                  Jonathan Lauderdale and
+                  Ryan Abernathey and
+                  samarkhatiwala and
+                  hongandyan and
+                  Bruno Deremble and
+                  dngoldberg and
+                  Pascal Bourgault and
+                  raphael dussin},
+  title        = {MITgcm/MITgcm: checkpoint67z},
+  month        = jun,
+  year         = 2021,
+  publisher    = {Zenodo},
+  version      = {checkpoint67z},
+  doi          = {10.5281/zenodo.4968496},
+  url          = {https://doi.org/10.5281/zenodo.4968496}
+}

paper.md

@@ -0,0 +1,100 @@
+---
+title: 'GCM-Filters: A Python package for Diffusion-based Spatial Filtering of Gridded Data'
+tags:
+  - Python
+  - ocean modeling
+  - climate modeling
+  - fluid dynamics
+authors:
+  - name: Nora Loose
+    orcid: 0000-0002-3684-9634
+    affiliation: 1
+  - name: Ryan Abernathey
+    orcid: 0000-0001-5999-4917
+    affiliation: 2
+  - name: Ian Grooms
+    orcid: 0000-0002-4678-7203
+    affiliation: 1
+  - name: Julius Busecke
+    orcid: 0000-0001-8571-865X
+    affiliation: 2
+  - name: Arthur Barthe
+    orcid: 0000-0003-1571-4228
+    affiliation: 3
+  - name: Elizabeth Yankovsky
+    orcid: 0000-0003-3612-549X
+    affiliation: 3
+  - name: Gustavo Marques
+    orcid: 0000-0001-7238-0290
+    affiliation: 4
+  - name: Jacob Steinberg
+    orcid: 0000-0002-2609-6405
+    affiliation: 5
+  - name: Andrew Ross
+    orcid: 0000-0002-2368-6979
+    affiliation: 3
+  - name: Hemant Khatri
+    orcid: 0000-0001-6559-9059
+    affiliation: 6
+  - name: Scott Bachman
+    orcid: 0000-0002-6479-4300
+    affiliation: 4
+  - name: Laure Zanna
+    orcid: 0000-0002-8472-4828
+    affiliation: 3
+affiliations:
+  - name: Department of Applied Mathematics, University of Colorado Boulder, Boulder, CO, USA
+    index: 1
+  - name: Lamont-Doherty Earth Observatory, Columbia University, New York, NY, USA
+    index: 2
+  - name: Courant Institute of Mathematical Sciences, New York University, New York, NY, USA
+    index: 3
+  - name: Climate and Global Dynamics Division, National Center for Atmospheric Research, Boulder, CO, USA
+    index: 4
+  - name: Woods Hole Oceanographic Institution, Woods Hole, MA, USA
+    index: 5
+  - name: Earth, Ocean and Ecological Sciences, University of Liverpool, UK
+    index: 6
+
+date: 1 November 2021
+bibliography: paper.bib
+
+---
+
+# Summary
+
+`GCM-Filters` is a python package that allows scientists to perform spatial filtering analysis in an easy, flexible and efficient way. The package implements the filtering method that was introduced by @grooms2021diffusion. The filtering algorithm is analogous to smoothing via diffusion; hence the name *diffusion-based filters*. `GCM-Filters` can be used with either gridded observational data or gridded data that is produced by General Circulation Models (GCMs) of ocean, weather, and climate. Spatial filtering of observational or GCM data is a common analysis method in the Earth Sciences, for example to study oceanic and atmospheric motions at different spatial scales or to develop subgrid-scale parameterizations for ocean models.
+
+`GCM-Filters` provides filters that are highly configurable, with the goal to be useful for a wide range of scientific applications. The user has different options for selecting the filter scale and filter shape.
+The filter scale can be defined in several ways: a fixed length scale (e.g., 100 km), a scale tied to a model grid scale (e.g., 1$^\circ$), or a scale tied to a varying dynamical scale (e.g., the Rossby radius of deformation). As an example, \autoref{fig1} shows unfiltered and filtered relative vorticity, where the filter scale is set to a model grid scale of 4$^\circ$. `GCM-Filters` also allows for anisotropic, i.e., direction-dependent, filtering.
+Finally, the filter shape -- currently: either Gaussian or Taper -- determines how sharply the filter separates scales above and below the target filter scale.
+
+![(Left) Snapshot of unfiltered surface relative vorticity  $\zeta = \partial_x v - \partial_y u$ from a global 0.1$^\circ$ simulation with MOM6 [@adcroft2019MOM6]. (Right) Relative vorticity filtered to 4$^\circ$, obtained by applying `GCM-Filters` to the field $\zeta$ on the left. The plots are made with `matplotlib` [@Hunter2007] and `cartopy` [@Cartopy].\label{fig1}](filtered_vorticity.png){ width=100% }
+
+# Statement of Need
+
+Spatial filtering is commonly used as a scientific tool for analyzing gridded data. An example of an existing spatial filtering tool in python is `SciPy`'s [@2020SciPy-NMeth] `ndimage.gaussian_filter` function, implemented as a sequence of convolution filters. While being a valuable tool for image processing (or blurring), `SciPy`'s Gaussian filter is of limited use for GCM data; it assumes a regular and rectangular Cartesian grid, employs a simple boundary condition, and the definitions of filter scale and shape have little or no flexibility. The python package `GCM-Filters` is specificially designed to filter GCM data, and seeks to solve a number of challenges for the user:
+
+1. GCM data comes on irregular curvilinear grids with spatially varying grid-cell geometry.
+2. Continental boundaries require careful and special treatment when filtering ocean GCM output.
+3. Earth Science applications benefit from configurable filters, where the definition of filter scale and shape is flexible.
+4. GCM output is often too large to process in memory, requiring distributed and / or delayed execution.
+
+The `GCM-Filters` algorithm [@grooms2021diffusion] applies a discrete Laplacian to smooth a field through an iterative process that resembles diffusion. The discrete Laplacian takes into account the varying grid-cell geometry and uses a no-flux boundary condition, mimicking how diffusion is internally implemented in GCMs. The no-flux boundary conditions ensures that the filter preserves the integral: $\int_{\Omega} \bar{f}(x,y) \,dA = \int_{\Omega} f (x,y)\, dA$, where $f$ is the original field, $\bar{f}$ the filtered field, and $\Omega$ the ocean domain. Conservation of the integral is a desirable filter property for many physical quantities, for example energy or ocean salinity. More details on the filter properties can be found in @grooms2021diffusion.
+
+An important goal of `GCM-Filters` is to enable computationally efficient filtering. The user can employ `GCM-Filters` on either CPUs or GPUs, with `NumPy` [@harris2020array] or `CuPy` [@cupy2017learningsys] input data. `GCM-Filters` leverages `Dask` [@dask] and `Xarray` [@hoyer2017xarray] to support filtering of larger-than-memory datasets and computational flexibility.
+
+# Usage
+
+The main `GCM-Filters` class that the user will interface with is the `gcm_filters.Filter` object. When creating a filter object, the user specifies how they want to smooth their data, including the desired filter shape and filter scale. At this stage, the user also picks the grid type that matches their GCM data, given a predefined list of grid types. Each grid type has an associated discrete Laplacian, and requires different *grid variables* that the user must provide (the latter are usually available to the user as part of the GCM output). Currently, `GCM-Filters` provides a number of different grid types and associated discrete Laplacians:
+
+* Grid types with **scalar Laplacians** that can be used for filtering scalar fields, for example temperature or vorticity (see \autoref{fig1}). The currently implemented grid types are compatible with different ocean GCM grids including MOM5 [@mom5], MOM6 [@adcroft2019MOM6] and the POP2 [@pop2] tripole grid.
+* Grid types with **vector Laplacians** that can be used for filtering vector fields, for example horizontal velocity $(u,v)$. The currently implemented grid type is compatible with ocean GCM grids that use an Arakawa C-grid convention; examples include MOM6 [@adcroft2019MOM6] and the MITgcm [@mitgcm].
+
+Atmospheric model grids are not yet supported, but could be implemented within the `GCM-Filters` package. Users are encouraged to contribute more grid types and Laplacians via pull requests.
+
+# Acknowledgements
+
+This work was supported by the National Science Foundation grants OCE 1912302, OCE 1912325, OCE 1912332, OCE 1912420, GEO 1912357, and the NOAA grant CVP NA19OAR4310364.
+
+# References