diff --git a/.gitignore b/.gitignore index 99f572c9..f2b99889 100644 --- a/.gitignore +++ b/.gitignore @@ -116,3 +116,8 @@ conda-build/ # Ad-hoc QA qa/ + +# Sphinx generated .txt files +notebook-examples.txt +team-panel.txt +demos.txt \ No newline at end of file diff --git a/AUTHORS.rst b/AUTHORS.rst deleted file mode 100644 index e0517d00..00000000 --- a/AUTHORS.rst +++ /dev/null @@ -1,9 +0,0 @@ -======== -The Team -======== - -* Tom Vo -* Jason Boutte -* Stephen Po-Chedley -* Jill Chengzhu Zhang -* Jiwoo Lee diff --git a/README.rst b/README.rst index 3c194863..58633a23 100644 --- a/README.rst +++ b/README.rst @@ -215,12 +215,21 @@ Xarray and Xarray usage in climate science! - `Pangeo Forum `_ - `Project Pythia `_ -Acknowledgement ---------------- +Projects Using xCDAT +-------------------- -Huge thank you to all of the xCDAT `contributors`_! +xCDAT is actively being integrated as a core component of the `Program for Climate Model +Diagnosis and Intercomparison (PCMDI) Metrics Package`_ and the `Energy Exascale Earth +System Model Diagnostics (E3SM) Package`_. xCDAT is also included in the `E3SM Unified +Anaconda Environment`_ that is deployed on various U.S. Department of Energy +supercomputers to run E3SM software tools. + +.. _Program for Climate Model Diagnosis and Intercomparison (PCMDI) Metrics Package: https://pcmdi.github.io/pcmdi_metrics/ +.. _Energy Exascale Earth System Model Diagnostics (E3SM) Package: https://e3sm-project.github.io/e3sm_diags/_build/html/main/index.html +.. _E3SM Unified Anaconda Environment: https://e3sm.org/resources/tools/other-tools/e3sm-unified-environment/ -.. _contributors: https://github.com/xCDAT/xcdat/graphs/contributors +Acknowledgement +--------------- xCDAT is jointly developed by scientists and developers from the Energy Exascale Earth System Model (`E3SM`_) Project and Program for Climate Model Diagnosis and @@ -241,18 +250,14 @@ Environmental Research (`BER`_) within the `Department of Energy`_'s `Office of .. _Department of Energy: https://www.energy.gov/ .. _Office of Science: https://science.osti.gov/ -Projects Using xCDAT --------------------- +Contributors +------------ -xCDAT is actively being integrated as a core component of the `Program for Climate Model -Diagnosis and Intercomparison (PCMDI) Metrics Package`_ and the `Energy Exascale Earth -System Model Diagnostics (E3SM) Package`_. xCDAT is also included in the `E3SM Unified -Anaconda Environment`_ that is deployed on various U.S. Department of Energy -supercomputers to run E3SM software tools. +Thank you to all of our contributors! -.. _Program for Climate Model Diagnosis and Intercomparison (PCMDI) Metrics Package: https://pcmdi.github.io/pcmdi_metrics/ -.. _Energy Exascale Earth System Model Diagnostics (E3SM) Package: https://e3sm-project.github.io/e3sm_diags/_build/html/main/index.html -.. _E3SM Unified Anaconda Environment: https://e3sm.org/resources/tools/other-tools/e3sm-unified-environment/ +.. image:: https://contrib.rocks/image?repo=xCDAT/xcdat + :alt: xCDAT contributors + :target: https://github.com/xCDAT/xcdat/graphs/contributors License ------- diff --git a/conda-env/dev.yml b/conda-env/dev.yml index 91328de6..83088470 100644 --- a/conda-env/dev.yml +++ b/conda-env/dev.yml @@ -29,6 +29,7 @@ dependencies: - sphinx-book-theme - sphinx-copybutton - nbsphinx + - sphinx-design - pandoc - ipython # Required for nbsphinx syntax highlighting - gsw-xarray # Required for vertical regridding example diff --git a/docs/_static/icons/book.svg b/docs/_static/icons/book.svg new file mode 100644 index 00000000..37415f78 --- /dev/null +++ b/docs/_static/icons/book.svg @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/docs/_static/icons/play.svg b/docs/_static/icons/play.svg new file mode 100644 index 00000000..b6c4339e --- /dev/null +++ b/docs/_static/icons/play.svg @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/docs/_static/icons/plot.svg b/docs/_static/icons/plot.svg new file mode 100644 index 00000000..f8afa270 --- /dev/null +++ b/docs/_static/icons/plot.svg @@ -0,0 +1,23 @@ + + + + + \ No newline at end of file diff --git a/docs/_static/icons/wrench.svg b/docs/_static/icons/wrench.svg new file mode 100644 index 00000000..b0d497d0 --- /dev/null +++ b/docs/_static/icons/wrench.svg @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/docs/_static/style.css b/docs/_static/style.css new file mode 100644 index 00000000..e3405ee2 --- /dev/null +++ b/docs/_static/style.css @@ -0,0 +1,9 @@ +/* Main index page overview cards */ + +.sd-card-img-top { + width: 33% !important; + display: block; + margin-left: auto; + margin-right: auto; + margin-top: 10px; +} diff --git a/docs/_static/thumbnails/ams-logo.jpg b/docs/_static/thumbnails/ams-logo.jpg new file mode 100644 index 00000000..013ef696 Binary files /dev/null and b/docs/_static/thumbnails/ams-logo.jpg differ diff --git a/docs/_static/thumbnails/climatology-and-departures.png b/docs/_static/thumbnails/climatology-and-departures.png new file mode 100644 index 00000000..a493d1ab Binary files /dev/null and b/docs/_static/thumbnails/climatology-and-departures.png differ diff --git a/docs/_static/thumbnails/esgf2-logo.png b/docs/_static/thumbnails/esgf2-logo.png new file mode 100644 index 00000000..de461091 Binary files /dev/null and b/docs/_static/thumbnails/esgf2-logo.png differ diff --git a/docs/_static/thumbnails/llnl-logo.png b/docs/_static/thumbnails/llnl-logo.png new file mode 100644 index 00000000..47d3e4d0 Binary files /dev/null and b/docs/_static/thumbnails/llnl-logo.png differ diff --git a/docs/_static/thumbnails/regridding-horizontal.png b/docs/_static/thumbnails/regridding-horizontal.png new file mode 100644 index 00000000..82176fd9 Binary files /dev/null and b/docs/_static/thumbnails/regridding-horizontal.png differ diff --git a/docs/_static/thumbnails/regridding-vertical.png b/docs/_static/thumbnails/regridding-vertical.png new file mode 100644 index 00000000..b1360f60 Binary files /dev/null and b/docs/_static/thumbnails/regridding-vertical.png differ diff --git a/docs/_static/thumbnails/spatial-avg.png b/docs/_static/thumbnails/spatial-avg.png new file mode 100644 index 00000000..99b72373 Binary files /dev/null and b/docs/_static/thumbnails/spatial-avg.png differ diff --git a/docs/_static/thumbnails/temporal-average.png b/docs/_static/thumbnails/temporal-average.png new file mode 100644 index 00000000..462da4bc Binary files /dev/null and b/docs/_static/thumbnails/temporal-average.png differ diff --git a/docs/authors.rst b/docs/authors.rst deleted file mode 100644 index e122f914..00000000 --- a/docs/authors.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../AUTHORS.rst diff --git a/docs/conf.py b/docs/conf.py index 01b3142c..eb38be54 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,11 +18,16 @@ # absolute, like shown here. # import os +import pathlib import sys from pathlib import Path from typing import Dict +from textwrap import dedent, indent import sphinx_autosummary_accessors +import yaml +from sphinx.application import Sphinx +from sphinx.util import logging # A workaround that sets the "ESMFMKFILE" env variable for the Read The Docs # build to work. Read The Docs does not activate the conda environment which @@ -34,6 +39,8 @@ sys.path.insert(0, os.path.abspath("..")) # noqa: I001, I003 import xcdat # noqa: I001, E402 +LOGGER = logging.getLogger("conf") + # -- General configuration --------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. @@ -50,6 +57,7 @@ "sphinx_autosummary_accessors", "sphinx_copybutton", "nbsphinx", + "sphinx_design", ] # autosummary and autodoc configurations @@ -160,7 +168,7 @@ # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static"] - +html_css_files = ["style.css"] # -- Options for HTMLHelp output --------------------------------------- @@ -224,5 +232,109 @@ def html_page_context(app, pagename, templatename, context, doctree): context["theme_use_edit_page_button"] = False -def setup(app): +def update_team(app: Sphinx): + """Update the team members list.""" + + LOGGER.info("Updating team members page...") + + team = yaml.safe_load(pathlib.Path(app.srcdir, "team.yml").read_bytes()) + items = [] + for member in team: + item = f""" + .. grid-item-card:: + :text-align: center + :link: https://github.com/{member['gh_login']} + + .. image:: {member['avatar']} + :alt: {member['name']} + +++ + {member['name']} + """ + items.append(item) + + items_md = indent(dedent("\n".join(items)), prefix=" ") + + markdown = f""" +.. grid:: 1 2 3 3 + :gutter: 2 + + {items_md} + """ + + pathlib.Path(app.srcdir, "team-panel.txt").write_text(markdown) + LOGGER.info("Team members page updated.") + + +def update_gallery(app: Sphinx): + """Update the gallery of examples notebooks.""" + + LOGGER.info("Updating gallery page...") + + notebooks = yaml.safe_load(pathlib.Path(app.srcdir, "gallery.yml").read_bytes()) + + items = [ + f""" + .. grid-item-card:: + :text-align: center + :link: {item['path']} + + .. image:: {item['thumbnail']} + :alt: {item['title']} + +++ + {item['title']} + """ + for item in notebooks + ] + + items_md = indent(dedent("\n".join(items)), prefix=" ") + markdown = f""" +.. grid:: 1 2 3 3 + :gutter: 2 + + {items_md} + """ + + pathlib.Path(app.srcdir, "notebook-examples.txt").write_text(markdown) + + LOGGER.info("Gallery page updated.") + + +def update_demos(app: Sphinx): + """Update the demos page.""" + + LOGGER.info("Updating demos page...") + + links = yaml.safe_load(pathlib.Path(app.srcdir, "demos.yml").read_bytes()) + + items = [ + f""" + .. grid-item-card:: + :text-align: center + :link: {item['path']} + + .. image:: {item['thumbnail']} + :alt: {item['title']} + +++ + {item['title']} + """ + for item in links + ] + + items_md = indent(dedent("\n".join(items)), prefix=" ") + markdown = f""" +.. grid:: 1 2 3 3 + :gutter: 2 + + {items_md} + """ + + pathlib.Path(app.srcdir, "demos.txt").write_text(markdown) + + LOGGER.info("Demos page updated.") + + +def setup(app: Sphinx): app.connect("html-page-context", html_page_context) + app.connect("builder-inited", update_team) + app.connect("builder-inited", update_gallery) + app.connect("builder-inited", update_demos) diff --git a/docs/demos.rst b/docs/demos.rst index ad1883b6..d2579995 100644 --- a/docs/demos.rst +++ b/docs/demos.rst @@ -3,10 +3,12 @@ Presentations and Demos This page includes relevant xCDAT presentations, demos, and papers. +.. include:: demos.txt + .. toctree:: :maxdepth: 2 :hidden: AMS 2023 Abstract demos/1-25-23-cwss-seminar/introduction-to-xcdat.ipynb - A Gentle Introduction to xCDAT (Xarray Climate Data Analysis Tools) - Video introduction + ESGF2 - A Gentle Introduction to xCDAT (video introduction) diff --git a/docs/demos.yml b/docs/demos.yml new file mode 100644 index 00000000..86086517 --- /dev/null +++ b/docs/demos.yml @@ -0,0 +1,11 @@ +- title: AMS 2023 Abstract + path: https://ams.confex.com/ams/103ANNUAL/meetingapp.cgi/Paper/412648 + thumbnail: _static/thumbnails/ams-logo.jpg + +- title: LLNL Climate and Weather Seminar Series (01/25/2023) - A Gentle Introduction to xCDAT + path: demos/1-25-23-cwss-seminar/introduction-to-xcdat.ipynb + thumbnail: _static/thumbnails/llnl-logo.png + +- title: ESGF2 - A Gentle Introduction to xCDAT (video introduction) + path: https://youtu.be/sJpQ9vKDKa8?feature=shared + thumbnail: _static/thumbnails/esgf2-logo.png diff --git a/docs/examples/general-utilities.ipynb b/docs/examples/general-utilities.ipynb index c086c757..f165f418 100644 --- a/docs/examples/general-utilities.ipynb +++ b/docs/examples/general-utilities.ipynb @@ -4564,7 +4564,7 @@ "\n", "Helpful knowledge:\n", "\n", - "- This API uses `cf_xarray` to interpret CF axis names and coordinate names in the xarray object attributes. Refer to [Metadata Interpretation](../faqs.rst) for more information.\n", + "- This API uses `cf_xarray` to interpret CF axis names and coordinate names in the xarray object attributes. Refer to [Metadata Interpretation](../getting-started-guide/faqs.rst) for more information.\n", "\n", "Xarray documentation on coordinates ([source](https://docs.xarray.dev/en/stable/user-guide/data-structures.html#coordinates)):\n", "\n", diff --git a/docs/gallery.rst b/docs/gallery.rst index 77a93f26..70f9681d 100644 --- a/docs/gallery.rst +++ b/docs/gallery.rst @@ -1,9 +1,9 @@ Gallery ======= -This gallery demonstrates how to use some of the features in ``xcdat``. Contributions are highly welcomed and appreciated. -Please checkout the :doc:`contributing` guide. +This gallery demonstrates how to use some of the features in ``xcdat``. Contributions are highly welcomed and appreciated. Please checkout the :doc:`contributing` guide. +.. include:: notebook-examples.txt .. toctree:: :maxdepth: 2 diff --git a/docs/gallery.yml b/docs/gallery.yml new file mode 100644 index 00000000..30439ef0 --- /dev/null +++ b/docs/gallery.yml @@ -0,0 +1,27 @@ +- title: A Gentle Introduction to xCDAT (Xarray Climate Data Analysis Tools) + path: examples/introduction-to-xcdat.ipynb + thumbnail: _static/xcdat-logo.png + +- title: General Dataset Utilities + path: examples/general-utilities.ipynb + thumbnail: _static/dataset-diagram.webp + +- title: Calculate Geospatial Weighted Averages from Monthly Time Series + path: examples/spatial-average.ipynb + thumbnail: _static/thumbnails/spatial-avg.png + +- title: Calculate Time Averages from Time Series Data + path: examples/temporal-average.ipynb + thumbnail: _static/thumbnails/temporal-average.png + +- title: Calculate Climatology and Departures from Time Series Data + path: examples/climatology-and-departures.ipynb + thumbnail: _static/thumbnails/climatology-and-departures.png + +- title: Horizontal Regridding + path: examples/regridding-horizontal.ipynb + thumbnail: _static/thumbnails/regridding-horizontal.png + +- title: Vertical Regridding + path: examples/regridding-vertical.ipynb + thumbnail: _static/thumbnails/regridding-vertical.png diff --git a/docs/faqs.rst b/docs/getting-started-guide/faqs.rst similarity index 100% rename from docs/faqs.rst rename to docs/getting-started-guide/faqs.rst diff --git a/docs/getting-started-hpc-jupyter.rst b/docs/getting-started-guide/getting-started-hpc-jupyter.rst similarity index 93% rename from docs/getting-started-hpc-jupyter.rst rename to docs/getting-started-guide/getting-started-hpc-jupyter.rst index 0bb1bd23..45ca9c94 100644 --- a/docs/getting-started-hpc-jupyter.rst +++ b/docs/getting-started-guide/getting-started-hpc-jupyter.rst @@ -19,9 +19,9 @@ Setting up your xCDAT environment Ensure ``conda`` is installed ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Generally, the instructions from `getting started guide `_ can also -be followed for HPC machines. This guide covers installing Miniconda3 and creating -a conda environment with the ``xcdat`` package. +Generally, the installation instructions from the `Installation <../installation.rst>`_ +page can also be followed for HPC machines. This guide covers installing Miniconda3 and +creating a conda environment with the ``xcdat`` package. Before installing Miniconda3, you should consult your HPC documentation to see if ``conda`` is already available; in some cases, ``python`` and ``conda`` may be @@ -101,4 +101,4 @@ kernel. You should then be able to use your ``xcdat`` environment on Jupyter. |image0| -.. |image0| image:: _static/jupyter-launcher-example.png \ No newline at end of file +.. |image0| image:: ../_static/jupyter-launcher-example.png \ No newline at end of file diff --git a/docs/getting-started-guide/index.rst b/docs/getting-started-guide/index.rst new file mode 100644 index 00000000..f11a42d1 --- /dev/null +++ b/docs/getting-started-guide/index.rst @@ -0,0 +1,14 @@ +################ +Getting Started +################ + +The getting started guide aims to get you using xCDAT productively as quickly as possible. + +.. toctree:: + :maxdepth: 2 + :hidden: + + Project Overview + Installation + xCDAT on HPC / Jupyter + faqs diff --git a/docs/getting-started.rst b/docs/getting-started-guide/installation.rst similarity index 98% rename from docs/getting-started.rst rename to docs/getting-started-guide/installation.rst index 27231aa5..73f65858 100644 --- a/docs/getting-started.rst +++ b/docs/getting-started-guide/installation.rst @@ -1,8 +1,8 @@ .. highlight:: shell -=============== -Getting Started -=============== +============= +Installation +============= Prerequisites ------------- @@ -39,7 +39,7 @@ Prerequisites .. _conda-forge: https://anaconda.org/conda-forge/xcdat .. _Miniforge: https://github.com/conda-forge/miniforge -Installation +Instructions ------------ 1. Create a Mamba environment from scratch with ``xcdat`` (`mamba create`_) diff --git a/docs/getting-started-guide/overview.rst b/docs/getting-started-guide/overview.rst new file mode 100644 index 00000000..70bc8e38 --- /dev/null +++ b/docs/getting-started-guide/overview.rst @@ -0,0 +1,208 @@ +xCDAT: Xarray Climate Data Analysis Tools +========================================= + +xCDAT is an extension of `xarray`_ for climate data analysis on structured grids. It +serves as a modern successor to the Community Data Analysis Tools (`CDAT`_) library. + +**Useful links**: +`Documentation `__ | +`Code Repository `__ | +`Issues `__ | +`Discussions `__ | +`Releases `__ | +`Mailing List `__ + +Project Motivation +------------------ + +The goal of xCDAT is to provide generalizable features and utilities for simple and +robust analysis of climate data. xCDAT's design philosophy is focused on reducing the +overhead required to accomplish certain tasks in xarray. xCDAT aims to be compatible +with structured grids that are `CF-compliant`_ (e.g., CMIP6). Some key xCDAT features +are inspired by or ported from the core CDAT library, while others leverage powerful +libraries in the xarray ecosystem (e.g., `xESMF`_, `xgcm`_, `cf_xarray`_) to deliver +robust APIs. + +The xCDAT core team's mission is to provide a maintainable and extensible package +that serves the needs of the climate community in the long-term. We are excited +to be working on this project and hope to have you onboard! + +.. _CF-compliant: https://cfconventions.org/ +.. _xarray: https://github.com/pydata/xarray +.. _CDAT: https://github.com/CDAT/cdat + +Getting Started +--------------- + +The best resource for getting started is the `xCDAT documentation website`_. +Our documentation provides general guidance for setting up xCDAT in an Anaconda +environment on your local `computer`_ or on an `HPC/Jupyter`_ environment. We also +include an `API Overview`_ and `Gallery`_ to highlight xCDAT functionality. + +.. _xCDAT documentation website: https://xcdat.readthedocs.io/en/stable/ +.. _computer: https://xcdat.readthedocs.io/en/stable/getting-started.html +.. _HPC/Jupyter: https://xcdat.readthedocs.io/en/stable/getting-started-hpc-jupyter.html +.. _API Overview: https://xcdat.readthedocs.io/en/stable/api.html +.. _Gallery: https://xcdat.readthedocs.io/en/stable/gallery.html + +Community +--------- + +xCDAT is a community-driven open source project. We encourage discussion on topics such +as version releases, feature suggestions, and architecture design on the +`GitHub Discussions`_ page. + +Subscribe to our `mailing list`_ for news and announcements related to xCDAT, +such as software version releases or future roadmap plans. + +Please note that xCDAT has a `Code of Conduct`_. By participating in the xCDAT +community, you agree to abide by its rules. + +.. _GitHub Discussions: https://github.com/xCDAT/xcdat/discussions +.. _Code of Conduct: code-of-conduct.rst +.. _mailing list: https://groups.google.com/g/xcdat + +Contributing +------------ + +We welcome and appreciate contributions to xCDAT. Users and contributors can view and +open issues on our `GitHub Issue Tracker`_. + +For more instructions on how to contribute, please checkout our `Contributing Guide`_. + +.. _GitHub Issue Tracker: https://github.com/xCDAT/xcdat/issues +.. _Contributing Guide: https://xcdat.readthedocs.io/en/stable/contributing.html + +Features +-------- + +* Extension of xarray's ``open_dataset()`` and ``open_mfdataset()`` with post-processing options + + * Generate bounds for axes supported by ``xcdat`` if they don't exist in the Dataset + * Optional selection of single data variable to keep in the Dataset (bounds are also + kept if they exist) + * Optional decoding of time coordinates + + * In addition to CF time units, also decodes common non-CF time units + ("months since ...", "years since ...") + + * Optional centering of time coordinates using time bounds + * Optional conversion of longitudinal axis orientation between [0, 360) and [-180, 180) + +* Temporal averaging + + * Time series averages (single snapshot and grouped), climatologies, and departures + * Weighted or unweighted + * Optional seasonal configuration (e.g., DJF vs. JFD, custom seasons) + +* Geospatial weighted averaging + + * Supports rectilinear grid + * Optional specification of regional domain + +* Horizontal structured regridding + + * Supports rectilinear and curvilinear grids + * Extends the `xESMF`_ horizontal regridding API + * Python implementation of `regrid2`_ for handling cartesian latitude longitude grids + +* Vertical structured regridding + + * Support rectilinear and curvilinear grids + * Extends the `xgcm`_ vertical regridding API + +Things We Are Striving For +-------------------------- + +* xCDAT supports CF compliant datasets, but will also strive to support datasets with + common non-CF compliant metadata (e.g., time units in "months since ..." or "years + since ...") + + * xCDAT leverages `cf_xarray`_ to interpret CF attributes on ``xarray`` objects + * Refer to `CF Convention`_ for more information on CF attributes + +* Robust handling of dimensions and their coordinates and coordinate bounds + + * Coordinate variables are retrieved with ``cf_xarray`` using CF axis names or + coordinate names found in xarray object attributes. Refer to `Metadata Interpretation`_ + for more information. + * Bounds are retrieved with ``cf_xarray`` using the ``"bounds"`` attr + * Ability to operate on both longitudinal axis orientations, [0, 360) and [-180, 180) + +* Support for parallelism using `dask`_ where it is both possible and makes sense + +.. _Metadata Interpretation: https://xcdat.readthedocs.io/en/stable/faqs.html#metadata-interpretation +.. _xESMF: https://pangeo-xesmf.readthedocs.io/en/latest/ +.. _regrid2: https://cdms.readthedocs.io/en/latest/regrid2.html +.. _xgcm: https://xgcm.readthedocs.io/en/latest/index.html +.. _dask: https://dask.org/ +.. _cf_xarray: https://cf-xarray.readthedocs.io/en/latest/index.html +.. _CF convention: http://cfconventions.org/ + +Releases +-------- +xCDAT (released as ``xcdat``) follows a feedback-driven release cycle using continuous +integration/continuous deployment. Software releases are performed based on the bandwidth +of the development team, the needs of the community, and the priority of bug fixes or +feature updates. + +After releases are performed on `GitHub Releases`_, the corresponding ``xcdat`` package +version will be available to download through Anaconda `conda-forge`_ usually within a day. + +Subscribe to our `mailing list`_ to stay notified of new releases. + +.. _conda-forge: https://anaconda.org/conda-forge/xcdat +.. _GitHub Releases: https://anaconda.org/conda-forge/xcdat + +Useful Resources +----------------- + +We highly encourage you to checkout the awesome resources below to learn more about +Xarray and Xarray usage in climate science! + +- `Official Xarray Tutorials `_ +- `Xarray GitHub Discussion Forum `_ +- `Pangeo Forum `_ +- `Project Pythia `_ + +Acknowledgement +--------------- + +Huge thank you to all of the xCDAT `contributors`_! + +.. _contributors: https://github.com/xCDAT/xcdat/graphs/contributors + +xCDAT is jointly developed by scientists and developers from the Energy Exascale +Earth System Model (`E3SM`_) Project and Program for Climate Model Diagnosis and +Intercomparison (`PCMDI`_). The work is performed for the E3SM project, which is +sponsored by Earth System Model Development (`ESMD`_) program, and the Simplifying ESM +Analysis Through Standards (`SEATS`_) project, which is sponsored by the Regional and +Global Model Analysis (`RGMA`_) program. ESMD and RGMA are programs for the Earth and +Environmental Systems Sciences Division (`EESSD`_) in the Office of Biological and +Environmental Research (`BER`_) within the `Department of Energy`_'s `Office of Science`_. + +.. _E3SM: https://e3sm.org/ +.. _PCMDI: https://pcmdi.llnl.gov/ +.. _SEATS: https://www.seatstandards.org/ +.. _ESMD: https://climatemodeling.science.energy.gov/program/earth-system-model-development +.. _RGMA: https://climatemodeling.science.energy.gov/program/regional-global-model-analysis +.. _EESSD: https://science.osti.gov/ber/Research/eessd +.. _BER: https://science.osti.gov/ber +.. _Department of Energy: https://www.energy.gov/ +.. _Office of Science: https://science.osti.gov/ + +License +------- + +xCDAT is licensed under the terms of the Apache License (Version 2.0 with LLVM exception). + +All new contributions must be made under the Apache-2.0 with LLVM exception license. + +See `LICENSE`_ and `NOTICE`_ for details. + +.. _LICENSE: https://github.com/xCDAT/xcdat/blob/main/LICENSE +.. _NOTICE: https://github.com/xCDAT/xcdat/blob/main/NOTICE + +SPDX-License-Identifier: Apache-2.0 + +``LLNL-CODE-846944`` diff --git a/docs/index.rst b/docs/index.rst index f851a5dd..06c514a8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,224 +1,65 @@ -xCDAT: Xarray Climate Data Analysis Tools -========================================= +xCDAT Documentation +==================== -xCDAT is an extension of `xarray`_ for climate data analysis on structured grids. It -serves as a modern successor to the Community Data Analysis Tools (`CDAT`_) library. +xCDAT (Xarray Climate Data Analysis Tools) is an extension of `xarray`_ for climate data analysis on structured grids. It serves as a modern successor to the Community Data Analysis Tools (`CDAT`_) library. + +.. _xarray: https://github.com/pydata/xarray +.. _CDAT: https://github.com/CDAT/cdat **Useful links**: -`Documentation `__ | `Code Repository `__ | `Issues `__ | `Discussions `__ | `Releases `__ | `Mailing List `__ -Project Motivation ------------------- - -The goal of xCDAT is to provide generalizable features and utilities for simple and -robust analysis of climate data. xCDAT's design philosophy is focused on reducing the -overhead required to accomplish certain tasks in xarray. xCDAT aims to be compatible -with structured grids that are `CF-compliant`_ (e.g., CMIP6). Some key xCDAT features -are inspired by or ported from the core CDAT library, while others leverage powerful -libraries in the xarray ecosystem (e.g., `xESMF`_, `xgcm`_, `cf_xarray`_) to deliver -robust APIs. - -The xCDAT core team's mission is to provide a maintainable and extensible package -that serves the needs of the climate community in the long-term. We are excited -to be working on this project and hope to have you onboard! - -.. _CF-compliant: https://cfconventions.org/ -.. _xarray: https://github.com/pydata/xarray -.. _CDAT: https://github.com/CDAT/cdat - -Getting Started ---------------- - -The best resource for getting started is the `xCDAT documentation website`_. -Our documentation provides general guidance for setting up xCDAT in an Anaconda -environment on your local `computer`_ or on an `HPC/Jupyter`_ environment. We also -include an `API Overview`_ and `Gallery`_ to highlight xCDAT functionality. - -.. _xCDAT documentation website: https://xcdat.readthedocs.io/en/stable/ -.. _computer: https://xcdat.readthedocs.io/en/stable/getting-started.html -.. _HPC/Jupyter: https://xcdat.readthedocs.io/en/stable/getting-started-hpc-jupyter.html -.. _API Overview: https://xcdat.readthedocs.io/en/stable/api.html -.. _Gallery: https://xcdat.readthedocs.io/en/stable/gallery.html - -Community ---------- - -xCDAT is a community-driven open source project. We encourage discussion on topics such -as version releases, feature suggestions, and architecture design on the -`GitHub Discussions`_ page. - -Subscribe to our `mailing list`_ for news and announcements related to xCDAT, -such as software version releases or future roadmap plans. - -Please note that xCDAT has a `Code of Conduct`_. By participating in the xCDAT -community, you agree to abide by its rules. - -.. _GitHub Discussions: https://github.com/xCDAT/xcdat/discussions -.. _Code of Conduct: code-of-conduct.rst -.. _mailing list: https://groups.google.com/g/xcdat - -Contributing ------------- - -We welcome and appreciate contributions to xCDAT. Users and contributors can view and -open issues on our `GitHub Issue Tracker`_. - -For more instructions on how to contribute, please checkout our `Contributing Guide`_. - -.. _GitHub Issue Tracker: https://github.com/xCDAT/xcdat/issues -.. _Contributing Guide: https://xcdat.readthedocs.io/en/stable/contributing.html - -Features --------- - -* Extension of xarray's ``open_dataset()`` and ``open_mfdataset()`` with post-processing options - - * Generate bounds for axes supported by ``xcdat`` if they don't exist in the Dataset - * Optional selection of single data variable to keep in the Dataset (bounds are also - kept if they exist) - * Optional decoding of time coordinates - - * In addition to CF time units, also decodes common non-CF time units - ("months since ...", "years since ...") - - * Optional centering of time coordinates using time bounds - * Optional conversion of longitudinal axis orientation between [0, 360) and [-180, 180) - -* Temporal averaging - - * Time series averages (single snapshot and grouped), climatologies, and departures - * Weighted or unweighted - * Optional seasonal configuration (e.g., DJF vs. JFD, custom seasons) - -* Geospatial weighted averaging - - * Supports rectilinear grid - * Optional specification of regional domain - -* Horizontal structured regridding - - * Supports rectilinear and curvilinear grids - * Extends the `xESMF`_ horizontal regridding API - * Python implementation of `regrid2`_ for handling cartesian latitude longitude grids - -* Vertical structured regridding - - * Support rectilinear and curvilinear grids - * Extends the `xgcm`_ vertical regridding API - -Things We Are Striving For --------------------------- - -* xCDAT supports CF compliant datasets, but will also strive to support datasets with - common non-CF compliant metadata (e.g., time units in "months since ..." or "years - since ...") - - * xCDAT leverages `cf_xarray`_ to interpret CF attributes on ``xarray`` objects - * Refer to `CF Convention`_ for more information on CF attributes - -* Robust handling of dimensions and their coordinates and coordinate bounds - - * Coordinate variables are retrieved with ``cf_xarray`` using CF axis names or - coordinate names found in xarray object attributes. Refer to `Metadata Interpretation`_ - for more information. - * Bounds are retrieved with ``cf_xarray`` using the ``"bounds"`` attr - * Ability to operate on both longitudinal axis orientations, [0, 360) and [-180, 180) - -* Support for parallelism using `dask`_ where it is both possible and makes sense - -.. _Metadata Interpretation: https://xcdat.readthedocs.io/en/stable/faqs.html#metadata-interpretation -.. _xESMF: https://pangeo-xesmf.readthedocs.io/en/latest/ -.. _regrid2: https://cdms.readthedocs.io/en/latest/regrid2.html -.. _xgcm: https://xgcm.readthedocs.io/en/latest/index.html -.. _dask: https://dask.org/ -.. _cf_xarray: https://cf-xarray.readthedocs.io/en/latest/index.html -.. _CF convention: http://cfconventions.org/ - -Releases --------- -xCDAT (released as ``xcdat``) follows a feedback-driven release cycle using continuous -integration/continuous deployment. Software releases are performed based on the bandwidth -of the development team, the needs of the community, and the priority of bug fixes or -feature updates. - -After releases are performed on `GitHub Releases`_, the corresponding ``xcdat`` package -version will be available to download through Anaconda `conda-forge`_ usually within a day. - -Subscribe to our `mailing list`_ to stay notified of new releases. - -.. _conda-forge: https://anaconda.org/conda-forge/xcdat -.. _GitHub Releases: https://anaconda.org/conda-forge/xcdat - -Useful Resources ------------------ - -We highly encourage you to checkout the awesome resources below to learn more about -Xarray and Xarray usage in climate science! - -- `Official Xarray Tutorials `_ -- `Xarray GitHub Discussion Forum `_ -- `Pangeo Forum `_ -- `Project Pythia `_ - -Acknowledgement ---------------- - -Huge thank you to all of the xCDAT `contributors`_! - -.. _contributors: https://github.com/xCDAT/xcdat/graphs/contributors +.. grid:: 1 1 2 2 + :gutter: 2 -xCDAT is jointly developed by scientists and developers from the Energy Exascale -Earth System Model (`E3SM`_) Project and Program for Climate Model Diagnosis and -Intercomparison (`PCMDI`_). The work is performed for the E3SM project, which is -sponsored by Earth System Model Development (`ESMD`_) program, and the Simplifying ESM -Analysis Through Standards (`SEATS`_) project, which is sponsored by the Regional and -Global Model Analysis (`RGMA`_) program. ESMD and RGMA are programs for the Earth and -Environmental Systems Sciences Division (`EESSD`_) in the Office of Biological and -Environmental Research (`BER`_) within the `Department of Energy`_'s `Office of Science`_. + .. grid-item-card:: Getting started + :img-top: _static/icons/play.svg + :link: getting-started-guide/index + :link-type: doc -.. _E3SM: https://e3sm.org/ -.. _PCMDI: https://pcmdi.llnl.gov/ -.. _SEATS: https://www.seatstandards.org/ -.. _ESMD: https://climatemodeling.science.energy.gov/program/earth-system-model-development -.. _RGMA: https://climatemodeling.science.energy.gov/program/regional-global-model-analysis -.. _EESSD: https://science.osti.gov/ber/Research/eessd -.. _BER: https://science.osti.gov/ber -.. _Department of Energy: https://www.energy.gov/ -.. _Office of Science: https://science.osti.gov/ + New to xCDAT? Check out the getting started guides. -License -------- + .. grid-item-card:: Examples + :img-top: _static/icons/plot.svg + :link: gallery + :link-type: doc -xCDAT is licensed under the terms of the Apache License (Version 2.0 with LLVM exception). + This gallery demonstrates how to use some of the features in xCDAT through + Jupyter Notebooks with real-world examples. -All new contributions must be made under the Apache-2.0 with LLVM exception license. + .. grid-item-card:: API reference + :img-top: _static/icons/wrench.svg + :link: api + :link-type: doc -See `LICENSE`_ and `NOTICE`_ for details. + The reference guide contains a detailed description of the xCDAT API. + The reference describes how the methods work and which parameters can + be used. It assumes that you have an understanding of key Xarray concepts. -.. _LICENSE: https://github.com/xCDAT/xcdat/blob/main/LICENSE -.. _NOTICE: https://github.com/xCDAT/xcdat/blob/main/NOTICE + .. grid-item-card:: Developer guide + :img-top: _static/icons/book.svg + :link: contributing + :link-type: doc -SPDX-License-Identifier: Apache-2.0 + Saw a typo in the documentation? Want to improve existing functionalities? + The contributing guidelines will guide you through the process of improving + xCDAT. -``LLNL-CODE-846944`` .. toctree:: :maxdepth: 2 :hidden: :caption: For Users - Getting Started - xCDAT on HPC / Jupyter + Getting Started Gallery Presentations and Demos API Reference Changelog - Frequently Asked Questions .. toctree:: :maxdepth: 2 @@ -226,9 +67,9 @@ SPDX-License-Identifier: Apache-2.0 :caption: For Developers/Contributors Code of Conduct + Team Contributing Guide Project Maintenance - Team .. toctree:: :maxdepth: 1 diff --git a/docs/team.rst b/docs/team.rst new file mode 100644 index 00000000..2217bdd0 --- /dev/null +++ b/docs/team.rst @@ -0,0 +1,14 @@ +Team +----- + +Current core developers +~~~~~~~~~~~~~~~~~~~~~~~ + +xCDAT core developers are responsible for the ongoing organizational maintenance and technical direction of the xCDAT project. + +The current core developers team comprises: + +.. include:: team-panel.txt + + +The full list of contributors is on our `GitHub Contributors Page `__. diff --git a/docs/team.yml b/docs/team.yml new file mode 100644 index 00000000..905f8cb3 --- /dev/null +++ b/docs/team.yml @@ -0,0 +1,19 @@ +- name: Tom Vo + gh_login: tomvothecoder + avatar: https://avatars.githubusercontent.com/u/25624127?v=4 + +- name: Stephen Po-Chedley + gh_login: pochedls + avatar: https://avatars.githubusercontent.com/u/3698109?v=4 + +- name: Jason Boutte + gh_login: jasonb5 + avatar: https://avatars.githubusercontent.com/u/2191036?v=4 + +- name: Jiwoo Lee + gh_login: lee1043 + avatar: https://avatars.githubusercontent.com/u/17091564?v=4 + +- name: Jill Chengzhu Zhang + gh_login: chengzhuzhang + avatar: https://avatars.githubusercontent.com/u/13056557?v=4