prophet.serialize

  1# Copyright (c) Facebook, Inc. and its affiliates.
  2
  3# This source code is licensed under the MIT license found in the
  4# LICENSE file in the root directory of this source tree.
  5
  6from __future__ import annotations
  7
  8from collections import OrderedDict
  9from copy import deepcopy
 10from io import StringIO
 11import json
 12from typing import Any, Final
 13
 14import numpy as np
 15import pandas as pd
 16
 17from prophet.__version__ import __version__
 18from prophet.forecaster import Prophet
 19
 20SIMPLE_ATTRIBUTES: Final[list[str]] = [
 21    'growth', 'n_changepoints', 'specified_changepoints', 'changepoint_range',
 22    'yearly_seasonality', 'weekly_seasonality', 'daily_seasonality',
 23    'seasonality_mode', 'seasonality_prior_scale', 'changepoint_prior_scale',
 24    'holidays_prior_scale', 'mcmc_samples', 'interval_width', 'uncertainty_samples',
 25    'y_scale', 'y_min', 'scaling', 'logistic_floor', 'country_holidays', 'component_modes',
 26    'holidays_mode'
 27]
 28
 29PD_SERIES: Final[list[str]] = ["changepoints", "history_dates", "train_holiday_names"]
 30
 31PD_TIMESTAMP: Final[list[str]] = ["start"]
 32
 33PD_TIMEDELTA: Final[list[str]] = ["t_scale"]
 34
 35PD_DATAFRAME: Final[list[str]] = ["holidays", "history", "train_component_cols"]
 36
 37NP_ARRAY: Final[list[str]] = ["changepoints_t"]
 38
 39ORDEREDDICT: Final[list[str]] = ["seasonalities", "extra_regressors"]
 40
 41
 42def model_to_dict(model: Prophet) -> dict[str, Any]:
 43    """Convert a Prophet model to a dictionary suitable for JSON serialization.
 44
 45    Model must be fitted. Skips Stan objects that are not needed for predict.
 46
 47    Can be reversed with model_from_dict.
 48
 49    Parameters
 50    ----------
 51    model: Prophet model object.
 52
 53    Returns
 54    -------
 55    dict that can be used to serialize a Prophet model as JSON or loaded back
 56    into a Prophet model.
 57    """
 58    if model.history is None:
 59        raise ValueError(
 60            "This can only be used to serialize models that have already been fit."
 61        )
 62
 63    model_dict = {
 64        attribute: getattr(model, attribute) for attribute in SIMPLE_ATTRIBUTES
 65    }
 66    # Handle attributes of non-core types
 67    for attribute in PD_SERIES:
 68        if getattr(model, attribute) is None:
 69            model_dict[attribute] = None
 70        else:
 71            model_dict[attribute] = getattr(model, attribute).to_json(
 72                orient='split', date_format='iso'
 73            )
 74    for attribute in PD_TIMESTAMP:
 75        model_dict[attribute] = getattr(model, attribute).timestamp()
 76    for attribute in PD_TIMEDELTA:
 77        model_dict[attribute] = getattr(model, attribute).total_seconds()
 78    for attribute in PD_DATAFRAME:
 79        if getattr(model, attribute) is None:
 80            model_dict[attribute] = None
 81        else:
 82            model_dict[attribute] = getattr(model, attribute).to_json(orient='table', index=False)
 83    for attribute in NP_ARRAY:
 84        model_dict[attribute] = getattr(model, attribute).tolist()
 85    for attribute in ORDEREDDICT:
 86        if attribute == 'extra_regressors':
 87            cleaned = OrderedDict()
 88            for name, props in getattr(model, attribute).items():
 89                props_copy = deepcopy(props)
 90                props_copy['predictor'] = None
 91                cleaned[name] = props_copy
 92            model_dict[attribute] = [
 93                list(cleaned.keys()),
 94                cleaned,
 95            ]
 96        else:
 97            model_dict[attribute] = [
 98                list(getattr(model, attribute).keys()),
 99                getattr(model, attribute),
100            ]
101    # Other attributes with special handling
102    # fit_kwargs -> Transform any numpy types before serializing.
103    # They do not need to be transformed back on deserializing.
104    fit_kwargs = deepcopy(model.fit_kwargs)
105    if 'init' in fit_kwargs:
106        for k, v in fit_kwargs['init'].items():
107            if isinstance(v, np.ndarray):
108                fit_kwargs['init'][k] = v.tolist()
109            elif isinstance(v, np.floating):
110                fit_kwargs['init'][k] = float(v)
111    model_dict['fit_kwargs'] = fit_kwargs
112
113    # Params (Dict[str, np.ndarray])
114    model_dict['params'] = {k: v.tolist() for k, v in model.params.items()}
115    # Attributes that are skipped: stan_fit, stan_backend
116    model_dict["__prophet_version"] = __version__
117    return model_dict
118
119
120def model_to_json(model: Prophet) -> str:
121    """Serialize a Prophet model to json string.
122
123    Model must be fitted. Skips Stan objects that are not needed for predict.
124
125    Can be deserialized with model_from_json.
126
127    Parameters
128    ----------
129    model: Prophet model object.
130
131    Returns
132    -------
133    json string that can be deserialized into a Prophet model.
134    """
135    model_json = model_to_dict(model)
136    return json.dumps(model_json)
137
138
139def _handle_simple_attributes_backwards_compat(model_dict: dict[str, Any]) -> None:
140    """Handle backwards compatibility for SIMPLE_ATTRIBUTES."""
141    # prophet<1.1.5: handle scaling parameters introduced in #2470
142    if 'scaling' not in model_dict:
143        model_dict['scaling'] = 'absmax'
144        model_dict['y_min'] = 0.
145    # prophet<1.1.5: handle holidays_mode parameter introduced in #2477
146    if 'holidays_mode' not in model_dict:
147        model_dict['holidays_mode'] = model_dict['seasonality_mode']
148
149def model_from_dict(model_dict: dict[str, Any]) -> Prophet:
150    """Recreate a Prophet model from a dictionary.
151
152    Recreates models that were converted with model_to_dict.
153
154    Parameters
155    ----------
156    model_dict: Dictionary containing model, created with model_to_dict.
157
158    Returns
159    -------
160    Prophet model.
161    """
162    model = Prophet()  # We will overwrite all attributes set in init anyway
163    # Simple types
164    _handle_simple_attributes_backwards_compat(model_dict)
165    for attribute in SIMPLE_ATTRIBUTES:
166        setattr(model, attribute, model_dict[attribute])
167    for attribute in PD_SERIES:
168        if model_dict[attribute] is None:
169            setattr(model, attribute, None)
170        else:
171            s = pd.read_json(StringIO(model_dict[attribute]), typ='series', orient='split')
172            if s.name == 'ds':
173                if len(s) == 0:
174                    s = pd.to_datetime(s)
175                s = s.dt.tz_localize(None)
176            setattr(model, attribute, s)
177    for attribute in PD_TIMESTAMP:
178        pd_ts = pd.Timestamp.fromtimestamp(model_dict[attribute], tz="UTC").tz_localize(None)
179        setattr(model, attribute, pd_ts)
180    for attribute in PD_TIMEDELTA:
181        setattr(model, attribute, pd.Timedelta(seconds=model_dict[attribute]))
182    for attribute in PD_DATAFRAME:
183        if model_dict[attribute] is None:
184            setattr(model, attribute, None)
185        else:
186            df = pd.read_json(StringIO(model_dict[attribute]), typ='frame', orient='table', convert_dates=['ds'])
187            if attribute == 'train_component_cols':
188                # Special handling because of named index column
189                df.columns.name = 'component'
190                df.index.name = 'col'
191            setattr(model, attribute, df)
192    for attribute in NP_ARRAY:
193        setattr(model, attribute, np.array(model_dict[attribute]))
194    for attribute in ORDEREDDICT:
195        key_list, unordered_dict = model_dict[attribute]
196        od = OrderedDict()
197        for key in key_list:
198            od[key] = unordered_dict[key]
199        setattr(model, attribute, od)
200    # Other attributes with special handling
201    # fit_kwargs
202    model.fit_kwargs = model_dict['fit_kwargs']
203    # Params (Dict[str, np.ndarray])
204    model.params = {k: np.array(v) for k, v in model_dict['params'].items()}
205    # Skipped attributes
206    model.stan_backend = None
207    model.stan_fit = None
208    return model
209
210
211def model_from_json(model_json: str) -> Prophet:
212    """Deserialize a Prophet model from json string.
213
214    Deserializes models that were serialized with model_to_json.
215
216    Parameters
217    ----------
218    model_json: Serialized model string
219
220    Returns
221    -------
222    Prophet model.
223    """
224    model_dict = json.loads(model_json)
225    return model_from_dict(model_dict)