[ENH] add at least one usage example to docstrings of estimators

[fkiraly]

Each estimator should have an example in its docstring.

This example should cover basic usage, and possiblly advanced cases.

The recipe for adding examples is:

• add an example section in numpydoc stype
• use as template for a simple example: NaiveForecaster
• use as template for complex/multiple examples: ForecastingGridSearchCV (search in code base)
• if the estimator relies on a soft dependency, ensure to use doctest skip to avoid import if the dependency is not present. Use as template for an example with soft dependency: ARIMA

To pick this up, post an estimator here that you are working on, to avoid double work, and make a PR.

[KishManani]

Hi @fkiraly! Happy to help adding some/more examples in the doc strings of estimators. Do you have a list already of some of the likely most used estimators that could benefit with an example?

[fkiraly]

There are currently 90 (out of 237) objects in sktime without example, code to generate them:

from sktime.registry import all_estimators

ests = all_estimators()
[x[1] for x in ests if "Example" not in x[1].__doc__ ]

(to subset to types, use the scitype arg of all_estimators)

[fkiraly]

The most "important" ones that I see in the list are (subjectively chosen):

• ForecastingRandomizedSearchCV
• DontUpdate, UpdateEvery, UpdateRefitsEvery
• YToX
• TimeBinner
• Id
• TSFreshClassifier
• TimeSeriesForestRegressor
• DummyClassifier
• TruncationTransformer

[JonathanBechtel]

@fkiraly After PR #4272 gets accepted I'll work on one for TimeSeriesForestRegressor and ForecastingRandomizedSearchCV

[Verogli]

I am adding examples to docstrings for DBScan.

[fkiraly]

FYI @Verogli, there's an example for DBScan in the EuroPython tutorial - this notebook: https://github.com/sktime/sktime-tutorial-europython-2023/blob/main/notebooks/05_panel_tasks.ipynb

although the result isn't "nice" in the sense of the clulster split being very clear.

[Verogli]

Thank you. I will look into that.

[meraldoantonio]

Hi! It's my first time contributing. I plan to add an example for CNNRegressor following the example from KNeighborsTimeSeriesRegressor. I imagine I'll need to include doctest skip for this?

[fkiraly]

Nice! Yes, the doctest should be skipped due to the soft dependency (alternatively, you can make the execution condtional on the soft dependency being present, that's a newer feature in doctest).

[YashKhare20]

Hi all! It's my first time contributing. I've added an example for DummyClassifier following the example from DummyRegressor. I've included doctest skip due to the soft dependency, hope that is fine.

[fkiraly]

Great addition, thanks, @YashKhare20!

Minor note, I think DummyRegressor does not have a soft dependency? So the doctest skips wouldn't be necessary.

[SamruddhiNavale]

Hello Team! I've added an example for WhiteNoiseAugmenter. Please let me know your review/feedback.
Thank You!