feat: allow plugins to register forecasters

[Flix6x]

Description

• Register Forecaster subclasses defined in plugins
• Add documentation in plugin section
• Added changelog item in documentation/changelog.rst

Look & Feel

In the hypothetical my-first-ems plugin, within my_first_ems.data.models.heating:

from marshmallow import Schema
from timely_beliefs import BeliefsDataFrame
from flexmeasures import Forecaster, Sensor

class COPForecaster(Forecaster):
    """
    Usage
    -----
    flexmeasures add forecasts \
      --sensor     260 \
      --regressors 9 \
      --forecaster COPForecaster \
      --start-date 2022-01-01T00:00:00+01:00 \
      --from-date  2022-03-01T00:00:00+01:00 \
      --to-date    2022-03-02T00:00:00+01:00

    """

    __version__ = "1"
    __author__ = "Felix"

    _config_schema = Schema(unknown="include")
    _parameters_schema = Schema(unknown="include")

    def _compute_forecast(self, **kwargs):
        cop_sensor = kwargs["sensor"]
        bdf = BeliefsDataFrame()
        return [
            {
                "sensor": cop_sensor,
                "data": bdf,
            },
        ]

After registering the my-first-ems plugin in flexmeasures.cfg:

$ flexmeasures show forecasters
name                    version  author    module
--------------------  ---------  --------  ------------------------------------------------------------
TrainPredictPipeline          1  Seita     flexmeasures.data.models.forecasting.pipelines.train_predict
COPForecaster                 1  Felix     my_first_ems.data.models.heating

and it would be picked up when selected using flexmeasures add forecasts --forecaster COPForecaster.

How to test

Copy-paste the above class into plugin code and run flexmeasures show forecasters to check that it shows up.

Further Improvements

• The schemas should currently be compatible with those of the TrainPredictPipeline. Here, we use ma.Schema(unknown="include") to accept any field. Both the API and CLI should validate fields using the schemas of the desired Forecaster subclass, rather than always using the schemas of the TrainPredictPipeline.
• Currently, the Forecaster subclass itself is responsible for saving the data and creating jobs. That should probably be handled by a data service instead, similar to how it's handled for Scheduler subclasses.

Related Items

• The idea of having the CLI options be generated from the schema: Unifying forecasting CLI and Schema field descriptions #1864

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #30930875 | 📁 Comparing 861fc6f against latest (d1897e5)

🔍 Preview build

Show files changed (12 files in total): 📝 12 modified | ➕ 0 added | ➖ 0 deleted

File	Status
changelog.html	📝 modified
genindex.html	📝 modified
_autosummary/flexmeasures.api.common.schemas.assets.html	📝 modified
_autosummary/flexmeasures.api.v3_0.assets.html	📝 modified
_autosummary/flexmeasures.data.schemas.sensors.html	📝 modified
_autosummary/flexmeasures.data.services.data_sources.html	📝 modified
_autosummary/flexmeasures.data.services.scheduling.html	📝 modified
_autosummary/flexmeasures.utils.unit_utils.html	📝 modified
api/change_log.html	📝 modified
api/v3_0.html	📝 modified
cli/change_log.html	📝 modified
plugin/customisation.html	📝 modified

[BelhsanHmida]

LGTM tested it out in a plugin and ran the forecasting cli command. the forecasting source was registered:

type: forecaster
==========
  ID  Name                         User ID    Model                                            Version
----  ---------------------------  ---------  -----------------------------------------------  ---------
 579  FlexMeasures                            COPForecaster

one small suggestion in example class.