Add Reporter classes to handle common reports

[victorgarcia98]

Recently, the introduction of the Reporter and PandasReporter classes in PR #641 opens the door to define report generation logic, in a standardized fashion. Even though both classes come with a great flexibility, they require a long list of arguments that might be similar (if not the same) across different use-cases.

For that reason, It would be nice to create a series of simple report generation classes that cover most of the practical applications and that require as little input arguments as possible. Some ideas for simple handy reporters:

• SimplePandasReporter: drops levels other than event_value
• AggregateReporter: Aggregate (min, max, mean, sum, ...) the data of all the sensors that are input.
• EnergyBillReporter: Computes the price of energy of a given sensor using the energy tariff, tolls, taxes, levies, etc...

With all this, I'd like to invite you to discuss which reporter classes we should prioritize and what functionality they should include.

[nhoening]

I think this is exactly the right course of action.

• Maybe this can be converted into a discussion? (there is a button on the right for that). It might lead to several issues.
• Instead of SimplePandasReporter we could say ValueReporter? Why bring up pandas in this abstraction?
• How about a CO2Reporter which reports overall CO2 and CO2/kWh?

[Flix6x]

I believe the original rationale behind the terms Reporter and PandasReporter was that the latter supports transformations defined as callable methods of a Pandas DataFrame. In reality, both classes are created around the concept of BeliefsDataFrames as input and output. Before delving into more custom reporter implementations (like AggregateReporter), I'd like to reflect on our main reporter classes, and suggest some alternatives for structuring/naming them:

1) Reporter -> PandasReporter -> SimplePandasReporter

Status quo + suggestion for a basic reporter that doesn't bother with sources, belief times and probabilities. This new SimplePandasReporter (1) only works with transformations defined as Pandas DataFrame methods. Option 1) is more based on how things happened to develop, and I feel with some hindsight we can do better.

2) Reporter -> TimelyBeliefsReporter -> PandasReporter

That is, rename the old PandasReporter (1) to the new TimelyBeliefsReporter (2), reflecting the fact that we can also already define transformations using custom methods of the BeliefsDataFrame (like resample_events). The new PandasReporter (2) does the same as what the SimplePandasReporter (1) would do.

3) Reporter -> PandasReporter

Looks like what we had initially, but bear with me. We rename the old PandasReporter (1) to Reporter (3), so that our basic reporter has transformation functionality by default. The new PandasReporter (3) does the same as what the SimplePandasReporter (1) would do.

[victorgarcia98]

Thanks for the ideas!

I like option (2) because it conveys the idea that Pandas DataFrame is a subset of a BeliefsDataFrame. Moreover, we keep the base Reporter class, which I think it's essential, however, needs some simplifications.

The reasons to keep the Reporter class, subject to some modifications, are:

• To have an abstract class that defines the interface for other code that uses reporters.
• Perform data validation with Marshmallow which is handy later to validate inputs from API calls or the CLI.
• (Optional) fetch data. I think we should move this into the current PandasReporter.

[Flix6x]

(Optional) fetch data. I think we should move this into the current PandasReporter.

So then in option 2:

• The Reporter class would have no functionality for fetching data, i.e. an empty fetch_data method. (Thinking out loud here: A question that comes to mind is why that would be better than assuming any subclassed reporter would want to rely on fetching time series data from our sensors? Maybe because someone would want to write their own queries from scratch. Okay, I'll subscribe to that.)
• The fetch_data method of the TimelyBeliefsReporter should return a BeliefsDataFrame. As we do now.
• The fetch_data method of the PandasReporter should return a pd.DataFrame (and without the multi-index).

[nhoening]

Where would these reporter classes live and how can I reference them in the CLI command?

[victorgarcia98]

Good question.

As long as they live in the folder flexmeasures.models.reporting, they'll be (auto)discovered and, therefore, available to the CLI.

Regarding on how to pass inputs, each Reporter can (should) define its own reporter_config Schema (which must inherit from ReporterConfigSchema). ReporterConfigSchema only requires the field tb_query_config, used to fetch the data of the sensors.

With this, a user should create a reporter_config with the inputs for the simple reporters. e.g:

{
    "tb_query_config" : [
       {"sensor" : 1},
       {"sensor" : 2}  
   ],
}

Just with this, the Reporter should have just enough, for instance, to aggregate the data from all the sensors.

[Flix6x]

Follow-up idea: what if sensor and tb_query_config move to the compute function? They are only used there anyway. Then the PandasReporter just defines a set of transformation rules, and a single reporter can be used by many output sensors (each defining their own set of input sensors, in the tb_query_config). It could be a key step towards making the reporter_config a database table of its own.

[victorgarcia98]

Ambiguous phrasing: do you mean, if both config and kwargs are passed, the kwargs will be used?

Yes, sorry. In case both config and kwargs are passed, we should default to kwargs.

No. Only when the input sensors, input sources or reporter_config changes. Or the aliases.

I'm not sure about this. I think we should create a new DataSource only when the reporter_config changes. That way, two reports are generated with the same Reporter class + reporter_config combination should share the same source. For instance, in the case of the ComputeErrorReporter, we would have one source for every type of error (e.g MSE, MAPE, ...).

[Flix6x]

For instance, in the case of the ComputeErrorReporter, we would have one source for every type of error

But then no information is stored regarding which input sensors & sources were used as a basis for determining the error. Although I don't expect the input sensors & sources for a ComputeErrorReporter to change, one use case that does worry me is aggregation.

Let's say that we compute aggregate power flow over a number of power sensors, and after a while, a new asset is installed and the aggregate power flow needs to account for an additional power sensor. Or alternatively, we switch from using power data provided by one party to power data provided by another party (for example, using data from a power clamp instead of API data, because it might be available faster). Such changes in input sensors & sources reflect changes in the report's origins.

[victorgarcia98]

Makes sense.

We have different ways to achieve that:

1. Define which parameters of the report_config generate a new DataSource.
   1.1. In the database, parallel to the reporter_config in the DataSource attributes.
   1.2. As a class attribute. This is important to avoid creating a new DataSource every time we update the start or end times.
2. Move those parameters to the reporter_config. Moreover, we can make them optional in both places and require one of them to be defined and by default, use the report_config. This later feature, although useful, could cause confusion.

The logic of when to create a new DataSource should be handled in the class DataGeneratorMixin.

For the DataSource, apart from the attributes field, I would add:

• A backreference to the sensor table. This would be useful to fetch which sensors make use of a Reporter, Scheduler, ...
• The path to the (Reporter, Scheduler, ...) class into the attributes field.

[Flix6x]

Agreed. I like 1.2, unless we think of a reason why this parameter set would be different across data sources. Which class did you have in mind to put the attributes on?

[victorgarcia98]

On one hand, the logic of getting the right data source happens in the property data_source in the DataGeneratorMixin class. I would update this property with the new functionality. On the other hand, I think that each Reporter subclass (e.g PandasReporter) should provide a (static) method that, given two DataSource attributes, returns True if a new data source needs to be generated.