Aggregation reporter: select sensors by asset, name and unit

[Ahmad-Wahid]

Description

A site usually wants its sensors as one aggregated signal — all the PV on site, so it can be
forecast and used in flex scheduling. Until now the AggregatorReporter could do that only if every
sensor was named by hand in the report parameters, which does not survive an inverter being added.

The reporter now selects its own sensors, through four new config fields:

• asset — aggregate the sensors of this asset and of all of its offspring, so pointing at a site asset covers everything below it.
• sensors — aggregate these sensors, listed by ID.
• sensor_name_pattern — keep only the sensors whose name matches this regular expression.
• sensor_units — keep only the sensors recording in one of these units, or in a unit measuring the same quantity, so ["MW"] also keeps a sensor recording in kW, but not one recording in MWh.

method: sum
asset: 3
sensor_name_pattern: "(?i)pv"
sensor_units: ["MW"]

Sensors named in the input parameters still work, and are read as described there; the selected
sensors are added to them. input is therefore no longer required in the parameters — a selection in
the config is enough, and a reporter that selects nothing at all says so, rather than failing later
inside Pandas.

Units and resolutions are reconciled with the output sensor. A discovered sensor cannot be
hand-checked, so values are converted to the unit of the output sensor and read at its resolution.
That is what makes a roof recording 100 kW in quarter-hourly events and a carport recording 0.2 MW in
hourly events add up to 0.3 MW on an hourly MW sensor. Passing a resolution parameter still wins
over the output sensor's, convert_units: false aggregates the raw values, a sensor without a unit is
never converted (an empty unit says nothing about what its values mean, so it draws a warning), and a
sensor whose quantity the output sensor cannot express — a temperature onto a power sensor — is
reported as an error instead of being silently added up.

The output sensor is left out of the aggregation. A report is often recorded on a sensor of the
very asset being aggregated, and reading it back in would fold each run's own previous output into the
next one.

Accountability. The selection lives in the config, not in the parameters, so it is recorded on
the reporter's data source alongside the method and weights, and a changed selection yields a new data
source. input_sensors reports the selected sensors too, so an automation validating what a reporter
reads sees the same sensors the reporter will read.

• Added changelog item in documentation/changelog.rst

How to test

pytest flexmeasures/data/models/reporting/tests/test_aggregator.py

Eight tests are added, on a fixture whose PV sensors sit on a child and a grandchild asset, record in
kW and MW at quarter-hourly and hourly resolutions, and whose output sensor already holds a previous
report of 99 MW.

Each was verified to fail with the code it covers disabled — the breaks used were: dropping the
name-pattern filter, dropping the units filter, including the output sensor, skipping the unit
conversion, ignoring convert_units, not defaulting the resolution to the output sensor's, dropping
the empty-selection error, not overriding input_sensors, ignoring the sensors list, not walking
asset.offspring, skipping the regex validation, and taking asset as a plain int rather than an
asset. Every new test went red under at least one of them, and the whole set is green with the code in
place.

The 15 pre-existing aggregator tests are untouched and still pass, as do the reporting, schema, CLI
and API report-trigger suites.

Further improvements

Two items of #2520 depend on PRs that have not landed yet, so they are noted rather than done here:

• Running as an automation (Reports as jobs and as automations #2297). Nothing in this PR gets in the way: the selection sits in the
  config, which is exactly what Reports as jobs and as automations #2297 pins on a report automation's data source, and input_sensors
  resolves the selected sensors so the output-scope check has something to check. Worth re-testing
  end to end once Reports as jobs and as automations #2297 merges.
• A prepared template (Prepared report templates #2300). A site-aggregate template carrying this reporter, an asset/
  sensor_name_pattern config and the recommended rolling window would fit Prepared report templates #2300's shape directly,
  and is left to that PR.

sensor_units matches on dimension rather than on the exact spelling, which is what makes it useful
next to the unit conversion; a caller wanting an exact-spelling filter would need a further option.

Related items

Closes #2520.

---

Sign-off

• I agree to contribute to the project under Apache 2 License.
• To the best of my knowledge, the proposed patch is not based on code under GPL or another incompatible license.

🤖 Generated with Claude Code

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #34512428 | 📁 Comparing 0ec32bd against latest (819b836)

  🔍 Preview build  

6 files changed · ± 6 modified

± Modified

• changelog.html
• genindex.html
• _autosummary/flexmeasures.data.models.reporting.aggregator.html
• _autosummary/flexmeasures.data.schemas.reporting.aggregation.html
• api/v3_0.html
• features/reporting.html