From 9f927c40c09fffb2dc90d89ccb0cda6ffe821075 Mon Sep 17 00:00:00 2001 From: madsCodeBuddy Date: Wed, 29 Apr 2026 04:31:58 +0000 Subject: [PATCH] Add Boyd-orientation Stommel demo build script docs/build_demo_boyd.py is the canonical example showing how to use the package with space_on_x=False (time on x-axis, space on y-axis), the convention used in Boyd et al. (2015) and most BGC literature. Renders all 14 rows from data/datasets/stommel_boyd2015_volumes.csv with diffusion lines, magnitude labels along both axes, and the legend moved to the right of the plot via add_legend(p, position='right'). Output: docs/demo_stommel_boyd.html (442 KB). --- docs/build_demo_boyd.py | 59 +++++++++++++++++++++++++++++++++++ docs/demo_stommel_boyd.html | 61 +++++++++++++++++++++++++++++++++++++ 2 files changed, 120 insertions(+) create mode 100644 docs/build_demo_boyd.py create mode 100644 docs/demo_stommel_boyd.html diff --git a/docs/build_demo_boyd.py b/docs/build_demo_boyd.py new file mode 100644 index 0000000..3e64313 --- /dev/null +++ b/docs/build_demo_boyd.py @@ -0,0 +1,59 @@ +"""Build a Boyd-orientation Stommel demo from the canonical Boyd (2015) CSV. + +Boyd orientation: time on x-axis (bottom), space on y-axis. This is the +convention used in Boyd et al. (2015) and most oceanographic/biogeochemical +literature. The package default is the opposite orientation +(``space_on_x=True``); this script demonstrates how to pass +``space_on_x=False`` end-to-end. + +The legend is moved to the right (default placement) so it sits outside the +plot area rather than covering data. + +Run from repo root: + python docs/build_demo_boyd.py + +Produces: + docs/demo_stommel_boyd.html +""" + +import os + +import pandas as pd +from bokeh.io import output_file, save + +from timeSpace.etl import transform_predefined_processes +from timeSpace.plotting import ( + add_diffusion_lines, + add_legend, + add_magnitude_labels, + add_predefined_processes, + create_space_time_figure, +) + +# Resolve paths relative to repo root regardless of where the script is run from +HERE = os.path.dirname(os.path.abspath(__file__)) +REPO = os.path.dirname(HERE) +CSV_IN = os.path.join(REPO, "data", "datasets", "stommel_boyd2015_volumes.csv") +HTML_OUT = os.path.join(HERE, "demo_stommel_boyd.html") + + +def build(): + df_raw = pd.read_csv(CSV_IN) + df = transform_predefined_processes(df_raw, space_on_x=False) + + p = create_space_time_figure( + title="Boyd (2015) Stommel diagram — time on x, space on y", + space_on_x=False, + ) + add_magnitude_labels(p, space_on_x=False) + add_diffusion_lines(p, space_on_x=False) + add_predefined_processes(p, df, space_on_x=False) + add_legend(p, position="right") + + output_file(HTML_OUT, title="timeSpace demo — Boyd orientation", mode="cdn") + save(p) + print(f"Built {HTML_OUT} ({os.path.getsize(HTML_OUT):,} bytes)") + + +if __name__ == "__main__": + build() diff --git a/docs/demo_stommel_boyd.html b/docs/demo_stommel_boyd.html new file mode 100644 index 0000000..c7dfdef --- /dev/null +++ b/docs/demo_stommel_boyd.html @@ -0,0 +1,61 @@ + + + + + timeSpace demo — Boyd orientation + + + + + +
+ + + + + \ No newline at end of file