OAFuncs

Oceanic and Atmospheric Functions for Python.

OAFuncs provides utilities for NetCDF files, geoscience arrays, plotting, geographic masks, downloads, file operations, model data, and small workflow tools.

Installation

pip install oafuncs

Optional dependency groups:

data, interp, nc, draw, geo, down, office, parallel, sign, science, all, full

Package Structure

oafuncs
|-- oa_nc.py          NetCDF utilities
|-- oa_data.py        data interpolation helpers
|-- oa_geo.py         geographic and land/ocean mask helpers
|-- oa_draw.py        plotting helpers
|-- oa_cmap.py        colormap helpers
|-- oa_file.py        file operation helpers
|-- oa_date.py        date and timing helpers
|-- oa_down/          download helpers
|-- oa_model/         ROMS and WRF helpers
|-- oa_linux.py       Linux, HPC, and Slurm helpers
|-- oa_office.py      Office document helpers
|-- oa_sign/          website sign-in helpers
`-- oa_tool.py        command, progress bar, email, and parallel helpers

Public API

oa_nc

oa_nc.save(write_mode="w") and oa_nc.merge() write to a temporary file before replacing an existing output. Failed writes preserve the previous file; append mode (write_mode="a") still updates the file in place. For NumPy input, preserve_mask_values=True keeps underlying masked values; False writes them as missing values. Explicit missing_value values remain missing even for integer arrays, and all-NaN arrays remain missing rather than 0. merge() preserves raw encoding and input order: units, calendars, non-merged variables and non-merged coordinates must match. It raises ValueError for incompatible inputs rather than converting time units or aligning different grids. oa_nc.rename() checks variable and dimension name conflicts before changing either name, so a conflicting coordinate rename does not leave a partial change.

oa_nc.draw() accepts a NetCDF path, xarray.Dataset, or xarray.DataArray. File-backed workloads use parallel="auto" by default: small batches remain serial, while sufficiently large collections of independent 2D slices use oafuncs.oa_tool.Pex with automatic worker sizing. Use parallel=False to force serial rendering or parallel=True to force Pex. The default output is 300 dpi; set save_dpi=600 when publication-resolution PNG files are needed. On Windows, Pex calls must run below an if __name__ == "__main__": guard. For strongly skewed fields, robust=True displays colors using the 1st–99th percentiles while the title continues to report the complete data range and the clipped color range. The default robust=False preserves the full range.

oa_data

oa_geo

mask_land_ocean() preserves existing xarray dimension coordinates, including x/y grid indices. Longitude and latitude describe mask positions; two-dimensional longitude/latitude arrays must have the same shape.

oa_draw

oa_draw.gif(frame_duration=0.2) uses seconds (200 milliseconds per frame). Unreadable images are skipped; automatic dimensions come from the first readable image.

oa_cmap

oa_file

Example:

from oafuncs.oa_file import replace

replace(
    input_path="config.txt",
    replace_dict={"old_value": "new_value"},
    output_path=r"D:\run\config.txt",
)

output_path accepts either a file name, such as "result.txt", or an absolute file path. A file name is saved in the input file's directory. Directory-only paths and relative paths containing directories are rejected to avoid ambiguous output.

oa_date

oa_down

Literature downloads require a PDF header and the configured min_size_kb before replacing an existing file. This is a basic content check, not a full PDF integrity check. Each mirror receives its own tries_each_url budget; an HTTP failure moves on to the next mirror and failure records are deduplicated.

For hycom_3hourly.download(), interval_hours for a time range must be a positive multiple of 3. When using IDM, idm_timeout controls how many seconds without a completed valid file are allowed before remaining files are reported as failed; it defaults to 24 hours.

oa_model

The little_r helpers retain the existing fixed-width record layout and units. Overlong text fields are truncated to their documented widths; invalid record lengths raise ValueError rather than terminating the caller's Python process.

oa_linux

oa_office

oa_sign

oa_tool

On Windows, Pex uses its own spawn context without changing the caller's global multiprocessing start method. Calls still require the main guard.

Links

• PyPI: https://pypi.org/project/oafuncs
• GitHub: https://github.com/OAKun/OAFuncs
• Download stats: https://pypistats.org/packages/oafuncs
• Wiki: https://deepwiki.com/OAKun/OAFuncs

License

MIT License. See LICENSE.txt.