perfectdays 0.0.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. perfectdays/__init__.py +14 -0
  2. perfectdays/api/__init__.py +13 -0
  3. perfectdays/api/formats/__init__.py +42 -0
  4. perfectdays/api/formats/reho.py +126 -0
  5. perfectdays/api/frontend.py +91 -0
  6. perfectdays/api/reho.py +120 -0
  7. perfectdays/api/routing.py +101 -0
  8. perfectdays/clusteringfactory/__init__.py +6 -0
  9. perfectdays/clusteringfactory/clustering.py +230 -0
  10. perfectdays/clusteringfactory/kmedoids.py +110 -0
  11. perfectdays/clusteringfactory/metrics.py +71 -0
  12. perfectdays/clusteringfactory/periods.py +106 -0
  13. perfectdays/clusteringfactory/quality.py +230 -0
  14. perfectdays/clusteringfactory/result.py +63 -0
  15. perfectdays/sources/__init__.py +10 -0
  16. perfectdays/sources/base.py +121 -0
  17. perfectdays/sources/files.py +68 -0
  18. perfectdays/sources/pvgis.py +64 -0
  19. perfectdays/sources/swiss.py +115 -0
  20. perfectdays/swissweathergrid/__init__.py +10 -0
  21. perfectdays/swissweathergrid/cell_access/__init__.py +8 -0
  22. perfectdays/swissweathergrid/cell_access/ch2025.py +200 -0
  23. perfectdays/swissweathergrid/cell_access/query.py +421 -0
  24. perfectdays/swissweathergrid/cell_access/zenodo.py +131 -0
  25. perfectdays/swissweathergrid/core/__init__.py +8 -0
  26. perfectdays/swissweathergrid/core/ch2025.py +82 -0
  27. perfectdays/swissweathergrid/core/fetch.py +57 -0
  28. perfectdays/swissweathergrid/core/geo.py +218 -0
  29. perfectdays/swissweathergrid/core/wsl.py +259 -0
  30. perfectdays/swissweathergrid/data/at_meta.json +1 -0
  31. perfectdays/swissweathergrid/data/imis_meta.txt +129 -0
  32. perfectdays/swissweathergrid/data/lakes_osm.json +116311 -0
  33. perfectdays/swissweathergrid/data/smn_meta.csv +159 -0
  34. perfectdays/swissweathergrid/data/swiss_border_osm.json +57493 -0
  35. perfectdays/swissweathergrid/data/switzerland.geojson +9684 -0
  36. perfectdays/swissweathergrid/data/wsl_change_iswr.csv +41581 -0
  37. perfectdays/swissweathergrid/data/wsl_delta_tas.csv +43849 -0
  38. perfectdays/swissweathergrid/grid_building/__init__.py +8 -0
  39. perfectdays/swissweathergrid/grid_building/__main__.py +4 -0
  40. perfectdays/swissweathergrid/grid_building/builder.py +276 -0
  41. perfectdays/swissweathergrid/grid_building/pipeline.py +500 -0
  42. perfectdays/swissweathergrid/grid_building/postgres.py +497 -0
  43. perfectdays/swissweathergrid/grid_building/scenarios.py +415 -0
  44. perfectdays/swissweathergrid/grid_building/solution.py +150 -0
  45. perfectdays/swissweathergrid/grid_building/storage.py +111 -0
  46. perfectdays/swissweathergrid/interpolation_method/__init__.py +11 -0
  47. perfectdays/swissweathergrid/interpolation_method/covariants_computation.py +795 -0
  48. perfectdays/swissweathergrid/interpolation_method/interpolation.py +244 -0
  49. perfectdays/swissweathergrid/interpolation_method/stations.py +694 -0
  50. perfectdays/swissweathergrid/interpolation_method/validation.py +550 -0
  51. perfectdays/swissweathergrid/paths.py +25 -0
  52. perfectdays-0.0.1.dist-info/METADATA +196 -0
  53. perfectdays-0.0.1.dist-info/RECORD +56 -0
  54. perfectdays-0.0.1.dist-info/WHEEL +5 -0
  55. perfectdays-0.0.1.dist-info/licenses/LICENSE +201 -0
  56. perfectdays-0.0.1.dist-info/top_level.txt +1 -0
@@ -0,0 +1,14 @@
1
+ """Hourly weather anywhere in Europe, shaped into typical periods.
2
+
3
+ Three layers: `sources` (with `swissweathergrid`, the 1 km Swiss grid, and
4
+ PVGIS elsewhere) provides hourly years, `clusteringfactory` reduces them to
5
+ typical periods, and `api` picks a source for a location and returns the
6
+ shape a model asks for, REHO's included (`perfectdays.api.reho`).
7
+ """
8
+ from .api import reho
9
+ from .api.frontend import get_typical_periods, get_weather
10
+ from .clusteringfactory import ClusterQuality, TypicalPeriods, cluster_periods
11
+ from .sources import SourceUnavailable
12
+
13
+ __all__ = ["get_weather", "get_typical_periods", "cluster_periods",
14
+ "TypicalPeriods", "ClusterQuality", "SourceUnavailable", "reho"]
@@ -0,0 +1,13 @@
1
+ """The entry points other tools call: weather or typical periods for a place.
2
+
3
+ `get_weather` and `get_typical_periods` are the general entry points;
4
+ `reho` speaks REHO's arguments and writes REHO's files.
5
+ """
6
+ from . import reho
7
+ from .frontend import get_typical_periods, get_weather
8
+ from .reho import generate_weather_data, get_cluster_file_ID
9
+ from .routing import default_sources, load_weather
10
+
11
+ __all__ = ["get_weather", "get_typical_periods", "load_weather",
12
+ "default_sources", "reho", "generate_weather_data",
13
+ "get_cluster_file_ID"]
@@ -0,0 +1,42 @@
1
+ """Output shapes for typical periods."""
2
+ from __future__ import annotations
3
+
4
+ from pathlib import Path
5
+
6
+ import pandas as pd
7
+
8
+ from ...clusteringfactory.result import TypicalPeriods
9
+ from .reho import write_reho
10
+
11
+ FORMATS = ("typical", "dataframe", "reho", "csv")
12
+
13
+
14
+ def shape(tp: TypicalPeriods, output_format: str, weather: pd.DataFrame,
15
+ output_dir: str | Path | None = None):
16
+ """Typical periods in the requested shape.
17
+
18
+ - `"typical"`: the `TypicalPeriods` object itself.
19
+ - `"dataframe"`: one long frame, (period, hour) rows with a frequency.
20
+ - `"reho"`: REHO's weather files in `output_dir`; returns the directory.
21
+ - `"csv"`: `typical_periods.csv` and `assignment.csv` in `output_dir`;
22
+ returns the directory.
23
+ """
24
+ if output_format not in FORMATS:
25
+ raise ValueError(f"unknown output_format {output_format!r}: choose "
26
+ f"among {', '.join(map(repr, FORMATS))}")
27
+ if output_format == "typical":
28
+ return tp
29
+ if output_format == "dataframe":
30
+ return tp.to_frame()
31
+ if output_dir is None:
32
+ raise ValueError(f"output_format {output_format!r} needs output_dir")
33
+ if output_format == "reho":
34
+ return write_reho(tp, output_dir, weather)
35
+ directory = Path(output_dir)
36
+ directory.mkdir(parents=True, exist_ok=True)
37
+ tp.to_frame().to_csv(directory / "typical_periods.csv")
38
+ tp.assignment.to_csv(directory / "assignment.csv")
39
+ return directory
40
+
41
+
42
+ __all__ = ["shape", "write_reho", "FORMATS"]
@@ -0,0 +1,126 @@
1
+ """Typical periods as the files REHO reads.
2
+
3
+ Five files in one directory, as REHO's `write_weather_files` writes them:
4
+
5
+ - `annual_data.csv`: the hourly weather clustered (`time(UTC)`, `Text`,
6
+ `Irr`, `Weekday`), every year of it.
7
+ - `typical_data.csv`: the hours of every period -- the typical periods, the
8
+ reference year's leftover hours if the duration does not divide the year,
9
+ then the coldest and the warmest hour.
10
+ - `frequency.csv`: the AMPL sets and parameters `Period`, `PeriodStandard`,
11
+ `dp` (periods of a year each one stands for) and `TimeEnd`.
12
+ - `index.csv`: `PeriodOfYear` and `TimeOfYear` of every hour of the
13
+ reference year.
14
+ - `timestamp.csv`: per period, the `Date` it starts, its number (`Day`),
15
+ `Frequency`, the `SourceYear` and `SourcePeriod` (period of that year,
16
+ from 1) it was taken from, and `Weekday` when clustered on.
17
+
18
+ `SourceYear` and `SourcePeriod` replace REHO's `RowOffset`, an hour offset
19
+ into a single year that pooled years cannot express.
20
+ """
21
+ from __future__ import annotations
22
+
23
+ from pathlib import Path
24
+
25
+ import numpy as np
26
+ import pandas as pd
27
+
28
+ from ...clusteringfactory.periods import with_weekday
29
+ from ...clusteringfactory.result import TypicalPeriods
30
+
31
+ #: Canonical column -> REHO column.
32
+ REHO_COLUMNS = {"temperature": "Text", "ghi": "Irr", "weekday": "Weekday"}
33
+
34
+
35
+ def write_reho(tp: TypicalPeriods, directory: str | Path,
36
+ weather: pd.DataFrame) -> Path:
37
+ """Write typical periods as REHO's weather files.
38
+
39
+ Args:
40
+ tp: the typical periods.
41
+ directory: created if needed.
42
+ weather: the canonical hourly frame `tp` was clustered from.
43
+
44
+ Returns:
45
+ The directory.
46
+ """
47
+ directory = Path(directory)
48
+ directory.mkdir(parents=True, exist_ok=True)
49
+ weekday = "weekday" in tp.features
50
+ columns = ["temperature", "ghi"] + (["weekday"] if weekday else [])
51
+ duration = tp.period_duration
52
+
53
+ annual = with_weekday(weather)[["temperature", "ghi", "weekday"]]
54
+ annual = annual.rename(columns=REHO_COLUMNS)
55
+ annual["Weekday"] = annual.Weekday.astype(int)
56
+ annual.index = annual.index.tz_localize("UTC")
57
+ annual.index.name = "time(UTC)"
58
+ annual.to_csv(directory / "annual_data.csv")
59
+
60
+ # every period in file order: typical, leftover, coldest, warmest
61
+ blocks = [tp.values[columns].to_numpy()]
62
+ durations = list(tp.frequency)
63
+ lengths = [duration] * tp.n_periods
64
+ starts = list(tp.origin.start)
65
+ sources = list(zip(tp.origin.year, tp.origin.period_of_year))
66
+ if tp.leftover is not None:
67
+ blocks.append(tp.leftover[columns].to_numpy())
68
+ durations.append(1)
69
+ lengths.append(len(tp.leftover))
70
+ starts.append(tp.leftover.index[0])
71
+ sources.append((tp.reference_year, tp.sequence.index.max() + 1))
72
+ for name in ("min", "max"):
73
+ row = tp.extremes.loc[name]
74
+ blocks.append(row[columns].to_numpy(dtype=float)[None, :])
75
+ durations.append(1)
76
+ lengths.append(1)
77
+ starts.append(row.start)
78
+ sources.append((int(row.year), int(row.period_of_year)))
79
+ typical = pd.DataFrame(np.concatenate(blocks),
80
+ columns=[REHO_COLUMNS[c] for c in columns])
81
+ typical.to_csv(directory / "typical_data.csv", index=False)
82
+
83
+ n = len(durations)
84
+ with open(directory / "frequency.csv", "w") as file:
85
+ file.write("set Period := \n")
86
+ file.writelines(f"{p}\n" for p in range(1, n + 1))
87
+ file.write(";\n")
88
+ file.write("set PeriodStandard := \n")
89
+ file.writelines(f"{p}\n" for p in range(1, n - 1))
90
+ file.write(";\n")
91
+ file.write("param: dp := \n")
92
+ file.writelines(f"{p} {_number(d)}\n"
93
+ for p, d in enumerate(durations, start=1))
94
+ file.write(";\n")
95
+ file.write("param: TimeEnd := \n")
96
+ file.writelines(f"{p} {t}\n" for p, t in enumerate(lengths, start=1))
97
+ file.write(";\n")
98
+
99
+ sequence = list(tp.sequence)
100
+ if tp.leftover is not None:
101
+ sequence.append(tp.n_periods + 1)
102
+ with open(directory / "index.csv", "w") as file:
103
+ file.write("param : PeriodOfYear TimeOfYear := \n")
104
+ hour = 1
105
+ for period in sequence:
106
+ for t in range(1, lengths[period - 1] + 1):
107
+ file.write(f"{hour} {period} {t}\n")
108
+ hour += 1
109
+ file.write(";\n")
110
+
111
+ first_rows = np.cumsum([0] + lengths[:-1])
112
+ stamps = pd.DataFrame({
113
+ "Date": [pd.Timestamp(s).strftime("%Y-%m-%d %H:%M:%S") for s in starts],
114
+ "Day": range(1, n + 1),
115
+ "Frequency": [_number(d) for d in durations],
116
+ "SourceYear": [int(y) for y, _ in sources],
117
+ "SourcePeriod": [int(p) for _, p in sources]})
118
+ if weekday:
119
+ stamps["Weekday"] = typical.Weekday.to_numpy()[first_rows]
120
+ stamps.to_csv(directory / "timestamp.csv", index=False)
121
+ return directory
122
+
123
+
124
+ def _number(x):
125
+ """An integer when it is one, so single-year files read as REHO's do."""
126
+ return int(x) if float(x).is_integer() else float(x)
@@ -0,0 +1,91 @@
1
+ """The two calls other tools make: hourly weather, and typical periods.
2
+
3
+ Example::
4
+
5
+ from perfectdays import get_typical_periods
6
+
7
+ tp = get_typical_periods(46.52, 6.63, periods=10) # Lausanne
8
+ tp, quality = get_typical_periods(48.85, 2.35, years=[2019, 2020],
9
+ output_format="dataframe",
10
+ clustering_evaluation=True)
11
+ quality.stability.plot()
12
+ """
13
+ from __future__ import annotations
14
+
15
+ from pathlib import Path
16
+
17
+ import pandas as pd
18
+
19
+ from ..clusteringfactory import cluster_periods
20
+ from .formats import shape
21
+ from .routing import load_weather
22
+
23
+
24
+ def get_weather(lat: float, lon: float, years: int | list[int] | None = None,
25
+ scenario: str = "current", source: str | None = None,
26
+ files=None) -> pd.DataFrame:
27
+ """Hourly temperature and irradiance at a point in Europe.
28
+
29
+ Args:
30
+ lat, lon: WGS84 degrees.
31
+ years: a year, several, or None: every stored year in Switzerland,
32
+ the PVGIS typical meteorological year elsewhere.
33
+ scenario: `"current"`, or a climate scenario such as `"rcp45_2050"`
34
+ (Switzerland only for now).
35
+ source: force `"swissweathergrid"` or `"pvgis"`; by default the
36
+ Swiss grid in Switzerland, PVGIS elsewhere, each falling back to
37
+ the next when it cannot serve.
38
+ files: annual hourly data overriding every source: CSV paths or
39
+ DataFrames, one or more years each (REHO's `Text`/`Irr` columns
40
+ are understood).
41
+
42
+ Returns:
43
+ Hourly frame, 8760 rows a year, with `temperature` [degC] and `ghi`
44
+ [W/m^2] at least; the source used is in `attrs["source"]`.
45
+ """
46
+ return load_weather(lat, lon, years, scenario, source, files)
47
+
48
+
49
+ def get_typical_periods(lat: float | None, lon: float | None,
50
+ years: int | list[int] | None = None, *,
51
+ periods: int | str = 10, period_duration: int = 24,
52
+ attributes=("T", "I", "W"),
53
+ scenario: str = "current", source: str | None = None,
54
+ files=None, output_format: str = "typical",
55
+ output_dir: str | Path | None = None,
56
+ clustering_evaluation: bool = False,
57
+ per_month: bool = False,
58
+ reference_year: int | None = None,
59
+ n_restarts: int = 20, seed: int | None = 0,
60
+ k_range=None):
61
+ """Typical periods of the weather at a point, in the shape asked for.
62
+
63
+ Args:
64
+ lat, lon: WGS84 degrees; may be None when `files` are given.
65
+ years, scenario, source, files: as for `get_weather`. Several years
66
+ are clustered together.
67
+ periods: number of typical periods, or `"auto"` for REHO's rule.
68
+ period_duration: hours per period.
69
+ attributes: clustered on, as REHO codes `"T"`, `"I"`, `"W"` or
70
+ column names.
71
+ output_format: `"typical"` (a `TypicalPeriods`), `"dataframe"`,
72
+ `"reho"` or `"csv"` (files in `output_dir`).
73
+ output_dir: where `"reho"` and `"csv"` write.
74
+ clustering_evaluation: also assess the clustering over a range of
75
+ numbers of periods.
76
+ per_month, reference_year, n_restarts, seed, k_range: see
77
+ `perfectdays.clusteringfactory.cluster_periods`.
78
+
79
+ Returns:
80
+ The output; with `clustering_evaluation`, the tuple
81
+ `(output, ClusterQuality)`.
82
+ """
83
+ if files is None and (lat is None or lon is None):
84
+ raise ValueError("give lat and lon, or files")
85
+ weather = load_weather(lat, lon, years, scenario, source, files)
86
+ tp = cluster_periods(weather, periods, period_duration, attributes,
87
+ per_month=per_month, n_restarts=n_restarts, seed=seed,
88
+ reference_year=reference_year,
89
+ evaluate=clustering_evaluation, k_range=k_range)
90
+ out = shape(tp, output_format, weather, output_dir)
91
+ return (out, tp.quality) if clustering_evaluation else out
@@ -0,0 +1,120 @@
1
+ """REHO's weather step, with REHO's arguments.
2
+
3
+ REHO calls `generate_weather_data(cluster, qbuildings_data, directory)` and
4
+ names its cache with `get_cluster_file_ID(cluster)`. The `cluster` keys REHO
5
+ has always used keep their meaning:
6
+
7
+ - `Location` (str): a label, used in the file ID only.
8
+ - `Periods` (int), `PeriodDuration` (int, hours).
9
+ - `Attributes`: among `"T"` (temperature), `"I"` (irradiance), `"W"`
10
+ (weekday).
11
+ - `custom_weather` (path): annual data overriding every source.
12
+ - `per_month` (bool): cluster each month apart.
13
+
14
+ and new, optional ones:
15
+
16
+ - `Year`: a year or a list of years, clustered together. Without it, every
17
+ stored year in Switzerland, the PVGIS TMY elsewhere.
18
+ - `Scenario`: a climate scenario such as `"rcp45_2050"` (Switzerland only).
19
+ - `Source`: force `"swissweathergrid"` or `"pvgis"`.
20
+ - `Coordinates`: `(lat, lon)` in WGS84, instead of the first building's.
21
+ """
22
+ from __future__ import annotations
23
+
24
+ from ..clusteringfactory import TypicalPeriods, cluster_periods
25
+ from ..swissweathergrid.core.geo import lv95_to_wgs84
26
+ from .formats.reho import write_reho
27
+ from .routing import load_weather
28
+
29
+ #: Clustering attribute -> the suffix it contributes to the file ID.
30
+ CLUSTER_ATTRIBUTE_SUFFIXES = {"T": "_T", "I": "_I", "W": "_W"}
31
+
32
+
33
+ def location(cluster: dict, qbuildings_data: dict) -> tuple:
34
+ """WGS84 (lat, lon) of the district; (None, None) if nothing gives one.
35
+
36
+ `cluster["Coordinates"]` wins; otherwise the first building's LV95
37
+ position in metres (EPSG:2056), as REHO has always taken it.
38
+ """
39
+ if "Coordinates" in cluster:
40
+ lat, lon = cluster["Coordinates"]
41
+ return float(lat), float(lon)
42
+ try:
43
+ building = next(iter(qbuildings_data["buildings_data"].values()))
44
+ except (KeyError, StopIteration, TypeError, AttributeError):
45
+ return None, None
46
+ lat, lon = lv95_to_wgs84(building["x"] / 1000.0, building["y"] / 1000.0)
47
+ return float(lat), float(lon)
48
+
49
+
50
+ def generate_weather_data(cluster: dict, qbuildings_data: dict,
51
+ clustering_directory) -> TypicalPeriods:
52
+ """Typical periods for a REHO run, written as REHO's weather files.
53
+
54
+ Args:
55
+ cluster: REHO's clustering options (see the module docstring).
56
+ qbuildings_data: REHO's buildings; the first one locates the district.
57
+ clustering_directory: where the files go.
58
+
59
+ Returns:
60
+ The typical periods written.
61
+ """
62
+ lat, lon = location(cluster, qbuildings_data)
63
+ files = cluster.get("custom_weather")
64
+ if files is None and lat is None:
65
+ raise ValueError("no location: give buildings with coordinates, "
66
+ "cluster['Coordinates'] or cluster['custom_weather']")
67
+ weather = load_weather(lat, lon, cluster.get("Year"),
68
+ cluster.get("Scenario", "current"),
69
+ cluster.get("Source"), files)
70
+ tp = cluster_periods(weather, cluster["Periods"], cluster["PeriodDuration"],
71
+ cluster["Attributes"],
72
+ per_month=cluster.get("per_month", False))
73
+ write_reho(tp, clustering_directory, weather)
74
+ return tp
75
+
76
+
77
+ def get_cluster_file_ID(cluster: dict) -> str:
78
+ """Identifier of a location and its clustering options.
79
+
80
+ `Location_Periods_PeriodDuration` and the attributes in the canonical
81
+ order T, I, W, then -- only when set -- the years, the scenario, the
82
+ source and per-month clustering, so that runs differing in any of them
83
+ never share cached files, while the IDs of existing runs are unchanged.
84
+
85
+ Examples:
86
+ >>> get_cluster_file_ID({'Location': 'Geneva', 'Attributes': ['T', 'I', 'W'],
87
+ ... 'Periods': 10, 'PeriodDuration': 24})
88
+ 'Geneva_10_24_T_I_W'
89
+ >>> get_cluster_file_ID({'Location': 'Geneva', 'Attributes': ['T', 'I'],
90
+ ... 'Periods': 10, 'PeriodDuration': 24,
91
+ ... 'Year': [2021, 2022, 2023], 'Scenario': 'rcp45_2050'})
92
+ 'Geneva_10_24_T_I_2021-2023_rcp45_2050'
93
+ """
94
+ unknown = [a for a in cluster["Attributes"]
95
+ if a not in CLUSTER_ATTRIBUTE_SUFFIXES]
96
+ if unknown:
97
+ raise ValueError(
98
+ f"Unknown clustering attribute(s) {', '.join(map(repr, unknown))}: "
99
+ f"choose among {', '.join(map(repr, CLUSTER_ATTRIBUTE_SUFFIXES))}.")
100
+ file_id = (f"{cluster['Location']}_{cluster['Periods']}_"
101
+ f"{cluster['PeriodDuration']}")
102
+ file_id += "".join(suffix for a, suffix in CLUSTER_ATTRIBUTE_SUFFIXES.items()
103
+ if a in cluster["Attributes"])
104
+ if cluster.get("Year") is not None:
105
+ file_id += "_" + _years_label(cluster["Year"])
106
+ if cluster.get("Scenario", "current") != "current":
107
+ file_id += f"_{cluster['Scenario']}"
108
+ if cluster.get("Source"):
109
+ file_id += f"_{cluster['Source']}"
110
+ if cluster.get("per_month"):
111
+ file_id += "_monthly"
112
+ return file_id
113
+
114
+
115
+ def _years_label(years) -> str:
116
+ """`2019`, `2019-2021` for a run of years, `2019+2021` otherwise."""
117
+ years = sorted({int(years)} if isinstance(years, int) else set(map(int, years)))
118
+ if len(years) > 1 and years == list(range(years[0], years[-1] + 1)):
119
+ return f"{years[0]}-{years[-1]}"
120
+ return "+".join(map(str, years))
@@ -0,0 +1,101 @@
1
+ """Which source serves a location, and what happens when it cannot.
2
+
3
+ Sources are tried in order -- the Swiss grid first, then PVGIS -- and the
4
+ first that covers the request and delivers it wins. A source that fails,
5
+ for lack of coverage, data or network, hands over to the next one with a
6
+ warning, so the loss of any one provider degrades the result instead of
7
+ breaking it. The source actually used is in `attrs["source"]`.
8
+ """
9
+ from __future__ import annotations
10
+
11
+ import warnings
12
+
13
+ import pandas as pd
14
+
15
+ from ..swissweathergrid.core.geo import in_switzerland
16
+ from ..sources import (PVGISSource, SourceUnavailable, SwissSource,
17
+ WeatherSource, read_weather_files)
18
+
19
+
20
+ def default_sources() -> list[WeatherSource]:
21
+ """The sources tried when none is forced, most accurate first."""
22
+ return [SwissSource(), PVGISSource()]
23
+
24
+
25
+ def load_weather(lat: float, lon: float,
26
+ years: int | list[int] | None = None,
27
+ scenario: str = "current",
28
+ source: str | WeatherSource | None = None,
29
+ files=None,
30
+ sources: list[WeatherSource] | None = None) -> pd.DataFrame:
31
+ """Hourly weather at a point, from the best source able to serve it.
32
+
33
+ Args:
34
+ lat, lon: WGS84 degrees.
35
+ years: a year, a list of years, or None for the source's default --
36
+ every stored year in Switzerland, a TMY elsewhere.
37
+ scenario: `"current"`, or a climate scenario such as `"rcp45_2050"`
38
+ (Switzerland only for now).
39
+ source: force one source, by name or instance; no fallback then.
40
+ files: user data overriding every source (see `read_weather_files`).
41
+ sources: the candidate list, replacing `default_sources()`.
42
+
43
+ Returns:
44
+ A canonical weather frame (see `perfectdays.sources.base`).
45
+
46
+ Raises:
47
+ SourceUnavailable: no source could serve the request.
48
+ NotImplementedError: a climate scenario outside Switzerland.
49
+ """
50
+ if files is not None:
51
+ out = read_weather_files(files)
52
+ out.attrs.update(lat=lat, lon=lon)
53
+ return out
54
+ if scenario != "current" and not in_switzerland(lat, lon):
55
+ raise NotImplementedError(
56
+ f"climate scenario {scenario!r} is available in Switzerland only "
57
+ "for now")
58
+
59
+ candidates = sources if sources is not None else default_sources()
60
+ if source is not None:
61
+ candidates = [_pick(source, candidates)]
62
+ requested = [years] if isinstance(years, int) else years
63
+
64
+ reasons = []
65
+ for src in candidates:
66
+ if not src.applies(lat, lon):
67
+ if source is None:
68
+ continue
69
+ reasons.append(f"{src.name}: the point is outside its area")
70
+ continue
71
+ wanted = requested or src.default_years(lat, lon, scenario)
72
+ reason = src.covers(lat, lon, wanted, scenario)
73
+ if reason is None and not wanted:
74
+ reason = "no default year"
75
+ if reason is None:
76
+ try:
77
+ out = src.load(lat, lon, wanted, scenario)
78
+ except SourceUnavailable as e:
79
+ reason = str(e)
80
+ else:
81
+ if reasons:
82
+ warnings.warn(
83
+ f"weather from {src.name}, because "
84
+ + "; ".join(reasons), stacklevel=2)
85
+ return out
86
+ reasons.append(f"{src.name}: {reason}")
87
+
88
+ raise SourceUnavailable(f"no source could serve ({lat}, {lon}), years "
89
+ f"{years}: " + "; ".join(reasons))
90
+
91
+
92
+ def _pick(source, candidates) -> WeatherSource:
93
+ """A forced source, by instance or by name."""
94
+ if isinstance(source, WeatherSource):
95
+ return source
96
+ known = {s.name: s for s in candidates}
97
+ known.update({s.name: s for s in default_sources() if s.name not in known})
98
+ if source not in known:
99
+ raise ValueError(f"unknown source {source!r}: choose among "
100
+ f"{', '.join(map(repr, known))}")
101
+ return known[source]
@@ -0,0 +1,6 @@
1
+ """Hourly years reduced to typical periods, and how good the reduction is."""
2
+ from .clustering import cluster_periods
3
+ from .quality import ClusterQuality
4
+ from .result import TypicalPeriods
5
+
6
+ __all__ = ["cluster_periods", "TypicalPeriods", "ClusterQuality"]