Skip to content

Add shift-column auto-update tooling and recompute logbook shift totals - #267

Open
jgray-19 wants to merge 10 commits into
masterfrom
shift-column-tooling
Open

Add shift-column auto-update tooling and recompute logbook shift totals#267
jgray-19 wants to merge 10 commits into
masterfrom
shift-column-tooling

Conversation

@jgray-19

Copy link
Copy Markdown
Contributor

Summary

Refactors the shift-timing logic into a shared, dependency-free core and adds a
script that recomputes the Shifts column of any logbook table directly from its
Start Date/End Date columns. All existing logbook tables have been regenerated
with this tool so the recorded shift breakdowns are consistent and reproducible.

Changes

Tooling

  • scripts/shift_model.py (new) — single source of truth for the shift model
    (work hours 08:30–17:30, calendar weekends, CERN public holidays, 8h = 1 shift).
    Pure standard library, so it can be reused without matplotlib/pandas. All times
    are timezone-aware (Europe/Zurich); holidays are listed as ISO dates grouped by
    source. Includes unit tests.
  • scripts/update_shift_column.py (new) — recomputes and rewrites the Shifts
    column of a logbook markdown table in place. Supports --check (dry-run, non-zero
    exit if stale — handy for CI/pre-commit) and --selftest. Only touches the first
    table in a file and preserves all surrounding content.
  • scripts/shift_calculations.py — slimmed down to the reporting/plotting layer;
    now imports the model from shift_model.py instead of redefining it. Also fixes an
    incorrect CERN holiday list (stale/duplicated dates).

Data

  • Regenerated the Shifts column across all logbook tables by running the tool over
    docs/logbook/*/*.md (LHC/PS/PSB/SPS, 2022–2026).

Usage

uv run scripts/update_shift_column.py docs/logbook/LHC/2025_lhc.md      # rewrite one file
uv run scripts/update_shift_column.py docs/logbook/*/*.md               # rewrite all
uv run scripts/update_shift_column.py --check docs/logbook/*/*.md       # dry-run
uv run scripts/shift_model.py                                           # run tests

Notes

- The shift model is unchanged from the previous definition (08:30–17:30, calendar
weekends) — only the surrounding tooling and the fixed holiday list affect results.
- Fixes the 2026 CERN holidays, which were previously copy-pasted from 2025.

jgray-19 and others added 3 commits July 24, 2026 12:09
Extract the shift-timing logic and CERN holiday list from
shift_calculations.py into a new pure-stdlib shift_model.py, so it can be
reused without matplotlib/pandas. shift_calculations.py now imports the model
for plotting; add update_shift_column.py to recompute the Shifts column of a
logbook table from its start/end dates.

Interpret all times in Europe/Zurich (tz-aware datetimes) and list the CERN
holidays as ISO date strings grouped by source.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ETmmvky8DVfjD6wBwB85dv
@jgray-19 jgray-19 added Type: Documentation Improvements, updates and fixes to the documentation. Estimate: Easy Good first issue for newcomers. Straightforward fixes. Priority: Medium Work on this. labels Jul 24, 2026
@jgray-19
jgray-19 requested a review from fsoubelet July 24, 2026 10:21
@jgray-19 jgray-19 added Type: Maintenance Improvements in the code, that are not necessarily visible in functionality. Status: Review Needed Work currently stopped, untils someone else reviews it. labels Jul 24, 2026

@fsoubelet fsoubelet left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm okay with the addition, but felt like being an annoying bitch somehow.

I realised half way through review that my comments were on some pre-existing but moved around code. However, wouldn't that be the opportunity to improve said code?

To be discussed: we could take the opportunity to get rid of the pie charts too? They are horrible for the human brain and can't do a thing that bar charts would do, better represented.

Comment thread scripts/shift_model.py Outdated
Comment thread scripts/shift_model.py Outdated
Comment thread scripts/shift_model.py Outdated
Comment thread scripts/shift_model.py
Comment thread scripts/shift_model.py Outdated
Comment thread scripts/shift_model.py Outdated
Comment thread scripts/update_shift_column.py Outdated
Comment thread scripts/update_shift_column.py
Comment thread scripts/update_shift_column.py
Comment thread scripts/update_shift_column.py Outdated
@jgray-19
jgray-19 requested a review from fsoubelet July 24, 2026 12:01
@JoschD

JoschD commented Aug 6, 2026

Copy link
Copy Markdown
Member

Hey, just saw this. If I understand this correctly, this goes against what the shift-column was supposed to be: a representation of the time actually worked, which might be different from start/end times, e.g. if there was a long interruption due to downtime.

Ewen didn't want to have this calculated into the plots he presents. That's why the python scripts had the option to calculate from either start/end times or from the shift column.

Calculating the shift durations from the start/end times kind of also makes one of the two columns redundant. There were supposed to represent two different kinds of time metrics.

@fsoubelet

Copy link
Copy Markdown
Member

Hey, just saw this. If I understand this correctly, this goes against what the shift-column was supposed to be: a representation of the time actually worked, which might be different from start/end times, e.g. if there was a long interruption due to downtime.

Ewen didn't want to have this calculated into the plots he presents. That's why the python scripts had the option to calculate from either start/end times or from the shift column.

Calculating the shift durations from the start/end times kind of also makes one of the two columns redundant. There were supposed to represent two different kinds of time metrics.

Yes this is pretty much the discussion that happened in the comments of #268. This PR is very much on hold I would say.

@JoschD

JoschD commented Aug 6, 2026

Copy link
Copy Markdown
Member

Ohh, thanks for the llink. Didn't see this discussion.
To contribute: the "Shifts" column has always been your envisioned "Beamtime" column.

And I don't think an extra "shifts" column (as @jgray-19 envisions it) is useful, as

a) it doesn't add new information (that's already in the start/end time)
b) additional columns make the table less readable
c) the information, if needed for visualiziation, can already be automatically extracted via the scripts.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Estimate: Easy Good first issue for newcomers. Straightforward fixes. Priority: Medium Work on this. Status: Review Needed Work currently stopped, untils someone else reviews it. Type: Documentation Improvements, updates and fixes to the documentation. Type: Maintenance Improvements in the code, that are not necessarily visible in functionality.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants