hdrake · hdrake · Jun 10, 2025
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     = source
+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/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=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%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
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,13 @@
+ipython
+jupyter
+jupyter-sphinx
+matplotlib
+netcdf4
+gsw
+numpy
+numba
+pandas
+sphinx-book-theme
+xarray
+xgcm==0.5.2
+xhistogram==0.3.1
diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -0,0 +1,10 @@
+API Documentation
+=================
+
+Information on specific functions, classes, and methods.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   api/*
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -0,0 +1,63 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../../'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'xwmt'
+copyright = '2022'
+author = 'xWMT Development Team'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['sphinx.ext.autodoc','sphinx.ext.napoleon','IPython.sphinxext.ipython_console_highlighting',
+              'IPython.sphinxext.ipython_directive','jupyter_sphinx','nbsphinx'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_book_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# 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']
+
+#-- Turn off copyright notice
+html_show_copyright = False
+
+#-- Master document
+master_doc = 'index'
+
+#-- Build api
+from sphinx.ext.apidoc import main
+main(['-f', '-M', '-e', '-T', '../../xwmt', '-o', 'api' ])
diff --git a/docs/source/contrib.rst b/docs/source/contrib.rst
@@ -0,0 +1,11 @@
+Contributing to the Package
+===========================
+
+Reporting Issues
+----------------
+If you uncover a bug or issue with the code, please file a report through the GitHub site:  https://github.com/jetesdal/xwmt
+
+
+Developing New Routines
+-----------------------
+Pull requests for new routines and code are welcome. Please note that **xwmt** is in the public domain and licensed and/or copyrighted material is not acceptable.
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -0,0 +1,68 @@
+xbudget: xarray-friendly tracer budget analysis
+===============================================
+
+**xbudget** is a Python package for tracer budget analysis that leverages xarray functionality
+
+.. * :doc:`install`
+.. * :doc:`virtualenv`
+.. * :doc:`testing`
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :caption: Background
+
+   objective
+
+..   install
+..   virtualenv
+..   testing
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :caption: Installation and Contributing
+
+   install
+   contrib
+
+.. * :doc:`generate_diags`
+.. * :doc:`sqlite_format`
+.. * :doc:`db2nc`
+
+.. toctree::
+..   :maxdepth: 1
+..   :hidden:
+..   :caption: User Guide
+
+..   generate_diags
+..   sqlite_format
+..   vitals_data_frame
+..   db2nc
+..   plotting
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :caption: Help & reference
+
+   api
+
+Quick Install
+-------------
+To install from PyPi:
+
+.. parsed-literal::
+   pip install xbudget
+
+To install from GitHub:
+
+.. parsed-literal::
+   pip install git+https://github.com/NOAA-GFDL/xwmt.git
+
+.. Indices and tables
+.. ==================
+..
+.. * :ref:`genindex`
+.. * :ref:`modindex`
+.. * :ref:`search`
diff --git a/docs/source/install.rst b/docs/source/install.rst
@@ -0,0 +1,18 @@
+Installation
+============
+
+**xwmt** Python package for water mass transformation analysis that leverages xarray functionality
+
+Prerequisites and dependencies
+------------------------------
+**xwmt** requires Python version 3.9 or greater and several additional packages
+that are listed below:
+
+* Python >=3.9
+* gsw
+* numpy
+* xarray
+* xgcm
+* xhistogram
+
+**xwmt** was build with `xgcm` version *0.5.2* and `xhistogram` version *0.1.1*. Some calculations may not work when a different version of `xgcm` or `xhistogram` is used.
diff --git a/docs/source/objective.rst b/docs/source/objective.rst
@@ -0,0 +1,37 @@
+Introduction
+===========================
+
+The Water Mass Transformation (WMT) framework was initially put forward by `Walin (1982) <https://doi.org/10.1111/j.2153-3490.1982.tb01806.x>`_ to describe the relationship between surface heat fluxes and interior ocean circulation. A series of studies further refined the framework to include the effect of haline-driven buoyancy forcing (e.g., `Tziperman 1986 <https://doi.org/10.1175/1520-0485(1986)016%3C0680:OTROIM%3E2.0.CO;2>`_; `Speer and Tziperman, 1992 <https://doi.org/10.1175/1520-0485(1992)022%3C0093:ROWMFI%3E2.0.CO;2>`_) and account for the role of interior mixing (e.g., ` Nurser et al., 1999 <https://doi.org/10.1175/1520-0485(1999)029%3C1468:DWMFFA%3E2.0.CO;2>`_; `Iudicone et al., 2008 <https://journals.ametsoc.org/view/journals/phoc/38/7/2007jpo3464.1.xml>`_). A comprehensive overview of past studies in WMT and details of how WMT is derived from diapycnal processes can be found in `Groeskamp et al. 2019 <https://doi.org/10.1146/annurev-marine-010318-095421>`_).
+
+
+Package Objectives
+===========================
+The goal of this package is to provide various WMT routines to derive key metrics related to water masses in the ocean.
+
+
+Required Input
+===========================
+The required input for the package is a xarray dataset including the necessary scalar field (e.g., ocean temperature, salinity or density) used for water mass classification and surface fluxes of heat, freshwater and salt. Varibale naming follows CMOR convention.
+- `tos`: Sea Surface Temperature (units: degC)
+> Temperature of upper boundary of the liquid ocean, including temperatures below sea-ice and floating ice shelves.
+- `sos`: Sea Surface Salinity (units: 0.001) 
+> Sea water salinity is the salt content of sea water, often on the Practical Salinity Scale of 1978. However, the unqualified term 'salinity' is generic and does not necessarily imply any particular method of calculation. The units of salinity are dimensionless and the units attribute should normally be given as 1e-3 or 0.001 i.e. parts per thousand. 
+- `hfds`: Downward Heat Flux at Sea Water Surface (units: W m-2)
+> This is the net flux of heat entering the liquid water column through its upper surface (excluding any "flux adjustment").
+- `wfo`: Water Flux into Sea Water (units: kg m-2 s-1)
+> Computed as the water flux into the ocean divided by the area of the ocean portion of the grid cell. This is the sum *wfonocorr* and *wfcorr*.
+- `sfdsi`: Downward Sea Ice Basal Salt Flux (units: kg m-2 s-1)
+> This field is physical, and it arises since sea ice has a nonzero salt content, so it exchanges salt with the liquid ocean upon melting and freezing.
+
+Surface WMT using `swmt` class
+==============================
+The first step is to initialize the class by creating an object. This object includes all the calculations for surface WMT (`swmt`) and full 3D WMT (`wmt`). Since we use here surface fluxes, we will use the `swmt` class.
+.. math::
+  swmt_class = swmt(ds)
+
+The `swmt` class object includes multiple functions to look at the relevant data. The most common function is `.G()` which is the WMT along $\lambda$ (i.e., $G(\lambda)$). Here, we need to define $\lambda$. For example, 'theta' for potential temperature ($\theta$) or 'sigma0' for potential density referenced at 0 dbar ($\sigma_0$). You can use command `.lambdas()` for a list of available $\lambda$'s. Here, we will go with $\sigma_0$. This is all you need, but if you want to define the size of the bins you can do that with the argument `bin`.
+
+Disclaimer
+===========================
+`xwmt` does not employ any checks to ensure conservation of heat and salt. It is the user's responsibility to ensure that budgets for heat and salt are properly closed in the datasets. Improperly conserved fields will yield incorrect results.
+