fvcomersem-viz

Utilities for turning FVCOM / FVCOM–ERSEM model output into clear, reproducible figures and animations:
time-series, plan-view maps, Hovmöller sections, x–y diagnostics, stoichiometry KDEs, and 3D cinematic bubble plumes.

---

Overview

fvcomersem-viz helps modellers and marine scientists quickly visualise and diagnose FVCOM–ERSEM runs with consistent, publication-ready plots.

It now includes a Cinematic 3D Bubble Renderer — powered by PyVista (VTK) — for visualising subsea gas leaks or bubble plumes as dynamic, shaded sphere animations.

Features

• Time-series at domain / region / station scopes (surface, bottom, depth-avg, sigma, fixed-z).
• Plan-view maps (full domain or polygon-masked regions).
• Hovmöller (time × depth) in native σ or interpolated z.
• Composition (time × depth) for phyto/zoo stoichiometry.
• Curves (x–y diagnostics) with binned median ± IQR or raw scatter.
• Stoichiometry KDEs (N:C & P:C vs variable) in 2×2 panels.
• Animations for time-series, maps, and 3D bubbles.
• Cinematic 3D bubble plumes using PyVista/VTK with lighting, fog, and orbiting camera.
• Sensible file naming & directory structure; Dask-friendly.

---

Requirements

Category	Packages	Notes
Core (required)	numpy, pandas, xarray, matplotlib, netCDF4, cftime, scipy, notebook, ffmpeg	Base numerical + plotting stack.
Geospatial (optional)	geopandas, shapely, pyproj, rtree, cartopy	For regional masks and map overlays.
Performance (optional)	dask[array]	Parallel/distributed arrays.
3D Visualisation (optional)	pyvista, pyvistaqt, vtk, imageio-ffmpeg	Enables plot_bubbles_pyvista (GPU-rendered 3D plumes).
Development (optional)	pytest, ruff, black, pre-commit, mypy	Included automatically in the dev environment.

Python ≥ 3.9 (3.11 recommended)

---

Installation

Option A — User install (recommended)

Use this if you just want to use the package.

1. Create the environment (from environment.yml) and activate it:

mamba env create -f environment.yml
mamba activate fviz
# (use conda instead of mamba if you prefer)

2. Verify:

python tests/check_install.py
# or a tiny smoke test:
python -c "import fvcomersemviz as m; print('fvcomersemviz', getattr(m,'__version__','n/a'))"

Note: environment.yml installs all dependencies from conda-forge and installs this package (non-editable) via pip inside the same environment.

---

Option B — Developer install (contributors)

Use this if you plan to modify the code, run tests, or use linting tools.

1. Clone the repository and create the dev environment (from environment-dev.yml), then activate it:

git clone https://github.com/mollyjames2/fvcomersem-viz.git
cd fvcomersem-viz
mamba env create -f environment-dev.yml
mamba activate fviz-dev

2. Verify dev setup:

python tests/check_install_dev.py
ruff check .
pytest -q

Notes:

• environment-dev.yml installs the package in editable mode with .[dev] extras (e.g., pytest, ruff).
• Edits under src/fvcomersemviz/ take effect immediately.

---

Option C — Manual install (no YAML)

If you don’t want to use the YAML files, you can create the environment and install packages explicitly. This keeps all heavy geospatial libs consistent via conda-forge, then installs the package with pip.

Create and activate the env:

mamba create -n fviz -c conda-forge \
  python=3.11 \
  numpy scipy pandas xarray dask netcdf4 \
  matplotlib notebook ffmpeg \
  geopandas shapely pyproj rtree cartopy \
  pyvista pyvistaqt vtk imageio-ffmpeg pip
mamba activate fviz

Install the package (users, non-editable):

python -m pip install "git+https://github.com/mollyjames2/fvcomersem-viz.git"
# SSH alternative (if your GitHub is set up for SSH):
# python -m pip install "git+ssh://git@github.com/mollyjames2/fvcomersem-viz.git"

Or, for developers (editable with dev tools) from the repo root:

git clone https://github.com/mollyjames2/fvcomersem-viz.git
cd fvcomersem-viz
python -m pip install -e ".[dev]"

Verify:

python tests/check_install.py       # users
# or
python tests/check_install_dev.py   # developers

If you see

  All good! fvcomersemviz and its dependencies look ready to run.

---

Troubleshooting

• Ensure you activate the environment before running Python:

  mamba activate fviz       # or: mamba activate fviz-dev
  which python              # should point inside your env
  which pip                 # should point inside your env

• Keep geospatial libs (GDAL/PROJ/GEOS family via geopandas/shapely/pyproj/rtree/cartopy) from conda-forge. Avoid mixing pip wheels for those packages in the same env.

• If you must reinstall cleanly:

  mamba env remove -n fviz -y
  mamba env remove -n fviz-dev -y

---

Examples

Browse and run the ready-to-use scripts in the examples/ folder or run the notebooks in the notebooks/ folder in jupyter notebook

---

Outputs & naming

Figures/animations are written under:

FIG_DIR/<basename(BASE_DIR)>/<module>/

Filenames encode scope, variable(s), depth tag, and time label for easy batch comparison.

---

Project structure

fvcomersem-viz/
├─ src/fvcomersemviz/
│  ├─ __init__.py
│  ├─ io.py
│  ├─ utils.py
│  ├─ regions.py
│  ├─ plot.py
│  └─ plots/
│     ├─ timeseries.py
│     ├─ maps.py
│     ├─ hovmoller.py
│     ├─ curves.py
│     ├─ composition.py
│     ├─ kde_stoichiometry.py
│     ├─ bubbles.py
│     └─ animate.py
├─ examples/
│  ├─ tutorial.py
│  ├─ plot_timeseries.py
│  ├─ plot_maps.py
│  ├─ plot_kde.py
│  ├─ plot_hovmoller.py
│  ├─ plot_curves.py
│  ├─ plot_composition.py
│  ├─ plot_bubbles.py
│  └─ plot_animations.py
├─ notebooks/
│  ├─ quickstart_tutorial.ipynb
│  ├─ plot_timeseries.ipynb
│  ├─ plot_maps.ipynb
│  ├─ plot_kde.ipynb
│  ├─ plot_hovmoller.ipynb
│  ├─ plot_curves.ipynb
│  ├─ plot_composition.ipynb
│  └─ plot_animations.ipynb
├─ tests/
│  └─ check_install.py
├─ LICENSE
├─ README.md
├─ pyproject.toml / setup.cfg (one or both)
└─ .gitignore

(Some filenames may evolve; see the repo for the authoritative layout.)

---

How to cite

APA (template)

James, MK. (2025). fvcomersem-viz (Version 0.0.1) [Computer software]. GitHub. https://github.com/mollyjames2/fvcomersem-viz

BibTeX (template)

@software{fvcomersem_viz,
  title        = {fvcomersem-viz},
  author       = {Molly James},
  year         = {2025},
  version      = {0.0.1},
  url          = {https://github.com/mollyjames2/fvcomersem-viz},
  note         = {FVCOM / FVCOM–ERSEM visualization utilities}
}

---

Contributing

Contributions of all kinds are welcome: bug fixes, new features, documentation improvements, and ideas.

Quick start

1. Clone the repository

   git clone https://github.com/mollyjames2/fvcomersem-viz.git cd fvcomersem-viz

2. Create your development environment

   Option A: conda (recommended)

    conda create -n fviz python=3.11 geopandas shapely pyproj rtree notebook -c conda-forge
    conda activate fviz
    pip install -e .[dev]
   

   Option B: virtual environment

    python -m venv .venv
    . .venv/bin/activate
    pip install -e .[dev]
   

3. Create a branch for your change

    git checkout dev
    git pull
    git checkout -b feat/my-change
   

4. Make and test your edits

    python tests/check_install.py
    git add -A
    git commit -m "feat: brief summary of your change"
    git push -u origin feat/my-change
   

5. Open a Pull Request

   • Base branch: dev
   • Add a clear title and short description
   • Continuous Integration (CI) will run automatically

After review and merge, your branch will be deleted automatically.

More information

See the full Contributing Guide (CONTRIBUTING.md) and Releasing Guide (RELEASING.md) for details on branching, review, and release workflows.

---

License

See the LICENSE file in this repository.

fvcomersem-viz