`xroms`

xroms contains functions for commonly used scripts for working with ROMS output in xarray.

There are functions to...

help read in model output with automatically-calculated z coordinates
calculate many derived variables with correct grid metrics in one line including:
- horizontal speed
- kinetic energy
- eddy kinetic energy
- vertical shear
- vertical vorticity
- horizontal divergence
- normalized surface divergence
- Ertel potential vorticity
- density as calculated in ROMS
- potential density
- buoyancy
- $N^2$ (buoyancy frequency/vertical buoyancy gradient)
- $M^2$ (horizontal buoyancy gradient)
useful functions including:
- derivatives in all dimensions, accounting for curvilinear grids and sigma layers
- grid metrics (i.e., grid lengths, areas, and volumes)
- subset horizontal grid such that the staggered grids are consistent
- easily change horizontal and vertical grids using xgcm grid objects
- easily reorder to dimensional convention
- slice along a fixed value
- wrapper for interpolation in longitude/latitude and for fixed depths
- mixed-layer depth
Demonstrations:
- selecting data in many different ways
- interpolation
- changing time sampling
- calculating climatologies
- various calculations
provide/track attributes and coordinates through functions
- wraps cf-xarray to generalize coordinate and dimension calling.
ability to automatically choose colormaps for plotting with xarray
- wraps xcmocean for this

Installation

You need to have conda installed for these installation instructions. You'll have best results if you use the channel conda-forge, which you can prioritize with conda config --add channels conda-forge --force.

Install, the easy way

PyPI:

pip install xroms

conda-forge:

mamba install -c conda-forge xroms

Create environment if needed

As a first step, you can create an environment for this package with conda if you want. If you do this, you'll need to git clone the package first as below. Note that mamba and conda can be used interchangeably, but mamba is faster for installation.

mamba env create -f environment.yml

You can choose to install with conda the optional dependencies for full functionality:

conda install --file requirements-opt.txt

and to install optional dependency xcmocean:

pip install git+https://github.com/pangeo-data/xcmocean

Then choose one of the following to install xroms from GitHub:

Clone xroms into a particular directory then install so that it is editable (-e)

git clone https://github.com/xoceanmodel/xroms.git
cd xroms
pip install -e .

Directly install xroms from github

pip install git+https://github.com/xoceanmodel/xroms

Metadata

Release files for xroms 0.6.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for xroms 0.6.2
File	Size	Uploaded
xroms-0.6.2.tar.gz	39.6 MB	Aug 27, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for xroms 0.6.2
File	Interpreter	ABI	Platform	Reset
xroms-0.6.2-py3-none-any.whl 42.6 kB Aug 27, 2025	Python 3	none	any	Details

Total release size: 39.6 MB

Release files / xroms-0.6.2.tar.gz

Download URL	xroms-0.6.2.tar.gz
Size	39.6 MB
Tags	Source
SHA-256 checksum How to use checksums	`4e9c0ec2a5c35135682a2d132c99038864cadc583ae3942952354bcc4e06d81f`
BLAKE2b-256 checksum How to use checksums	`e212b2d6e58931bae5268e4d35b133595f51ef3f5d5166c096fcc258a06bb7cc`
Upload date	Aug 27, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.12.9`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/xoceanmodel/xroms
Publishing commit: github.com/xoceanmodel/xroms/tree/be8ea34aca92430759cb62210ee66e2b87bf8247

Workflow

Publishing configuration: github.com/xoceanmodel/xroms/blob/be8ea34aca92430759cb62210ee66e2b87bf8247/.github/workflows/release.yaml
Publishing logs: github.com/xoceanmodel/xroms/actions/runs/17275779649/attempts/1

Artifact

Subject: xroms-0.6.2.tar.gz
SHA-256 checksum: 4e9c0ec2a5c35135682a2d132c99038864cadc583ae3942952354bcc4e06d81f Verifying attestations

Release files / xroms-0.6.2-py3-none-any.whl

Download URL	xroms-0.6.2-py3-none-any.whl
Size	42.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`04cb964fccb525dfcc0a7a9ee6dd9c3e6e4186c18f7fabbd9665170755c977f4`
BLAKE2b-256 checksum How to use checksums	`dad5a400884177e3626b7496a6987327d1e5d616aac7df8b00e2da244db65f93`
Upload date	Aug 27, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.12.9`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/xoceanmodel/xroms
Publishing commit: github.com/xoceanmodel/xroms/tree/be8ea34aca92430759cb62210ee66e2b87bf8247

Workflow

Publishing configuration: github.com/xoceanmodel/xroms/blob/be8ea34aca92430759cb62210ee66e2b87bf8247/.github/workflows/release.yaml
Publishing logs: github.com/xoceanmodel/xroms/actions/runs/17275779649/attempts/1

Artifact

Subject: xroms-0.6.2-py3-none-any.whl
SHA-256 checksum: 04cb964fccb525dfcc0a7a9ee6dd9c3e6e4186c18f7fabbd9665170755c977f4 Verifying attestations