Skip to content

refactor: use package API in build_desert_farm.py + add n_points/label_x/label_y to ETL#30

Merged
MDunitz merged 3 commits intomainfrom
refactor/build-desert-farm-uses-package-api
Apr 29, 2026
Merged

refactor: use package API in build_desert_farm.py + add n_points/label_x/label_y to ETL#30
MDunitz merged 3 commits intomainfrom
refactor/build-desert-farm-uses-package-api

Conversation

@madsCodeBuddy
Copy link
Copy Markdown
Collaborator

Summary

Replaces closed PR #24 (which had diverged ahead=10/behind=10). Recreated from current main per branch hygiene rule.

Two logical changes structured as two commits:

  1. feat(etl): — public-API addition to transform_process_response_sheet: n_points parameter + auto-computed label_x/label_y columns. Reviewers: this is a public API change; please look at this commit independently. All 17 tests pass.
  2. refactor(stommel):docs/build_desert_farm.py consumes the new etl.py columns and replaces ~80 lines of duplicated figure/grid/ETL setup with package calls.

Kept together rather than split into two PRs because the build-script refactor is the only consumer of the new etl.py columns — splitting creates a merge-order problem where the build PR breaks until the etl PR merges.

Files changed

  • etl.py (+22/-3): new params/columns
  • tests/test_etl.py (+96/-2): 17 happy-path tests
  • docs/build_desert_farm.py (+42/-101): refactor to use package API
  • docs/desert_farm_stommel.html: regenerated (+3 KB, due to n_points=100 ellipse smoothness)

Out of scope

Verified

  • pytest tests/test_etl.py → 17 passed
  • black --check clean on all four files
  • flake8 --max-line-length=120 clean
  • HTML regenerated successfully on current main (renders all 24 processes + 5 leverage point annotations)

madsCodeBuddy and others added 3 commits April 29, 2026 04:35
…onse_sheet

Public-API additions to transform_process_response_sheet:

- n_points (int, default 1000): controls ellipse vertex count, passed
  through to create_ellipse_data. Lets callers trade rendered HTML size
  for curve smoothness when plotting many ellipses.
- label_x / label_y columns: geometric mean of (Time_min, Time_max) and
  (Space_min, Space_max). If the input DataFrame already has these
  columns (e.g. CSV-provided manual overrides), they are preserved.
  Reduces duplication in callers that previously computed these inline.

Adds 17 happy-path tests covering both new params, column preservation,
and existing behavior (no regressions to ellipse coords, FillAlpha,
TextAlpha, geometry classification).
Replace duplicated logic in docs/build_desert_farm.py with calls to the
package's public functions, while preserving figure-specific overrides
that exist for UX reasons.

Replaced with package calls:

- Figure setup (~15 -> 9 lines + overrides). figure(...) ->
  create_space_time_figure(space_on_x=False) plus per-attribute overrides
  for figure-specific defaults (width=900, height=650, ranges 1e-3..1e13
  / 1e-28..1e22, 11pt axis labels, 16pt bold title, #fafafa background,
  toolbar above, original 4-tool toolbar).
- Reference grid (~28 -> 1 line). The hand-rolled
  for time_val in TIME_MARKERS: ... for space_val in SPACE_MARKERS:
  loop with manually-positioned dashed Spans and Labels is replaced by
  add_magnitude_labels(p, font_size_px=11).
- Process ETL (~40 -> 5 lines). Manual Time_min/Time_max parsing,
  alpha computation, and ellipse vertex generation replaced by
  transform_process_response_sheet(df, space_on_x=False, n_points=100).
  EXPLORER_N_POINTS=100 keeps rendered HTML compact for the 24-row
  dataset (vs the package default of 1000).
- Label coordinates: rely on the new label_x/label_y columns rather
  than recomputing geometric means inline.

Preserved (figure-specific UX):

- ENERGY_COLORS palette and per-row Energy_type -> color mapping
- Numbered annotations and leader lines for the 5 leverage points
- Custom HTML wrapper with footer and intro paragraph

Output unchanged in shape: same 24 processes rendered, same 5 leverage
point annotations. HTML size increased ~3 KB due to n_points=100 ellipse
smoothness vs the old hand-rolled curves.

Regenerated docs/desert_farm_stommel.html.
@MDunitz MDunitz merged commit 1a50bce into main Apr 29, 2026
4 checks passed
madsCodeBuddy added a commit that referenced this pull request Apr 29, 2026
The merge of PR #30 (refactor) resolved its conflict with PR #28 (earth
tones) by taking the refactor branch's old ENERGY_COLORS values
(#0F793D / #FFCC33 / #CC3333 / #336699), reverting #28's earth-tone
palette in the dict. The CSS footer link color was preserved as
#7A8C5C, leaving the file in an inconsistent state where the legend
swatches and ellipse fills used the old palette while the page accent
used the new one.

Restoring the earth-tone palette and regenerating the HTML:

  Chemical   #0F793D -> #7A8C5C  (olive)
  Radiative  #FFCC33 -> #E5C16E  (warm sand)
  Thermal    #CC3333 -> #7B3F3F  (deep rust)
  Mechanical #336699 -> #4F6B82  (slate)

Same palette and same colorblind-safety reasoning as PR #28.
madsCodeBuddy added a commit that referenced this pull request Apr 29, 2026
* fix: restore earth-tone palette in ENERGY_COLORS after PR #30 merge

The merge of PR #30 (refactor) resolved its conflict with PR #28 (earth
tones) by taking the refactor branch's old ENERGY_COLORS values
(#0F793D / #FFCC33 / #CC3333 / #336699), reverting #28's earth-tone
palette in the dict. The CSS footer link color was preserved as
#7A8C5C, leaving the file in an inconsistent state where the legend
swatches and ellipse fills used the old palette while the page accent
used the new one.

Restoring the earth-tone palette and regenerating the HTML:

  Chemical   #0F793D -> #7A8C5C  (olive)
  Radiative  #FFCC33 -> #E5C16E  (warm sand)
  Thermal    #CC3333 -> #7B3F3F  (deep rust)
  Mechanical #336699 -> #4F6B82  (slate)

Same palette and same colorblind-safety reasoning as PR #28.

* Update header description to match earth-tone palette

The page header had 'chemical (green), radiative (gold), thermal
(red), mechanical (blue)' baked into the prose. After the palette
change to olive/sand/rust/slate, that text would describe colors
that no longer match the rendered ellipses.
madsCodeBuddy added a commit that referenced this pull request Apr 29, 2026
Replaces the hand-rolled load_reference_objects with a thin adapter
around timeSpace.etl.transform_process_response_sheet, mirroring the
pattern PR #30 established for build_desert_farm.py.

Why: the script's hand-rolled ETL had drifted from the package version.
The previous commit on this branch fixed one symptom (missing
.rename(columns={0: 'x_coords', 1: 'y_coords'}) after result_type=
'expand'), but the underlying issue was duplicated-and-stale code.
Other things load_reference_objects was missing vs the package ETL:
  - Filtering rows where Time_min > Time_max or Space_min > Space_max
  - FillAlpha / TextAlpha (script uses fixed 0.0 for hidden state, so
    these are unused but harmless additions)
  - Time Max / Space Min derived columns (also unused, harmless)

Adapter pattern (same as build_desert_farm.py's load_processes):
  - Rename Name -> FullName so create_name's ShortName fallback inside
    the ETL doesn't overwrite the descriptive name used for hover/labels
  - Map Category -> Color (uppercase to match POSSIBLE_COL_LIST)
  - Set ShortName = FullName (reference objects don't have separate
    short forms, but create_name needs the column to exist)

Behavior verification: regenerated explorer.html is byte-for-byte
identical to the previous commit (688,092 B, 159 coord lists with
content >= 100 chars), so this is a pure code-quality change with
no rendered output difference.

Drops numpy import (was only used in the manual label_x / label_y
computation that the package ETL now handles).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants