-
Notifications
You must be signed in to change notification settings - Fork 466
/
forecaster.py
3136 lines (2827 loc) · 134 KB
/
forecaster.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
import logging
import os
import time
from collections import OrderedDict
from typing import Callable, List, Optional, Tuple, Type, Union
import matplotlib
import numpy as np
import pandas as pd
import pytorch_lightning as pl
import torch
from matplotlib import pyplot
from matplotlib.axes import Axes
from pytorch_lightning.tuner.tuning import Tuner
from torch.utils.data import DataLoader
from neuralprophet import configure, df_utils, np_types, time_dataset, time_net, utils, utils_metrics
from neuralprophet.data.process import (
_check_dataframe,
_convert_raw_predictions_to_raw_df,
_create_dataset,
_handle_missing_data,
_prepare_dataframe_to_predict,
_reshape_raw_predictions_to_forecst_df,
_validate_column_name,
)
from neuralprophet.data.split import _make_future_dataframe, _maybe_extend_df
from neuralprophet.data.transform import _normalize
from neuralprophet.logger import MetricsLogger
from neuralprophet.plot_forecast_matplotlib import plot, plot_components
from neuralprophet.plot_forecast_plotly import conformal_plot_plotly
from neuralprophet.plot_forecast_plotly import plot as plot_plotly
from neuralprophet.plot_forecast_plotly import plot_components as plot_components_plotly
from neuralprophet.plot_model_parameters_matplotlib import plot_parameters
from neuralprophet.plot_model_parameters_plotly import plot_parameters as plot_parameters_plotly
from neuralprophet.plot_utils import get_valid_configuration, log_warning_deprecation_plotly, select_plotting_backend
from neuralprophet.uncertainty import Conformal
log = logging.getLogger("NP.forecaster")
class NeuralProphet:
"""NeuralProphet forecaster.
A simple yet powerful forecaster that models:
Trend, seasonality, events, holidays, auto-regression, lagged covariates, and future-known regressors.
Can be regularized and configured to model nonlinear relationships.
Parameters
----------
COMMENT
Trend Config
COMMENT
growth : {'off' or 'linear'}, default 'linear'
Set use of trend growth type.
Options:
* ``off``: no trend.
* (default) ``linear``: fits a piece-wise linear trend with ``n_changepoints + 1`` segments
* ``discontinuous``: For advanced users only - not a conventional trend,
allows arbitrary jumps at each trend changepoint
changepoints : {list of str, list of np.datetimes or np.array of np.datetimes}, optional
Manually set dates at which to include potential changepoints.
Note
----
Does not accept ``np.array`` of ``np.str``. If not specified, potential changepoints are selected
automatically.
n_changepoints : int
Number of potential trend changepoints to include.
Note
----
Changepoints are selected uniformly from the first ``changepoint_range`` proportion of the history.
Ignored if manual ``changepoints`` list is supplied.
changepoints_range : float
Proportion of history in which trend changepoints will be estimated.
e.g. set to 0.8 to allow changepoints only in the first 80% of training data.
Ignored if manual ``changepoints`` list is supplied.
trend_reg : float, optional
Parameter modulating the flexibility of the automatic changepoint selection.
Note
----
Large values (~1-100) will limit the variability of changepoints.
Small values (~0.001-1.0) will allow changepoints to change faster.
default: 0 will fully fit a trend to each segment.
trend_reg_threshold : bool, optional
Allowance for trend to change without regularization.
Options
* ``True``: Automatically set to a value that leads to a smooth trend.
* (default) ``False``: All changes in changepoints are regularized
trend_global_local : str, default 'global'
Modelling strategy of the trend when multiple time series are present.
Options:
* ``global``: All the elements are modelled with the same trend.
* ``local``: Each element is modelled with a different trend.
Note
----
When only one time series is input, this parameter should not be provided.
Internally it will be set to ``global``, meaning that all the elements(only one in this case)
are modelled with the same trend.
trend_local_reg : Optional[Union[bool, float]] = False,
Parameter to regularize weights to induce similarity between global and local trend
Note
----
Large values (~100) will limit the variability of changepoints.
Small values (~0.001) will allow changepoints to change faster.
COMMENT
Seasonality Config
COMMENT
yearly_seasonality : bool, int
Fit yearly seasonality.
Options
* ``True`` or ``False``
* ``auto``: set automatically
* ``value``: number of Fourier/linear terms to generate
yearly_seasonality_glocal_mode : bool, str
Whether to train the yearly seasonality. Only effective on multiple time series
Options
* ``global``
* ``local``
* ``glocal``
weekly_seasonality : bool, int
Fit monthly seasonality.
Options
* ``True`` or ``False``
* ``auto``: set automatically
* ``value``: number of Fourier/linear terms to generate
weekly_seasonality_glocal_mode : bool, str
Whether to train the weekly seasonality. Only effective on multiple time series
Options
* ``global``
* ``local``
* ``glocal``
daily_seasonality : bool, int
Fit daily seasonality.
Options
* ``True`` or ``False``
* ``auto``: set automatically
* ``value``: number of Fourier/linear terms to generate
daily_seasonality_glocal_mode : bool, str
Whether to train the daily seasonality. Only effective on multiple time series
Options
* ``global``
* ``local``
* ``glocal``
seasonality_mode : str
Specifies mode of seasonality
Options
* (default) ``additive``
* ``multiplicative``
seasonality_reg : float, optional
Parameter modulating the strength of the seasonality model.
Note
----
Smaller values (~0.1-1) allow the model to fit larger seasonal fluctuations,
larger values (~1-100) dampen the seasonality.
default: None, no regularization
season_global_local : str, default 'global'
Modelling strategy of the general/default seasonality when multiple time series are present.
Options:
* ``global``: All the elements are modelled with the same seasonality.
* ``local``: Each element is modelled with a different seasonality.
Note
----
When only one time series is input, this parameter should not be provided.
Internally it will be set to ``global``, meaning that all the elements(only one in this case)
are modelled with the same seasonality.
seasonality_local_reg : Optional[Union[bool, float]] = False,
Parameter to regularize weights to induce similarity between global and local seasonality
Note
----
Large values (~100) will limit the variability of changepoints.
Small values (~0.001) will allow changepoints to change faster.
COMMENT
Future Regressors
COMMENT
future_regressors_model: str
Options
* (default) ``linear``
* ``neural_nets``
* ``shared_neural_nets``
* ``shared_neural_nets_coef``
future_regressors_d_hidden: int
Number of hidden layers in the neural network model for future regressors.
Ignored if ``future_regressors_model`` is ``linear``.
future_regressors_num_hidden_layers: int
Dimension of hidden layers in the neural network model for future regressors.
Ignored if ``future_regressors_model`` is ``linear``.
COMMENT
AR Config
COMMENT
n_lags : int
Previous time series steps to include in auto-regression. Aka AR-order
ar_reg : float, optional
how much sparsity to induce in the AR-coefficients
Note
----
Large values (~1-100) will limit the number of nonzero coefficients dramatically.
Small values (~0.001-1.0) will allow more non-zero coefficients.
default: 0 no regularization of coefficients.
ar_layers : list of int, optional
array of hidden layer dimensions of the AR-Net. Specifies number of hidden layers (number of entries)
and layer dimension (list entry).
COMMENT
Model Config
COMMENT
n_forecasts : int
Number of steps ahead of prediction time step to forecast.
lagged_reg_layers : list of int, optional
array of hidden layer dimensions of the Covar-Net. Specifies number of hidden layers (number of entries)
and layer dimension (list entry).
COMMENT
Train Config
COMMENT
learning_rate : float
Maximum learning rate setting for 1cycle policy scheduler.
Note
----
Default ``None``: Automatically sets the ``learning_rate`` based on a learning rate range test.
For manual user input, (try values ~0.001-10).
epochs : int
Number of epochs (complete iterations over dataset) to train model.
Note
----
Default ``None``: Automatically sets the number of epochs based on dataset size.
For best results also leave batch_size to None. For manual values, try ~5-500.
batch_size : int
Number of samples per mini-batch.
If not provided, ``batch_size`` is approximated based on dataset size.
For manual values, try ~8-1024.
For best results also leave ``epochs`` to ``None``.
newer_samples_weight: float, default 2.0
Sets factor by which the model fit is skewed towards more recent observations.
Controls the factor by which final samples are weighted more compared to initial samples.
Applies a positional weighting to each sample's loss value.
e.g. ``newer_samples_weight = 2``: final samples are weighted twice as much as initial samples.
newer_samples_start: float, default 0.0
Sets beginning of 'newer' samples as fraction of training data.
Throughout the range of 'newer' samples, the weight is increased
from ``1.0/newer_samples_weight`` initially to 1.0 at the end,
in a monotonously increasing function (cosine from pi to 2*pi).
loss_func : str, torch.nn.functional.loss
Type of loss to use:
Options
* (default) ``SmoothL1Loss``: SmoothL1 loss function
* ``MSE``: Mean Squared Error loss function
* ``MAE``: Mean Absolute Error loss function
* ``torch.nn.functional.loss.``: loss or callable for custom loss, eg. L1-Loss
Examples
--------
>>> from neuralprophet import NeuralProphet
>>> import torch
>>> import torch.nn as nn
>>> m = NeuralProphet(loss_func=torch.nn.L1Loss)
collect_metrics : list of str, dict, bool
Set metrics to compute.
Options
* (default) ``True``: [``mae``, ``rmse``]
* ``False``: No metrics
* ``list``: Valid options: [``mae``, ``rmse``, ``mse``]
* ``dict``: Collection of names of torchmetrics.Metric objects
Examples
--------
>>> from neuralprophet import NeuralProphet
>>> # computer MSE, MAE and RMSE
>>> m = NeuralProphet(collect_metrics=["MSE", "MAE", "RMSE"])
>>> # use custorm torchmetrics names
>>> m = NeuralProphet(collect_metrics={"MAPE": "MeanAbsolutePercentageError", "MSLE": "MeanSquaredLogError",
COMMENT
Uncertainty Estimation
COMMENT
quantiles : list, default None
A list of float values between (0, 1) which indicate the set of quantiles to be estimated.
COMMENT
Missing Data
COMMENT
impute_missing : bool
whether to automatically impute missing dates/values
Note
----
imputation follows a linear method up to 20 missing values, more are filled with trend.
impute_linear : int
maximal number of missing dates/values to be imputed linearly (default: ``10``)
impute_rolling : int
maximal number of missing dates/values to be imputed
using rolling average (default: ``10``)
drop_missing : bool
whether to automatically drop missing samples from the data
Options
* (default) ``False``: Samples containing NaN values are not dropped.
* ``True``: Any sample containing at least one NaN value will be dropped.
COMMENT
Data Normalization
COMMENT
normalize : str
Type of normalization to apply to the time series.
Options
* ``off`` bypasses data normalization
* (default, binary timeseries) ``minmax`` scales the minimum value to 0.0 and the maximum value to 1.0
* ``standardize`` zero-centers and divides by the standard deviation
* (default) ``soft`` scales the minimum value to 0.0 and the 95th quantile to 1.0
* ``soft1`` scales the minimum value to 0.1 and the 90th quantile to 0.9
global_normalization : bool
Activation of global normalization
Options
* ``True``: dict of dataframes is used as global_time_normalization
* (default) ``False``: local normalization
global_time_normalization : bool
Specifies global time normalization
Options
* (default) ``True``: only valid in case of global modeling local normalization
* ``False``: set time data_params locally
unknown_data_normalization : bool
Specifies unknown data normalization
Options
* ``True``: test data is normalized with global data params even if trained with local data params
(global modeling with local normalization)
* (default) ``False``: no global modeling with local normalization
accelerator: str
Name of accelerator from pytorch_lightning.accelerators to use for training. Use "auto" to automatically
select an available accelerator.
Provide `None` to deactivate the use of accelerators.
trainer_config: dict
Dictionary of additional trainer configuration parameters.
prediction_frequency: dict
Set a periodic interval in which forecasts should be made.
By default, a model creates predictions for all possible prediction origins in dataset.
(e.g. for a hourly dataset, at each hour, each day, for all days in dataset)
Setting `prediction_frequency` allows to make forecasts only at a specific, periodically repeating point in time (prediction origin).
(e.g. {"daily-hour": 12} sets the model to predict only at noon, and no other hour)
Currently, only one item in dict is supported, except for the specific combination of
{"daily-hour": x, "weekly-day": y"} to predict at a specific hour of a specific day of week.
Key: str
periodicity of the predictions to be made.
value: int
forecast origin of the predictions to be made, e.g. 7 for 7am in case of 'daily-hour'.
Options
* ``'hourly-minute'``: forecast once per hour at a specified minute in range [0, 59]
* ``'daily-hour'``: forecast once per day at a specified hour in range [0, 23]
* ``'weekly-day'``: forecast once per week at a specified day in range [0, 6]
* ``'monthly-day'``: forecast once per month at a specified day in range [1, 31]
* ``'yearly-month'``: forecast once per year at a specified month in range [1, 12]
Note
----
This filter is applied to both model training and prediction.
Note
----
The forecast/prediction origin set refers to the last observation's timestamp, not the first forecast target.
In the special case where no auto-regression or lagged regressors are used, the forecast origin and forecast target are identical.
"""
model: time_net.TimeNet
trainer: pl.Trainer
def __init__(
self,
growth: np_types.GrowthMode = "linear",
changepoints: Optional[list] = None,
n_changepoints: int = 10,
changepoints_range: float = 0.8,
trend_reg: float = 0,
trend_reg_threshold: Optional[Union[bool, float]] = False,
trend_global_local: str = "global",
trend_local_reg: Optional[Union[bool, float]] = False,
yearly_seasonality: np_types.SeasonalityArgument = "auto",
yearly_seasonality_glocal_mode: np_types.SeasonalityArgument = "auto",
weekly_seasonality: np_types.SeasonalityArgument = "auto",
weekly_seasonality_glocal_mode: np_types.SeasonalityArgument = "auto",
daily_seasonality: np_types.SeasonalityArgument = "auto",
daily_seasonality_glocal_mode: np_types.SeasonalityArgument = "auto",
seasonality_mode: np_types.SeasonalityMode = "additive",
seasonality_reg: float = 0,
season_global_local: np_types.SeasonGlobalLocalMode = "global",
seasonality_local_reg: Optional[Union[bool, float]] = False,
future_regressors_model: np_types.FutureRegressorsModel = "linear",
future_regressors_d_hidden: int = 4,
future_regressors_num_hidden_layers: int = 2,
n_forecasts: int = 1,
n_lags: int = 0,
ar_layers: Optional[list] = [],
ar_reg: Optional[float] = None,
lagged_reg_layers: Optional[list] = [],
learning_rate: Optional[float] = None,
epochs: Optional[int] = None,
batch_size: Optional[int] = None,
loss_func: Union[str, torch.nn.modules.loss._Loss, Callable] = "SmoothL1Loss",
optimizer: Union[str, Type[torch.optim.Optimizer]] = "AdamW",
newer_samples_weight: float = 2,
newer_samples_start: float = 0.0,
quantiles: List[float] = [],
impute_missing: bool = True,
impute_linear: int = 10,
impute_rolling: int = 10,
drop_missing: bool = False,
collect_metrics: Union[bool, list, dict] = True,
normalize: np_types.NormalizeMode = "auto",
global_normalization: bool = False,
global_time_normalization: bool = True,
unknown_data_normalization: bool = False,
accelerator: Optional[str] = None,
trainer_config: dict = {},
prediction_frequency: Optional[dict] = None,
):
self.config = locals()
self.config.pop("self")
# General
self.name = "NeuralProphet"
self.n_forecasts = n_forecasts
self.prediction_frequency = prediction_frequency
# Data Normalization settings
self.config_normalization = configure.Normalization(
normalize=normalize,
global_normalization=global_normalization,
global_time_normalization=global_time_normalization,
unknown_data_normalization=unknown_data_normalization,
)
# Missing Data Preprocessing
self.config_missing = configure.MissingDataHandling(
impute_missing=impute_missing,
impute_linear=impute_linear,
impute_rolling=impute_rolling,
drop_missing=drop_missing,
)
if isinstance(collect_metrics, list):
log.info(
DeprecationWarning(
"Providing metrics to collect via `collect_metrics` in NeuralProphet is deprecated and will be "
+ "removed in a future version. The metrics are now configure in the `fit()` method via `metrics`."
)
)
self.metrics = utils_metrics.get_metrics(collect_metrics)
# AR
self.config_ar = configure.AR(n_lags=n_lags, ar_reg=ar_reg, ar_layers=ar_layers)
self.n_lags = self.config_ar.n_lags
self.max_lags = self.n_lags
# Model
self.config_model = configure.Model(lagged_reg_layers=lagged_reg_layers)
# Trend
self.config_trend = configure.Trend(
growth=growth,
changepoints=changepoints,
n_changepoints=n_changepoints,
changepoints_range=changepoints_range,
trend_reg=trend_reg,
trend_reg_threshold=trend_reg_threshold,
trend_global_local=trend_global_local,
trend_local_reg=trend_local_reg,
)
# Training
self.config_train = configure.Train(
quantiles=quantiles,
learning_rate=learning_rate,
epochs=epochs,
batch_size=batch_size,
loss_func=loss_func,
optimizer=optimizer,
newer_samples_weight=newer_samples_weight,
newer_samples_start=newer_samples_start,
trend_reg_threshold=self.config_trend.trend_reg_threshold,
)
# Seasonality
self.config_seasonality = configure.ConfigSeasonality(
mode=seasonality_mode,
reg_lambda=seasonality_reg,
yearly_arg=yearly_seasonality,
weekly_arg=weekly_seasonality,
daily_arg=daily_seasonality,
global_local=season_global_local,
seasonality_local_reg=seasonality_local_reg,
yearly_global_local=yearly_seasonality_glocal_mode,
weekly_global_local=weekly_seasonality_glocal_mode,
daily_global_local=daily_seasonality_glocal_mode,
condition_name=None,
)
# Events
self.config_events: Optional[configure.ConfigEvents] = None
self.config_country_holidays: Optional[configure.ConfigCountryHolidays] = None
# Extra Regressors
self.config_lagged_regressors: Optional[configure.ConfigLaggedRegressors] = None
self.config_regressors = configure.ConfigFutureRegressors(
model=future_regressors_model,
d_hidden=future_regressors_d_hidden,
num_hidden_layers=future_regressors_num_hidden_layers,
) # Optional[configure.ConfigFutureRegressors] = None
# set during fit()
self.data_freq = None
# Set during _train()
self.fitted = False
self.data_params = None
# Pytorch Lightning Trainer
self.metrics_logger = MetricsLogger(save_dir=os.getcwd())
self.accelerator = accelerator
self.trainer_config = trainer_config
# set during prediction
self.future_periods = None
self.predict_steps = self.n_forecasts
# later set by user (optional)
self.highlight_forecast_step_n = None
self.true_ar_weights = None
def add_lagged_regressor(
self,
names: Union[str, List[str]],
n_lags: Union[int, np_types.Literal["auto", "scalar"]] = "auto",
regularization: Optional[float] = None,
normalize: Union[bool, str] = "auto",
):
"""Add a covariate or list of covariate time series as additional lagged regressors to be used for fitting and
predicting.
The dataframe passed to ``fit`` and ``predict`` will have the column with the specified name to be used as
lagged regressor. When normalize=True, the covariate will be normalized unless it is binary.
Parameters
----------
names : string or list
name of the regressor/list of regressors.
n_lags : int
previous regressors time steps to use as input in the predictor (covar order)
if ``auto``, time steps will be equivalent to the AR order (default)
if ``scalar``, all the regressors will only use last known value as input
regularization : float
optional scale for regularization strength
normalize : bool
optional, specify whether this regressor will benormalized prior to fitting.
if ``auto``, binary regressors will not be normalized.
"""
lagged_reg_layers = self.config_model.lagged_reg_layers
if n_lags == 0 or n_lags is None:
raise ValueError(
f"Received n_lags {n_lags} for lagged regressor {names}. Please set n_lags > 0 or use options 'scalar' or 'auto'."
)
if n_lags == "auto":
if self.n_lags is not None and self.n_lags > 0:
n_lags = self.n_lags
log.info(
"n_lags = 'auto', number of lags for regressor is set to Autoregression number of lags "
+ f"({self.n_lags})"
)
else:
n_lags = 1
log.info(
"n_lags = 'auto', but there is no lags for Autoregression. Number of lags for regressor is "
+ "automatically set to 1"
)
if n_lags == "scalar":
n_lags = 1
log.info("n_lags = 'scalar', number of lags for regressor is set to 1")
only_last_value = False if n_lags > 1 else True
if self.fitted:
raise Exception("Regressors must be added prior to model fitting.")
if not isinstance(names, list):
names = [names]
for name in names:
_validate_column_name(
name=name,
config_events=self.config_events,
config_country_holidays=self.config_country_holidays,
config_seasonality=self.config_seasonality,
config_lagged_regressors=self.config_lagged_regressors,
config_regressors=self.config_regressors,
)
if self.config_lagged_regressors is None:
self.config_lagged_regressors = OrderedDict()
self.config_lagged_regressors[name] = configure.LaggedRegressor(
reg_lambda=regularization,
normalize=normalize,
as_scalar=only_last_value,
n_lags=n_lags,
lagged_reg_layers=lagged_reg_layers,
)
return self
def parameters(self):
return self.config
def state_dict(self):
return {
"data_freq": self.data_freq,
"fitted": self.fitted,
"data_params": self.data_params,
"optimizer": self.config_train.optimizer,
"scheduler": self.config_train.scheduler,
"model": self.model,
"future_periods": self.future_periods,
"predict_steps": self.predict_steps,
"highlight_forecast_step_n": self.highlight_forecast_step_n,
"true_ar_weights": self.true_ar_weights,
}
def add_future_regressor(
self,
name: str,
regularization: Optional[float] = None,
normalize: Union[str, bool] = "auto",
mode: str = "additive",
):
"""Add a regressor as lagged covariate with order 1 (scalar) or as known in advance (also scalar).
The dataframe passed to :meth:`fit` and :meth:`predict` will have a column with the specified name to be used
as a regressor. When normalize=True, the regressor will be normalized unless it is binary.
Note
----
Future Regressors have to be known for the entire forecast horizon, e.g. ``n_forecasts`` into the future.
Parameters
----------
name : string
name of the regressor.
regularization : float
optional scale for regularization strength
normalize : bool
optional, specify whether this regressor will be normalized prior to fitting.
Note
----
if ``auto``, binary regressors will not be normalized.
mode : str
``additive`` (default) or ``multiplicative``.
"""
if self.fitted:
raise Exception("Regressors must be added prior to model fitting.")
if regularization is not None:
if regularization < 0:
raise ValueError("regularization must be >= 0")
if regularization == 0:
regularization = None
_validate_column_name(
name=name,
config_events=self.config_events,
config_country_holidays=self.config_country_holidays,
config_seasonality=self.config_seasonality,
config_lagged_regressors=self.config_lagged_regressors,
config_regressors=self.config_regressors,
)
if self.config_regressors.regressors is None:
self.config_regressors.regressors = OrderedDict()
self.config_regressors.regressors[name] = configure.Regressor(
reg_lambda=regularization, normalize=normalize, mode=mode
)
return self
def add_events(
self,
events: Union[str, List[str]],
lower_window: int = 0,
upper_window: int = 0,
regularization: Optional[float] = None,
mode: str = "additive",
):
"""
Add user specified events and their corresponding lower, upper windows and the
regularization parameters into the NeuralProphet object
Parameters
----------
events : str, list
name or list of names of user specified events
lower_window : int
the lower window for the events in the list of events
upper_window : int
the upper window for the events in the list of events
regularization : float
optional scale for regularization strength
mode : str
``additive`` (default) or ``multiplicative``.
"""
if self.fitted:
raise Exception("Events must be added prior to model fitting.")
if self.config_events is None:
self.config_events = OrderedDict({})
if regularization is not None:
if regularization < 0:
raise ValueError("regularization must be >= 0")
if regularization == 0:
regularization = None
if not isinstance(events, list):
events = [events]
for event_name in events:
_validate_column_name(
name=event_name,
config_events=self.config_events,
config_country_holidays=self.config_country_holidays,
config_seasonality=self.config_seasonality,
config_lagged_regressors=self.config_lagged_regressors,
config_regressors=self.config_regressors,
)
self.config_events[event_name] = configure.Event(
lower_window=lower_window, upper_window=upper_window, reg_lambda=regularization, mode=mode
)
return self
def add_country_holidays(
self,
country_name: Union[str, list, dict],
lower_window: int = 0,
upper_window: int = 0,
regularization: Optional[float] = None,
mode: str = "additive",
):
"""
Add a country into the NeuralProphet object to include country specific holidays
and create the corresponding configs such as lower, upper windows and the regularization
parameters
Holidays can only be added for a single country or country list. Calling the function
multiple times will override already added country holidays.
Parameters
----------
country_name : str, list, dict
name or list of names of the country or a dictionary where the key is the country name and the value is a subdivision
lower_window : int
the lower window for all the country holidays
upper_window : int
the upper window for all the country holidays
regularization : float
optional scale for regularization strength
mode : str
``additive`` (default) or ``multiplicative``.
"""
if self.fitted:
raise AssertionError("Country must be specified prior to model fitting.")
if self.config_country_holidays:
raise AssertionError(
"Country holidays can only be added once. Previous country holidays will be overridden."
"If adding multiple countries, please add as list. "
)
if regularization is not None:
if regularization < 0:
raise ValueError("regularization must be >= 0")
if regularization == 0:
regularization = None
self.config_country_holidays = configure.Holidays(
country=country_name,
lower_window=lower_window,
upper_window=upper_window,
reg_lambda=regularization,
mode=mode,
)
self.config_country_holidays.init_holidays()
return self
def add_seasonality(
self,
name: str,
period: float,
fourier_order: int,
global_local: str = "auto",
condition_name: Optional[str] = None,
):
"""Add a seasonal component with specified period, number of Fourier components, and regularization.
Increasing the number of Fourier components allows the seasonality to change more quickly
(at risk of overfitting).
Note: regularization and mode (additive/multiplicative) are set in the main init.
If condition_name is provided, the dataframe passed to `fit` and
`predict` should have a column with the specified condition_name
containing only zeros and ones, deciding when to apply seasonality.
Floats between 0 and 1 can be used to apply seasonality partially.
Parameters
----------
name : string
name of the seasonality component.
period : float
number of days in one period.
fourier_order : int
number of Fourier components to use.
global_local : str
glocal modelling mode.
condition_name : string
string name of the seasonality condition.
Examples
--------
Adding a quarterly changing weekly seasonality to the model. First, add columns to df.
The columns should contain only zeros and ones (or floats), deciding when to apply seasonality.
>>> df["summer"] = df["ds"].apply(lambda x: x.month in [6, 7, 8])
>>> df["fall"] = df["ds"].apply(lambda x: x.month in [9, 10, 11])
>>> df["winter"] = df["ds"].apply(lambda x: x.month in [12, 1, 2])
>>> df["spring"] = df["ds"].apply(lambda x: x.month in [3, 4, 5])
>>> df.head()
ds y summer_week fall_week winter_week spring_week
0 2022-12-01 9.59 0 0 1 0
1 2022-12-02 8.52 0 0 1 0
2 2022-12-03 8.18 0 0 1 0
3 2022-12-04 8.07 0 0 1 0
As a next step, add the seasonality to the model. With period=7, we specify that the seasonality changes weekly.
>>> m = NeuralProphet(weekly_seasonality=False)
>>> m.add_seasonality(name="weekly_summer", period=7, fourier_order=4, condition_name="summer")
>>> m.add_seasonality(name="weekly_winter", period=7, fourier_order=4, condition_name="winter")
>>> m.add_seasonality(name="weekly_spring", period=7, fourier_order=4, condition_name="spring")
>>> m.add_seasonality(name="weekly_fall", period=7, fourier_order=4, condition_name="fall")
"""
if self.fitted:
raise Exception("Seasonality must be added prior to model fitting.")
if name in ["daily", "weekly", "yearly"]:
log.error("Please use inbuilt daily, weekly, or yearly seasonality or set another name.")
# Do not Allow overwriting built-in seasonalities
_validate_column_name(
name=name,
config_events=self.config_events,
config_country_holidays=self.config_country_holidays,
config_seasonality=self.config_seasonality,
config_lagged_regressors=self.config_lagged_regressors,
config_regressors=self.config_regressors,
seasons=True,
)
if condition_name is not None:
_validate_column_name(
name=condition_name,
config_events=self.config_events,
config_country_holidays=self.config_country_holidays,
config_seasonality=self.config_seasonality,
config_lagged_regressors=self.config_lagged_regressors,
config_regressors=self.config_regressors,
)
if fourier_order <= 0:
raise ValueError("Fourier Order must be > 0")
self.config_seasonality.append(
name=name,
period=period,
resolution=fourier_order,
arg="custom",
global_local=global_local,
condition_name=condition_name,
)
return self
def fit(
self,
df: pd.DataFrame,
freq: str = "auto",
validation_df: Optional[pd.DataFrame] = None,
epochs: Optional[int] = None,
batch_size: Optional[int] = None,
learning_rate: Optional[float] = None,
early_stopping: bool = False,
minimal: bool = False,
metrics: Optional[np_types.CollectMetricsMode] = None,
progress: Optional[str] = "bar",
checkpointing: bool = False,
continue_training: bool = False,
num_workers: int = 0,
deterministic: bool = False,
):
"""Train, and potentially evaluate model.
Training/validation metrics may be distorted in case of auto-regression,
if a large number of NaN values are present in df and/or validation_df.
Parameters
----------
df : pd.DataFrame
containing column ``ds``, ``y``, and optionally``ID`` with all data
freq : str
Data step sizes. Frequency of data recording,
Note
----
Any valid frequency for pd.date_range, such as ``5min``, ``D``, ``MS`` or ``auto`` (default) to
automatically set frequency.
validation_df : pd.DataFrame, dict
If provided, model with performance will be evaluated after each training epoch over this data.
epochs : int
Number of epochs to train for. If None, uses the number of epochs specified in the model config.
batch_size : int
Batch size for training. If None, uses the batch size specified in the model config.
learning_rate : float
Learning rate for training. If None, uses the learning rate specified in the model config.
early_stopping : bool
Flag whether to use early stopping to stop training when training / validation loss is no longer
improving.
minimal : bool
Minimal mode deactivates metrics, the progress bar and checkpointing. Control more granular by using the
`metrics`, `progress` and `checkpointing` parameters.
metrics : bool
Flag whether to collect metrics during training. If None, uses the metrics specified in the model
config.
progress : str
Flag whether to show a progress bar during training. If None, uses the progress specified in the model
config.
Options
* (default) ``bar``
* ``plot``
* `None`
checkpointing : bool
Flag whether to save checkpoints during training
continue_training : bool
Flag whether to continue training from the last checkpoint
num_workers : int
Number of workers for data loading. If 0, data will be loaded in the main process.
Note: using multiple workers and therefore distributed training might significantly increase
the training time since each batch needs to be copied to each worker for each epoch. Keeping
all data on the main process might be faster for most datasets.
Returns
-------
pd.DataFrame
metrics with training and potentially evaluation metrics
"""
if self.fitted:
raise RuntimeError("Model has been fitted already. Please initialize a new model to fit again.")
# Configuration
if epochs is not None:
self.config_train.epochs = epochs
if batch_size is not None:
self.config_train.batch_size = batch_size
if learning_rate is not None:
self.config_train.learning_rate = learning_rate
if early_stopping is not None:
self.early_stopping = early_stopping
if metrics is not None:
self.metrics = utils_metrics.get_metrics(metrics)
# Warnings