Skip to content

Update for pyedautils 0.0.33, review fixes, lean book, MIT/CC BY licenses, branding and README - #4

Merged
retomarek merged 24 commits into
mainfrom
update-pyedautils-0.0.32
Nov 6, 2026
Merged

Update for pyedautils 0.0.33, review fixes, lean book, MIT/CC BY licenses, branding and README#4
retomarek merged 24 commits into
mainfrom
update-pyedautils-0.0.32

Conversation

@retomarek

@retomarek retomarek commented Nov 6, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Summary

Updates the book for pyedautils 0.0.32 and 0.0.33, fixes the errors found in an independent review, applies the owner's decisions on scope and licensing, and adds branding, a README and community files in the style of the sister repositories.

Content fixes from the review

  • Cross-correlation: the hours are now on a regular grid, the recipe correlates hour-to-hour changes, and the lag convention is correct. The peak is now at +4 h, where before it showed -5 h.
  • Temperature vs. humidity: the correlation is explained correctly; in these flats it is positive.
  • Comfort chapter: the Mollier diagram, the donuts and the compass now grade the room with one target band (8–18 °C, 40–70 %). The branding images were rendered again with that band.
  • Gap filling: the meaning of limit= is corrected, with limit_area="inside" and a way to fill only short gaps. STL and the ACF need a regular grid first.
  • Meter readings: daily and hourly sums keep complete periods only (min_count). Units are corrected: the household meter counts Wh, and ele_meter.csv holds mean power in W.
  • pandas 3: frequency aliases, .loc slicing and dtype wording are updated, and there is a short section on daylight saving time.
  • Pages that promised too much: the energy signature and PES pages, the histogram, the duration curves and several failing or silent examples now match what the code does. The PES citation is complete.
  • Outdated facts: the MeteoSwiss open data download, the R book title, InfluxDB versions and PyCharm editions.
  • Colab setup cell: the same hidden cell in every notebook. It installs only pyedautils>=0.0.32, and the renderer is set only outside Colab.

Owner decisions

  • Lean book:
    • EDA keeps steps 1–4 and links the Part III recipes.
    • Data Quality no longer repeats the outlier methods.
    • InfluxDB moves to a short appendix note.
    • Jupyter shortcuts, cell tags and the Spyder and PyCharm-via-Anaconda sections are removed.
    • The Mollier chapter is changed only where the comfort-band fix needs it.
  • License:
    • Code is under MIT (LICENSE); text and images are under CC BY 4.0 (LICENSE-CC-BY-4.0, official legal code).
    • The README, book footer and preface state this.
    • A data sources and credits section lists the third-party material.
    • Copies distributed before keep their GPL-3.0 license.
  • Files: the .psd and .vsdx files and all CSVs are kept.

Repository

  • CI: pull requests and a weekly run build the book without deploying, and warnings fail those runs. Dead PLOTLY_RENDERER removed.
  • Cleanup: CONTRIBUTING.md is rewritten for the book. my_sensor_data.pkl is no longer tracked. All notebooks have cell ids and no stored outputs.
  • Branding and community files from the first round: banner, social preview, favicon, README, issue and discussion forms, PR template.

Testing

  • Full clean jupyter-book build edap -W --keep-going with all notebooks executed (Python 3.14, pandas 3.1, pyedautils 0.0.33): build succeeded with 0 warnings. Before this PR there were 6 warnings, including 2 notebooks that failed to execute.
  • All notebooks were also run with plotly 5.24 and pandas 2.3, as in Colab.
  • I looked at screenshots of the changed pages.

Notes

  • After merging, upload docs/social-preview.png under Settings > General > Social preview.
  • The book now requires pyedautils 0.0.33. It uses the public pyedautils.psychrometrics.pressure_from_altitude import, lets plot_mollier_hx derive the pressure from altitude=, and relies on the max_gap gap handling in plot_autocorrelation / plot_decomposition. The statsmodels FutureWarning on the ACF pages is gone.
  • The cover image and logo were created by the owner (AI-generated) and are covered by CC BY 4.0; only the third-party sample data is excluded.

🤖 Generated with Claude Code

retomarek and others added 22 commits November 6, 2026 08:33
@retomarek @claude
Add issue, discussion and pull request templates
a2d1057 
Bug report (book page, notebook, what went wrong, environment), topic or
chapter suggestion, contact links to Q&A, the book and pyedautils, a Q&A
discussion form and a pull request checklist, like the sister repositories.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@retomarek @claude
Fix two Python Basics notebooks that no longer execute
93ee535 
- dataQuality: Series.fillna(method=...) was removed in pandas 3; use
  .ffill() / .bfill(), which work in pandas 2 and 3.
- meteoData: the nearest Agrometeo station to PLZ 6048 is now Meggen
  (id 239), which has data only from December 2025; download June 2026
  instead of June 2024 so the example returns data again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@retomarek @claude
Colab setup: require pyedautils 0.0.32, drop kaleido
6167560 
Opening a notebook in Google Colab installed the latest kaleido (1.x) next
to Colab's preinstalled plotly 5.24, and plotly then warned that the two
are incompatible. No notebook exports static images, so kaleido is not
needed: it is removed from the Colab install cells and from
requirements.txt (the package tables now mark it as optional). Plotly is
not upgraded in Colab, so no runtime restart is needed; all notebooks
were executed against plotly 5.24.1 and pandas 2.3 without errors.

The install cells and requirements.txt now ask for pyedautils>=0.0.32,
and the Meteo Data notebook gets the Colab setup cell it was missing.
The package tables link the pyedautils documentation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@retomarek @claude
Replace pandas APIs deprecated in pandas 3
8205b22 
The rendered pages showed Pandas4Warning messages: assign the result
instead of inplace=True (DataFrame.rename, DataFrame.drop) and use
Series.dt.day_of_week instead of dt.dayofweek. Both forms also work in
pandas 2.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@retomarek @claude
Comfort chapter: pyedautils 0.0.32 features and reading guides
3cbde7e 
- Mollier h-x Diagram: the warning bands are now given as offsets around
  the comfort zone, derived with comfort_warning_bands() from the same
  severity stages as the comfort compass; a short new section shows the
  outside air with its ventilation line (outdoor=) and
  ventilation_effect(); captions/texts mentioned in the customisation.
- Comfort Compass: one paragraph on reading the glyph and one
  interpreting the example room; scale="fixed" vs. "fit" and the text
  options in the customisation dropdown.
- Both pages and the chapter intro link the pyedautils guides on reading
  the diagrams, comfort and saving energy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@retomarek @claude
Add banner, social preview and favicon in the style of the book logo
13aa207 
scripts/render_branding.py renders docs/banner.png (1280x320),
docs/social-preview.png (1280x640) and two plots from the comfort chapter
(docs/images/branding_*.png) with headless Chromium from the HTML
templates in scripts/. Paper texture and coffee cup are cropped from
edap/images/logo_big.png, the text is real text (Lexend). The cup is also
the book's new favicon (edap/images/favicon.png, html.favicon).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@retomarek @claude
README: banner, badges, contents and links like the sister repositories
516877f 
Banner and book link, flat-square badges, hero plots from the comfort
chapter, a pyedautils callout, a short Why, the contents from _toc.yml,
the existing build and deployment notes, related projects, questions and
feedback, contributing and code of conduct, how to regenerate the
repository images, license and credits. The license badge is static
because GitHub does not detect the GPL from the short LICENSE notice.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@retomarek @claude
Statistical recipes: correct cross-correlation and correlation readings
0b5cd1d 
- Cross-correlation: keep a regular hourly grid (asfreq) so shift() moves
  hours, correlate the hour-to-hour changes instead of the raw values
  (the shared annual cycle dominates those at every lag) and use
  indoor.corr(outdoor.shift(lag)), so a positive lag means the indoor
  temperature follows the outdoor temperature. Peak at +4 h.
- Correlation: temperature and relative humidity correlate positively in
  these flats; explain both effects and point to the h-x diagram.
- Autocorrelation: the confidence band widens because of Bartlett's
  formula, not because fewer points are available.
- The 'Density Plot' recipe draws a count histogram; call it that and
  drop the marginal options plot_distribution does not expose.
- Density by season: the season is called Fall, not Autumn.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@retomarek @claude
Time Series: correct gap filling and frequency aliases
51af93b 
- interpolate(limit=6) fills the first 6 values of every gap, it does not
  skip long gaps: say so, recommend limit_area="inside" and show how to
  fill only gaps up to a given length.
- Replace the image of resample aliases (H, T, M, ... rejected by
  pandas 3) with a short table of the current aliases.
- df.loc["2024-01"] instead of df["2024-01"], no .pad(), f-strings
  that also run on Python < 3.12, trailing mean wording, rolling window
  note; clear the committed outputs and add cell ids.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@retomarek @claude
Electricity recipes: complete periods only and correct units
c8d2270 
- Sum the 15-minute consumption with min_count (96 per day, 4 per hour),
  so days and hours with missing readings are dropped instead of
  showing up as zero or too low consumption (20 empty and 6 incomplete
  days in flatElectricity.csv).
- Duration curves are sorted from highest to lowest (reverse=True); the
  unsupported resolution="monthly" and seasons=True examples are fixed.
- eboBookEleMeter.csv counts Wh (about 1,000 kWh per year): convert to
  kWh. ele_meter.csv holds the mean power in W per 15 minutes, so the
  profile pages are labelled Power [W]; the decomposed example uses a
  trend window longer than a day.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@retomarek @claude
Energy signature pages: describe what the plots show
d6124f7 
- The simple energy signature is a scatter colored by season; the
  balance point is fitted in the PES recipe. The winter-only example
  parses the timestamp first.
- PES: the data is heat pump electricity, not heat; full citation of
  Eriksson, Akander and Moshfegh (2020).
- Multiple y-axes example: use the index of the frame it plots.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@retomarek @claude
Python Basics: pandas 3 dtypes, daylight saving time, meter readings
ebee539 
- Text columns are object in pandas 2 and str in pandas 3.
- Datetime Handling: short section on the repeated and the missing hour
  of daylight saving time (ambiguous / nonexistent); one week of hourly
  timestamps is 7 x 24; counters are aggregated with
  resample().last().diff() or diff() plus sum(min_count=...).
- Loading Data: restore the stripped link to requests.
- Data Wrangling: complete the MultiIndex explanation, show the results
  of the select/drop examples, make the inner/left join differ, keep the
  pipe example free of side effects; clear the stale committed outputs
  and add cell ids.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@retomarek @claude
Comfort chapter: grade the room with one target band
16a649a 
The Mollier page drew the default 20-26 °C comfort zone for the cool
room that the donut and the compass grade against 8-18 °C / 40-70 %.
All three now use the room's band. comfort_warning_bands() shares the
severity stages, not the band, so the text says that; the compass
numbers are printed from the distribution instead of typed. The branding
images are rendered again with the same band.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@retomarek @claude
Keep the book lean: teach each statistics step once
6145749 
- EDA keeps steps 1-4 (inspect, quality, overview plot, histogram) and
  links the Part III recipes for outliers, correlation, decomposition and
  autocorrelation from its checklist, instead of repeating the same
  pyedautils calls on the same column.
- Data Quality covers missing values, gaps, duplicates and filling; the
  IQR and z-score sections are dropped (see Outlier Detection). The gap
  check now finds the NaN runs that are the gaps in this file, the
  duplicate count says that the repeated rows are empty rows, and the
  interpolation uses limit_area="inside".
- InfluxDB moves from a Python Basics chapter to a short appendix note
  (versions and query languages, influxdb-toolkit, allow_write).
- Jupyter shortcuts and cell tags, and the Spyder and PyCharm-via-
  Anaconda sections are removed; the appendix part page gets one line.
- Intro gets an H1 and lists the comfort topics; preface names the R
  book correctly (Energy Data Analysis with R) and credits Engineering
  Data Analysis in R; package tables and requirements.txt drop
  influxdb-toolkit, kaleido and the pyedautils dependencies ephem and
  statsmodels; pandas>=2.2.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@retomarek @claude
Overview pages, references and outdated facts
1aaedd6 
- Part and chapter overview pages list the recipes that exist and
  describe what they show (duration curves, histogram, overlaid
  profiles, all comfort recipes).
- Meteo Data: MeteoSwiss measurements are open data now and pyedautils
  downloads them; no hard-coded station counts.
- Decomposition and autocorrelation: their period and lags count rows,
  so the series has to be on a regular grid first.
- PES reference with its real title and DOI; unused references.bib and
  BibTeX settings removed; config doc link fixed, no-op
  use_multitoc_numbering removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@retomarek @claude
CI build for pull requests, contributing guide for this book
1b9969f 
- Pull requests and a weekly scheduled run build the book with all
  notebooks executed, without deploying; warnings fail these runs, so a
  notebook that stops executing (e.g. a changed weather API) shows up.
  Separate concurrency groups keep them from cancelling a deploy.
- Drop PLOTLY_RENDERER: every notebook sets its renderer itself.
- CONTRIBUTING.md was a Python package template; it now explains how to
  report errors and change the book.
- Files written by the notebooks (*.pkl) are ignored; my_sensor_data.pkl
  is no longer tracked and Loading Data writes it to the temp folder.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@retomarek @claude
Colab setup cell: the same, hidden, in every notebook
53882dc 
- Install only pyedautils (>=0.0.32) in Colab: plotly, statsmodels and
  ephem are its dependencies and come with it.
- Set the notebook_connected renderer only outside Colab, where Colab's
  own renderer is needed for the figures to show.
- The setup cell is hidden (remove-input) in every notebook.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@retomarek @claude
American spelling, one import style, one unit notation
1ac4592 
- The book is written in American English; the comfort pages and the
  branding used British spellings (Customisation, centre, anonymised),
  and Overlayed becomes Overlaid.
- Import every plot function from pyedautils.plots.
- Units in square brackets, per day as /d.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@retomarek @claude
License: code under MIT, text and images under CC BY 4.0
4c19893 
The owner, sole author of the book, relicenses it: LICENSE holds the
standard MIT text (Copyright (c) 2021-2026 Reto Marek) for the code
(notebook code cells, scripts, workflows), LICENSE-CC-BY-4.0 the official
CC BY 4.0 legal code for the text and images. The previous LICENSE held
only the GPL how-to-apply notice. Copies distributed before keep their
GPL-3.0 license. The book footer and the preface state the licenses and
point to the third-party data and images, which are not covered.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@retomarek @claude
README: licenses, data sources and credits, relative image paths
b0d9dfa 
- License section and badges: code MIT, text and images CC BY 4.0, and a
  data sources and credits section for the third-party material (sample
  data from the edar repository, pyedautils data, weather and geodata
  services, cover image and logo of undocumented source).
- Images use relative paths, so they show before the merge too.
- Contents follow the new table of contents (InfluxDB in the appendix,
  Histogram); American spelling. Branding images re-rendered with the
  corrected tagline.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@retomarek @claude
Notebooks: cell ids everywhere, no committed outputs
21607ac 
nbformat warned about missing cell ids in most notebooks (they will
become an error in future versions); all notebooks are now nbformat 4.5
with ids and without stored outputs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@retomarek @claude
Shorter code lines and clearer printouts on the changed pages
1c09884 
Wrap the new code cells so they fit the page without horizontal
scrolling, shorten a chart title that was cut off, say what the compass
percentages refer to, and avoid a repeated sentence in EDA.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@retomarek retomarek changed the title Update for pyedautils 0.0.32, fix notebooks and Colab setup, branding and README Update for pyedautils 0.0.32, review fixes, lean book, MIT/CC BY licenses, branding and README Nov 6, 2026
retomarek and others added 2 commits November 6, 2026 09:34
@retomarek @claude
License: cover image and logo are covered by CC BY 4.0
e8dfddf 
The owner created the coffee-cup cover and the edap logo (AI-generated)
and releases them under CC BY 4.0 with the rest of the book; only
third-party data is excluded now.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@retomarek @claude
Switch to pyedautils 0.0.33
1eb4e7d 
- Require pyedautils>=0.0.33 (requirements.txt, Colab setup cells,
  branding command, bug report placeholder).
- Mollier h-x: plot_mollier_hx derives the air pressure from altitude=,
  so the explicit pressure is dropped; ventilation_effect() still needs
  it and gets it from the now public pyedautils.psychrometrics import
  (no more pyedautils._mollier). Same in scripts/render_branding.py.
- plot_autocorrelation and plot_decomposition put the data on a regular
  grid and fill gaps up to max_gap themselves: one sentence each instead
  of the earlier workaround notes. The statsmodels FutureWarning on the
  autocorrelation pages is gone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@retomarek retomarek changed the title Update for pyedautils 0.0.32, review fixes, lean book, MIT/CC BY licenses, branding and README Update for pyedautils 0.0.33, review fixes, lean book, MIT/CC BY licenses, branding and README Nov 6, 2026
@retomarek
retomarek merged commit fb7796e into main Nov 6, 2026
2 checks passed
@retomarek
retomarek deleted the update-pyedautils-0.0.32 branch November 6, 2026 09:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@retomarek