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
| Function |
Purpose |
save |
Write arrays, DataArrays, or Datasets to NetCDF. |
merge |
Merge multiple NetCDF files. |
modify |
Modify a variable value or variable attribute. |
rename |
Rename a NetCDF variable or dimension. |
check |
Check whether a NetCDF file is readable. |
convert_longitude |
Convert longitude coordinates between [-180, 180] and [0, 360]. |
isel |
Select NetCDF data by dimension indices. |
draw |
Plot variables from a NetCDF file or xarray object. |
compress |
Apply NetCDF compression. |
unscale |
Decode and remove scale_factor / add_offset storage encoding. |
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
| Function |
Purpose |
ensure_list |
Convert a value to a list. |
interp_vertical |
Interpolate along the fixed z axis in [t, z, y, x] order. |
interp_horizontal |
Interpolate horizontal fields over the fixed y, x axes. |
oa_geo
| Function |
Purpose |
earth_distance |
Calculate great-circle distance between two lon/lat points. |
mask_shapefile |
Mask a 2D field using a shapefile. |
mask_land_ocean |
Keep land or ocean values using a land/ocean mask. |
is_land |
Check whether a lon/lat point is on land. |
is_ocean |
Check whether a lon/lat point is in the ocean. |
oa_draw
| Function |
Purpose |
fig_minus |
Format minus signs in axis or colorbar tick labels. |
gif |
Create a GIF from image files. |
movie |
Create a video from image files. |
setup_map |
Configure a Cartopy map. |
ticks_symmetric |
Generate ticks symmetric around a center value. |
font_CN |
Configure Chinese font support for Matplotlib. |
oa_cmap
| Function |
Purpose |
show |
Preview a colormap. |
to_color |
Convert a colormap to a list of colors. |
create |
Create a custom colormap from colors or an RGB text file. |
get |
Load a Matplotlib or custom colormap. |
random_color |
Generate a random hex color. |
oa_file
| Function |
Purpose |
script_dir |
Return the caller script directory, independent of current working directory. |
find |
Find files by pattern. |
link |
Create symbolic links with wildcard support. |
copy |
Copy files or directories with wildcard support. |
move |
Move files or directories with wildcard support. |
rename |
Rename files by replacing text in filenames. |
remove_empty |
Remove empty folders recursively. |
remove |
Delete files or directories by pattern. |
size |
Return file size in the requested unit. |
replace |
Replace text content by replace_dict and save it to output_path. |
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
| Function / Class |
Purpose |
month_days |
Return the number of days in a month. |
hour_range |
Generate datetime strings at an hourly interval. |
adjust_time |
Offset a base time by a time delta. |
timeit |
Decorator class for timing function execution. |
oa_down
| Function |
Purpose |
download |
Download HYCOM data for one time or a time range. |
draw_time_range |
Draw the available HYCOM time range. |
download_by_doi |
Download literature files from DOI lists. |
downloader |
Send a download task to Internet Download Manager. |
get_ua |
Return the default user-agent string for download requests. |
oa_model
| Function |
Purpose |
interp |
Interpolate and remap ROMS data to target lon/lat/depth grids. |
header_record |
Build a WRF little_r header record. |
data_record |
Build a WRF little_r data record. |
ending_record |
Build a WRF little_r ending record. |
tail_record |
Build a WRF little_r tail record. |
oa_linux
| Function |
Purpose |
patch_slurm |
Update selected #SBATCH directives in a Slurm script. |
submit |
Submit a Slurm job with queue-aware retry logic. |
job_state |
Query Slurm job state. |
is_linux |
Check whether the current system is Linux. |
get_jobid |
Return an ID only when exactly one pending/running Slurm job matches; otherwise return None. |
cancel_job |
Cancel all active Slurm replicas matching an exact path and/or exact job name. |
scancel_dir |
Cancel every pending/running Slurm job submitted from one exact directory. |
dir_queued |
Check whether one exact directory has any pending/running Slurm job, including race replicas. |
oa_office
| Function |
Purpose |
extract_pptx_notes |
Extract PowerPoint notes to a Word document. |
oa_sign
| Function |
Purpose |
sign_in_love_ocean |
Sign in to 52ocean. |
sign_in_meteorological_home |
Sign in to Meteorological Home. |
sign_in_scientific_research |
Sign in to AbleSci. |
oa_tool
| Function / Class |
Purpose |
run_command |
Run an external command safely without using a shell. |
Pex |
Parallel executor wrapper with progress and timing. PEx remains as a deprecated compatibility alias until 2026-12-22. |
email |
Send an email. |
pbar |
Create a colored progress bar. |
Links
License
MIT License. See LICENSE.txt.
