jrpyprogramming 0.2.4__tar.gz → 0.2.6__tar.gz

{jrpyprogramming-0.2.4 → jrpyprogramming-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.1
 Name: jrpyprogramming
-Version: 0.2.4
+Version: 0.2.6
 Summary: Jumping Rivers: Programming with Python
 Author: Jumping Rivers
 Author-email: info@jumpingrivers.com
@@ -10,8 +10,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: jrpyintroduction (>=0.2.2)
+Requires-Dist: jrpyintroduction (>=0.3.8)
 Requires-Dist: matplotlib (>=3.5,<4.0)
-Requires-Dist: numpy (>=1.26,<2.0)
-Requires-Dist: pandas (>=1.5,<2.0)
+Requires-Dist: numpy (>=2.0,<3.0)
+Requires-Dist: pandas (>=2.2.0,<3.0.0)

{jrpyprogramming-0.2.4 → jrpyprogramming-0.2.6}/jrpyprogramming/__init__.py

@@ -1,4 +1,3 @@
 from .__version__ import __version__  # noqa: F401
 
 from . import data  # noqa: F401
-from . import vignettes  # noqa: F401

jrpyprogramming-0.2.6/jrpyprogramming/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.2.6"

{jrpyprogramming-0.2.4 → jrpyprogramming-0.2.6}/jrpyprogramming/data.py

@@ -46,3 +46,17 @@ def populate_examples():
         abs_path = data_path / file
         copyfile(abs_path, file)
         print(f'\nCreated file {file} in current directory.\n')
+
+
+def populate_sectors():
+    # Get absolute path to the per-sector example files
+    examples_path = resources.files("jrpyprogramming") / "examples"
+
+    # List the example files shipped with the package
+    files = os.listdir(examples_path)
+
+    # Copy files to current dir
+    for file in files:
+        abs_path = examples_path / file
+        copyfile(abs_path, file)
+        print(f'\nCreated file {file} in current directory.\n')

jrpyprogramming-0.2.6/jrpyprogramming/dev/buildings.py

@@ -0,0 +1,106 @@
+"""
+This non-exported module creates the `buildings` dataset used by the climate
+variant of the course, in chapter 0.
+
+The source is the Seventh Carbon Budget residential-buildings archetype dataset
+published by the Climate Change Committee (CCC), downloaded from:
+https://www.theccc.org.uk/publication/methodology-report-uk-northern-ireland-wales-and-scotland-carbon-budget-advice/
+The raw workbook is stored zipped in
+`jrpyprogramming/data_raw/ccc_data/` so that the build is reproducible.
+
+We keep a subset of columns that mirrors the teaching operations the base
+course previously performed on the `movies` dataset (boolean/conditional
+filtering, compound conditions, summary statistics and counting with 0/1 flag
+columns), themed around residential-building archetypes. It is the same
+dataset that students meet in the Introduction to Python course.
+
+Run with:
+
+    python -m jrpyprogramming.dev.buildings
+"""
+
+import zipfile
+from io import BytesIO
+from pathlib import Path
+
+import pandas as pd
+
+# ---- #
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[1]
+
+PATHS = {
+    "raw": PACKAGE_ROOT
+    / "data_raw"
+    / "ccc_data"
+    / "residential_buildings_archetype_dataset.zip",
+    "out": PACKAGE_ROOT / "data" / "buildings.zip",
+}
+
+SHEET = "Archetype Dataset"
+
+# Mapping from raw CCC column name -> teaching column name
+COLUMNS = {
+    "Final archetype number": "archetype_number",
+    "Region": "region",
+    "Country": "country",
+    "Property type": "property_type",
+    "Age band": "age_band",
+    "Tenure": "tenure",
+    "Heating system": "heating_system",
+    "Floor area": "floor_area",
+    "Stock": "stock",
+    "Annual space heating demand": "space_heating_demand",
+    "Space heating fuel consumption": "space_heating_fuel",
+    "Space heating CO2 (direct)": "space_heating_co2",
+    "Solar PV": "solar_pv",
+    "Fuel poverty": "fuel_poverty",
+    "Hot water tank": "hot_water_tank",
+}
+
+# Yes/No columns that we store as 0/1 integer flags (like the movies genre
+# columns) so that counting exercises work with `.sum()` and multiplication.
+FLAG_COLUMNS = ["solar_pv", "fuel_poverty", "hot_water_tank"]
+
+# ---- #
+
+
+def build_buildings(raw_path):
+    """
+    Read the CCC residential-buildings archetype workbook and return the
+    teaching subset as a tidy DataFrame.
+    """
+    # The zip holds a single workbook named after the archive; extract it to
+    # memory since read_excel cannot open zipped files directly.
+    with zipfile.ZipFile(raw_path) as archive:
+        workbook = BytesIO(archive.read(raw_path.with_suffix(".xlsx").name))
+    raw = pd.read_excel(workbook, sheet_name=SHEET)
+
+    subset = raw[list(COLUMNS.keys())].rename(columns=COLUMNS)
+
+    for column in FLAG_COLUMNS:
+        subset[column] = (subset[column] == "Yes").astype(int)
+
+    # Sort by the unique archetype identifier for a clean, stable ordering.
+    subset = subset.sort_values("archetype_number").reset_index(drop=True)
+
+    return subset
+
+
+# ---- #
+
+
+def main():
+    buildings = build_buildings(PATHS["raw"])
+    buildings.to_csv(
+        PATHS["out"],
+        index=False,
+        compression={"method": "zip", "archive_name": "buildings.csv"},
+    )
+    print(f"Wrote {len(buildings)} rows to {PATHS['out']}")
+
+
+# ---- #
+
+if __name__ == "__main__":
+    main()

jrpyprogramming-0.2.6/jrpyprogramming/dev/energy_demand.py

@@ -0,0 +1,105 @@
+"""
+This non-exported module creates the `energy_demand` dataset used by the
+climate variant of the course, in the chapter 3
+exercises.
+
+The source is the Seventh Carbon Budget full dataset published by the Climate
+Change Committee (CCC). The raw workbook is stored zipped in
+`jrpyprogramming/data_raw/ccc_data/` so that the build is reproducible.
+
+We take the economy-wide primary energy demand (substitution method) from the
+`Economy-wide data` sheet and reshape it so that each row is a single
+(source, year) observation. Only the Balanced Pathway scenario reports this
+breakdown, so the scenario is dropped. The result is a tidy table of UK primary
+energy demand (TWh) by source and year - a fresh, non-sector theme (the energy
+mix) that still supports the group-by and summary exercises the students have
+just learned. It maps onto the base course `experiment` dataset: `source` is
+the grouping column (like `treat`), `year` is the ordered index (like `time`)
+and `demand` is the numeric measure (like `measure`).
+
+The output is written as a zipped CSV in `jrpyprogramming/data/`, loadable with
+`jrpy.data.load("energy_demand")`.
+
+Run with:
+
+    python -m jrpyprogramming.dev.energy_demand
+"""
+
+import zipfile
+from io import BytesIO
+from pathlib import Path
+
+import pandas as pd
+
+# ---- #
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[1]
+
+PATHS = {
+    "raw": PACKAGE_ROOT
+    / "data_raw"
+    / "ccc_data"
+    / "seventh_carbon_budget_full_dataset.zip",
+    "out": PACKAGE_ROOT / "data" / "energy_demand.zip",
+}
+
+SHEET = "Economy-wide data"
+
+# We keep the primary-demand-by-source variables (substitution method), which
+# together make up the energy mix.
+PREFIX = "Energy: primary demand "
+SUFFIX = " (substitution method)"
+
+COLUMN_ORDER = ["source", "year", "demand"]
+
+# ---- #
+
+
+def build_energy_demand(raw_path):
+    """
+    Read the CCC economy-wide sheet and return a tidy table with one row per
+    (scenario, source, year) giving primary energy demand in TWh.
+    """
+    # The zip holds a single workbook named after the archive; extract it to
+    # memory since read_excel cannot open zipped files directly.
+    with zipfile.ZipFile(raw_path) as archive:
+        workbook = BytesIO(archive.read(raw_path.with_suffix(".xlsx").name))
+    raw = pd.read_excel(workbook, sheet_name=SHEET)
+
+    is_primary = raw["variable"].str.startswith(PREFIX) & raw[
+        "variable"
+    ].str.endswith(SUFFIX)
+    subset = raw[is_primary].copy()
+
+    # Turn the variable name into a plain source name, eg.
+    # "Energy: primary demand wind (substitution method)" -> "wind".
+    subset["source"] = (
+        subset["variable"].str.replace(PREFIX, "", regex=False).str.replace(
+            SUFFIX, "", regex=False
+        )
+    )
+    subset = subset.rename(columns={"value": "demand"})
+
+    tidy = subset[COLUMN_ORDER]
+    tidy = tidy.sort_values(["source", "year"]).reset_index(drop=True)
+
+    return tidy
+
+
+# ---- #
+
+
+def main():
+    energy_demand = build_energy_demand(PATHS["raw"])
+    energy_demand.to_csv(
+        PATHS["out"],
+        index=False,
+        compression={"method": "zip", "archive_name": "energy_demand.csv"},
+    )
+    print(f"Wrote {len(energy_demand)} rows to {PATHS['out']}")
+
+
+# ---- #
+
+if __name__ == "__main__":
+    main()

jrpyprogramming-0.2.6/jrpyprogramming/dev/sectors.py

@@ -0,0 +1,147 @@
+"""
+This non-exported module creates the per-sector example CSV files used by the
+climate variant of the course, in the chapter 1 and
+chapter 3 file-concatenation and comprehension material.
+
+It reads the Seventh Carbon Budget full dataset published by the Climate Change
+Committee (CCC) directly. The raw workbook is stored zipped in
+`jrpyprogramming/data_raw/ccc_data/` so that the build is reproducible. From the
+tidy `Sector-level data` sheet we keep the direct-emissions variables (total
+and CO2), pivot them into columns, keep the `Balanced Pathway` scenario, and
+write one CSV per selected sector into `jrpyprogramming/examples/`. Each file is
+named after its sector, has the `scenario` and `sector` columns removed (the
+sector is encoded in the filename), and holds a tidy `year`, `total_emissions`,
+`co2_emissions` time series (MtCO2e).
+
+These files stand in for the base course's `data1.csv` - `data5.csv`: the
+students list them, filter by extension, and concatenate them back together
+(re-adding the sector from the filename). A single non-CSV file (`source.txt`)
+is written alongside so that the `.endswith(".csv")` filtering has something to
+exclude, exactly as the base course's `.xlsx`/`.txt` files did.
+
+They are copied into a student's working directory by
+`jrpyprogramming.data.populate_sectors()`.
+
+Run with:
+
+    python -m jrpyprogramming.dev.sectors
+"""
+
+import zipfile
+from io import BytesIO
+from pathlib import Path
+
+import pandas as pd
+
+# ---- #
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[1]
+
+PATHS = {
+    "raw": PACKAGE_ROOT
+    / "data_raw"
+    / "ccc_data"
+    / "seventh_carbon_budget_full_dataset.zip",
+    "out_dir": PACKAGE_ROOT / "examples",
+}
+
+SHEET = "Sector-level data"
+
+SCENARIO = "Balanced Pathway"
+
+# Keep the direct-emissions variables, giving each a concise column name.
+VARIABLES = {
+    "Emissions: direct emissions total": "total_emissions",
+    "Emissions: direct emissions CO2": "co2_emissions",
+}
+
+# Sectors to write out as individual files, with the filename stem to use.
+SECTORS = {
+    "Surface transport": "surface_transport",
+    "Electricity supply": "electricity_supply",
+    "Aviation": "aviation",
+    "Industry": "industry",
+    "Agriculture": "agriculture",
+}
+
+KEEP_COLUMNS = ["year", "total_emissions", "co2_emissions"]
+
+SOURCE_NOTE = (
+    "Per-sector emissions (MtCO2e), Balanced Pathway scenario.\n"
+    "Source: Climate Change Committee, Seventh Carbon Budget.\n"
+    "Each CSV is named after its sector; the sector column has been removed.\n"
+)
+
+# ---- #
+
+
+def build_sector_emissions(raw_path):
+    """
+    Read the CCC sector-level sheet and return a tidy table with one row per
+    (sector, year) for the Balanced Pathway, with the two emissions variables
+    as columns.
+    """
+    # The zip holds a single workbook named after the archive; extract it to
+    # memory since read_excel cannot open zipped files directly.
+    with zipfile.ZipFile(raw_path) as archive:
+        workbook = BytesIO(archive.read(raw_path.with_suffix(".xlsx").name))
+    raw = pd.read_excel(workbook, sheet_name=SHEET)
+
+    subset = raw[raw["variable"].isin(VARIABLES.keys())].copy()
+    subset["variable"] = subset["variable"].map(VARIABLES)
+
+    wide = subset.pivot_table(
+        index=["scenario", "sector", "year"],
+        columns="variable",
+        values="value",
+    ).reset_index()
+    wide.columns.name = None
+
+    return wide[wide["scenario"] == SCENARIO]
+
+
+def build_sector_files(out_dir):
+    """
+    Write one CSV per selected sector, plus a non-CSV source note. Returns the
+    list of files written.
+    """
+    emissions = build_sector_emissions(PATHS["raw"])
+
+    out_dir.mkdir(exist_ok=True)
+
+    # Remove any previously generated example files so the build is clean.
+    for stale in list(out_dir.glob("*.csv")) + list(out_dir.glob("*.txt")):
+        stale.unlink()
+
+    written = []
+    for sector, stem in SECTORS.items():
+        sector_data = (
+            emissions[emissions["sector"] == sector][KEEP_COLUMNS]
+            .sort_values("year")
+            .reset_index(drop=True)
+        )
+        out_path = out_dir / f"{stem}.csv"
+        sector_data.to_csv(out_path, index=False)
+        written.append(out_path)
+
+    note_path = out_dir / "source.txt"
+    note_path.write_text(SOURCE_NOTE)
+    written.append(note_path)
+
+    return written
+
+
+# ---- #
+
+
+def main():
+    written = build_sector_files(PATHS["out_dir"])
+    print(f"Wrote {len(written)} files to {PATHS['out_dir']}:")
+    for path in written:
+        print(f"  {path.name}")
+
+
+# ---- #
+
+if __name__ == "__main__":
+    main()

jrpyprogramming-0.2.6/jrpyprogramming/examples/agriculture.csv

@@ -0,0 +1,27 @@
+year,total_emissions,co2_emissions
+2025,47.04431879231096,7.11195142881007
+2026,46.55971791769261,7.023718730759533
+2027,44.91961444729086,6.56837380452751
+2028,43.08119057340664,6.107754047068191
+2029,41.07062128163186,5.640581135648146
+2030,39.2427769198489,5.176830072219891
+2031,37.46240643359306,4.819954797741994
+2032,35.79183758704355,4.463896837292482
+2033,34.30362690434493,4.116596727741165
+2034,32.97088627962682,3.77314366224367
+2035,31.88870113630172,3.430093892074354
+2036,31.30582464597946,3.116219661603278
+2037,30.85804840096916,2.802758170501625
+2038,30.32960145784595,2.489499473287159
+2039,29.78846069070192,2.176314463032735
+2040,29.24745296064348,1.863204831562803
+2041,28.9372814742712,1.804917014168791
+2042,28.52645035035353,1.74665634658448
+2043,28.22708686768913,1.688420161238338
+2044,27.92657749070909,1.630193354965281
+2045,27.62604337338858,1.572003315436226
+2046,27.37569122099639,1.562232204515042
+2047,27.12588924398758,1.552483057234836
+2048,26.87912952128276,1.54285338761824
+2049,26.63070678801907,1.533134803808428
+2050,26.38987159012214,1.524031830032308

jrpyprogramming-0.2.6/jrpyprogramming/examples/aviation.csv

@@ -0,0 +1,27 @@
+year,total_emissions,co2_emissions
+2025,36.73092377300829,36.41693106698673
+2026,35.82018879855322,35.51423624912584
+2027,35.00742550819214,34.70893024921723
+2028,34.00178520559492,33.71284523357664
+2029,33.67295409587235,33.38754490125839
+2030,33.49469016774837,33.21167610810286
+2031,32.51765107111196,32.2445676931948
+2032,31.98026143205675,31.71388757830032
+2033,31.54017292637023,31.27932211828804
+2034,31.15116485647634,30.89600687731529
+2035,30.13455308348728,29.89100051346249
+2036,30.04547641932908,29.80502798088056
+2037,29.96476684818071,29.72742640000849
+2038,29.6612303597675,29.42971764444973
+2039,29.71971799127217,29.49097946843761
+2040,29.53945662930248,29.31602496204097
+2041,28.80931109424303,28.60007655299749
+2042,27.91913517762153,27.72578687428328
+2043,27.45474016880508,27.27373996335709
+2044,26.90365477915237,26.73750382489026
+2045,25.94155768732015,25.79614781431329
+2046,25.44564450586888,25.31673961647436
+2047,24.74520842183633,24.63621389966453
+2048,24.16286024271848,24.07368980782465
+2049,23.54229515901582,23.47545768393051
+2050,22.66831879088747,22.62882756821037

jrpyprogramming-0.2.6/jrpyprogramming/examples/electricity_supply.csv

@@ -0,0 +1,27 @@
+year,total_emissions,co2_emissions
+2025,32.50725713374266,32.44196100652248
+2026,29.83790830913824,29.77797400434832
+2027,27.16855948453379,27.11398700217416
+2028,24.49921065992936,24.45
+2029,17.13942733489128,17.105
+2030,9.77964400985319,9.759999999999998
+2031,8.64235958862539,8.625
+2032,7.505075167397589,7.490000000000002
+2033,6.857106950897744,6.843333333333334
+2034,6.209138734397911,6.196666666666665
+2035,5.56117051789807,5.549999999999997
+2036,5.36878407835998,5.357999999999997
+2037,5.176397638821882,5.165999999999997
+2038,4.984011199283785,4.973999999999997
+2039,4.79162475974568,4.781999999999996
+2040,4.59923832020759,4.589999999999996
+2041,4.038111204888153,4.030000000000001
+2042,3.476984089568695,3.469999999999999
+2043,2.915856974249259,2.909999999999997
+2044,2.354729858929822,2.350000000000001
+2045,1.793602743610371,1.789999999999999
+2046,1.635284736073807,1.631999999999998
+2047,1.476966728537256,1.474000000000004
+2048,1.318648721000699,1.316000000000003
+2049,1.160330713464148,1.158000000000001
+2050,1.002012705927584,1.0

jrpyprogramming-0.2.6/jrpyprogramming/examples/industry.csv

@@ -0,0 +1,27 @@
+year,total_emissions,co2_emissions
+2025,44.58577948677008,44.05894839030271
+2026,41.76215491141179,41.25758933951977
+2027,39.70567192073906,39.23765240655013
+2028,37.26010561856675,36.83431447995322
+2029,34.19785316556313,33.81117841957851
+2030,31.43245031291405,31.07353635510041
+2031,28.69997029599952,28.36819676278073
+2032,26.59501095792233,26.28617230178295
+2033,24.84076273628184,24.55131752501302
+2034,22.94586216257986,22.67464332054091
+2035,21.14735223607432,20.89904650039935
+2036,19.27633788073949,19.05109559649581
+2037,15.7653474545877,15.59620736142275
+2038,12.9384589438616,12.80140603563029
+2039,12.08381263593697,11.95654097216175
+2040,11.15047714637436,11.03178833357156
+2041,9.187758972035972,9.083599662502756
+2042,8.161045397245623,8.068761566542541
+2043,7.122371590722622,7.040473951764909
+2044,6.340010755308043,6.266324996154999
+2045,5.598491109906249,5.532365132638375
+2046,4.791837461554515,4.731966528251405
+2047,4.383266305448885,4.329026897175616
+2048,3.977737419529227,3.929071887534263
+2049,3.774533739035476,3.72590477210364
+2050,3.565474949937183,3.516870745882208

jrpyprogramming-0.2.6/jrpyprogramming/examples/source.txt

@@ -0,0 +1,3 @@
+Per-sector emissions (MtCO2e), Balanced Pathway scenario.
+Source: Climate Change Committee, Seventh Carbon Budget.
+Each CSV is named after its sector; the sector column has been removed.

jrpyprogramming-0.2.6/jrpyprogramming/examples/surface_transport.csv

@@ -0,0 +1,27 @@
+year,total_emissions,co2_emissions
+2025,99.12272664305519,98.25403855675562
+2026,94.00545196720526,93.18324933151627
+2027,88.46829694145109,87.692118829643
+2028,81.9631670476133,81.24051515232904
+2029,75.54235046364245,74.87020128594503
+2030,68.55089525927193,67.93090887662072
+2031,62.00366564071578,61.43432616860417
+2032,55.49538901005911,54.97921156162987
+2033,49.35226948036563,48.88829574478177
+2034,43.29431972460326,42.88441284920134
+2035,36.9826117147182,36.62787683374223
+2036,31.70591627163367,31.40105788566954
+2037,26.91955426062552,26.66063915889774
+2038,22.56536583866087,22.34890270709492
+2039,18.61995627199961,18.44222160728471
+2040,14.86378564829454,14.72182848513786
+2041,11.69090865447991,11.57930543734517
+2042,9.037940995623742,8.951534692161857
+2043,6.870212520242049,6.804186723328982
+2044,5.149414108151774,5.099362380047054
+2045,3.820839623560758,3.782803243875009
+2046,2.834962923360678,2.805657916263755
+2047,2.130571272650968,2.107463740688843
+2048,1.63534027428399,1.616550287951554
+2049,1.294459934736096,1.278532401102467
+2050,1.07020023620143,1.056053934053608

{jrpyprogramming-0.2.4 → jrpyprogramming-0.2.6}/pyproject.toml

@@ -1,15 +1,15 @@
 [tool.poetry]
 name = "jrpyprogramming"
-version = "0.2.4"
+version = "0.2.6"
 description = "Jumping Rivers: Programming with Python"
 authors = ["Jumping Rivers <info@jumpingrivers.com>"]
 
 [tool.poetry.dependencies]
 python = ">=3.9"
-pandas = "^1.5"
-numpy = "^1.26"
+pandas = "^2.2.0"
+numpy = "^2.0"
 matplotlib = "^3.5"
-jrpyintroduction = ">=0.2.2"
+jrpyintroduction = ">=0.3.8"
 
 [build-system]
 requires = ["poetry-core>=1.0.0"]

jrpyprogramming-0.2.4/jrpyprogramming/__version__.py

@@ -1 +0,0 @@
-__version__ = "0.2.4"

jrpyprogramming-0.2.4/jrpyprogramming/vignettes.py

@@ -1,42 +0,0 @@
-import webbrowser
-from pkg_resources import resource_listdir
-from pkg_resources import resource_filename
-
-
-def browse():
-    """
-    List all of the vignettes available for this package.
-    """
-    outs = _get_vignette_titles()
-
-    if len(outs) > 0:
-        print("\nAvailable documents: \n")
-        print("\n".join(outs))
-        print(f"\nTo open use e.g load('{outs[0]}')\n")
-    else:
-        print("\nNo documents available\n")
-
-
-def load(name):
-    """
-    Open a particular vignette from the package.
-    """
-    outs = _get_vignette_titles()
-    if name in outs:
-        path = resource_filename("jrpyprogramming", f"vignettes/{name}")
-        webbrowser.open_new(path)
-    else:
-        print(f"\nVignette '{name}' not found")
-        browse()
-
-
-def _get_vignette_titles():
-    x = resource_listdir("jrpyprogramming", "vignettes")
-    # grab only those which are pdfs or html
-    pdfs = [file for file in x if file.endswith(".pdf")]
-    htmls = [file for file in x if file.endswith(".html")]
-    # Concat pdfs and htmls
-    outs = pdfs + htmls
-    # Return in some legible order
-    outs.sort()
-    return outs