prophet.models

  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 abc import abstractmethod, ABC
  9from dataclasses import dataclass
 10from collections import OrderedDict
 11from enum import Enum
 12import importlib.resources
 13import pathlib
 14import platform
 15from typing import TYPE_CHECKING, Any, Sequence, cast
 16
 17import numpy as np
 18import pandas as pd
 19
 20import logging
 21logger: logging.Logger = logging.getLogger('prophet.models')
 22
 23if TYPE_CHECKING:
 24    from cmdstanpy import CmdStanMCMC, CmdStanMLE, CmdStanModel
 25    from typing_extensions import TypedDict, Unpack, type_check_only, final
 26
 27    @type_check_only
 28    @final
 29    class _IStanBackendOptions(TypedDict, total=False):
 30        newton_fallback: bool
 31
 32PLATFORM = "win" if platform.platform().startswith("Win") else "unix"
 33
 34class TrendIndicator(Enum):
 35    LINEAR = 0
 36    LOGISTIC = 1
 37    FLAT = 2
 38
 39@dataclass
 40class ModelInputData:
 41    T: int
 42    S: int
 43    K: int
 44    tau: float
 45    trend_indicator: int
 46    y: Sequence[float] | pd.Series  # length T
 47    t: Sequence[float] | pd.Series  # length T
 48    cap: Sequence[float] | np.ndarray | pd.Series  # length T
 49    t_change: Sequence[float] | np.ndarray  # length S
 50    s_a: Sequence[int] | pd.Series  # length K
 51    s_m: Sequence[int] | pd.Series  # length K
 52    X: Sequence[Sequence[float]] | pd.DataFrame  # shape (T, K)
 53    sigmas: Sequence[float]  # length K
 54
 55@dataclass
 56class ModelParams:
 57    k: float
 58    m: float
 59    delta: Sequence[float] | np.ndarray  # length S
 60    beta: Sequence[float] | np.ndarray  # length K
 61    sigma_obs: float
 62
 63
 64class IStanBackend(ABC):
 65    model: Any
 66    stan_fit: Any | None
 67    newton_fallback: bool
 68    
 69    def __init__(self) -> None:
 70        self.model = self.load_model()
 71        self.stan_fit = None
 72        self.newton_fallback = True
 73
 74    def set_options(self, **kwargs: Unpack[_IStanBackendOptions]) -> None:
 75        """
 76        Specify model options as kwargs.
 77         * newton_fallback [bool]: whether to fallback to Newton if L-BFGS fails
 78        """
 79        for k, v in kwargs.items():
 80            if k == 'newton_fallback':
 81                self.newton_fallback = cast(bool, v)
 82            else:
 83                raise ValueError(f'Unknown option {k}')
 84    
 85    def cleanup(self) -> None:
 86        """Clean up temporary files created during model fitting."""
 87        pass
 88
 89
 90    @staticmethod
 91    @abstractmethod
 92    def get_type() -> str:
 93        pass
 94
 95    @abstractmethod
 96    def load_model(self) -> Any:
 97        pass
 98
 99    @abstractmethod
100    def fit(
101        self,
102        stan_init: dict[str, float],
103        stan_data: dict[str, Any],
104        **kwargs: Any,
105    ) -> dict[str, Any]:
106        pass
107
108    @abstractmethod
109    def sampling(
110        self,
111        stan_init: dict[str, float],
112        stan_data: dict[str, Any],
113        samples: int,
114        **kwargs: Any,
115    ) -> dict[str, Any]:
116        pass
117
118
119class CmdStanPyBackend(IStanBackend):
120    CMDSTAN_VERSION = "2.37.0"
121
122    model: CmdStanModel
123    stan_fit: CmdStanMLE | CmdStanMCMC | None
124    
125    def __init__(self) -> None:
126        import cmdstanpy
127        # this must be set before super.__init__() for load_model to work on Windows
128        local_cmdstan = cast(
129            pathlib.Path,
130            importlib.resources.files("prophet") / "stan_model" / f"cmdstan-{self.CMDSTAN_VERSION}",
131        )
132        if local_cmdstan.exists():
133            cmdstanpy.set_cmdstan_path(str(local_cmdstan))
134        super().__init__()
135
136    @staticmethod
137    def get_type() -> str:
138        return StanBackendEnum.CMDSTANPY.name
139
140    def load_model(self) -> CmdStanModel:
141        import cmdstanpy
142        model_file = importlib.resources.files("prophet") / "stan_model" / "prophet_model.bin"
143        return cmdstanpy.CmdStanModel(exe_file=str(model_file))
144
145    def fit(
146        self,
147        stan_init: dict[str, float], 
148        stan_data: dict[str, Any],
149        **kwargs: Any,
150    ) -> OrderedDict[str, np.ndarray]:
151        if 'inits' not in kwargs and 'init' in kwargs:
152            stan_init = self.sanitize_custom_inits(stan_init, kwargs['init'])
153            del kwargs['init']
154
155        inits_list, data_list = self.prepare_data(stan_init, stan_data)
156        args = dict(
157            data=data_list,
158            inits=inits_list,
159            algorithm='Newton' if cast(float, data_list['T']) < 100 else 'LBFGS',
160            iter=int(1e4),
161        )
162        args.update(kwargs)
163
164        try:
165            self.stan_fit = self.model.optimize(**args)
166        except RuntimeError as e:
167            # Fall back on Newton
168            if not self.newton_fallback or args['algorithm'] == 'Newton':
169                raise e
170            logger.warning('Optimization terminated abnormally. Falling back to Newton.')
171            args['algorithm'] = 'Newton'
172            self.stan_fit = self.model.optimize(**args)
173        params = self.stan_to_dict_numpy(
174            self.stan_fit.column_names, self.stan_fit.optimized_params_np)
175        for par in params:
176            params[par] = params[par].reshape((1, -1))
177        return params
178
179    def sampling(
180        self,
181        stan_init: dict[str, float],
182        stan_data: dict[str, Any],
183        samples: int,
184        **kwargs: Any,
185    ) -> OrderedDict[str, np.ndarray]:
186        if 'inits' not in kwargs and 'init' in kwargs:
187            stan_init = self.sanitize_custom_inits(stan_init, kwargs['init'])
188            del kwargs['init']
189
190        inits_list, data_list = self.prepare_data(stan_init, stan_data)
191        args = dict(
192            data=data_list,
193            inits=inits_list,
194        )
195        if 'chains' not in kwargs:
196            kwargs['chains'] = 4
197        iter_half = samples // 2
198        kwargs['iter_sampling'] = iter_half
199        if 'iter_warmup' not in kwargs:
200            kwargs['iter_warmup'] = iter_half
201        args.update(kwargs)
202
203        self.stan_fit = self.model.sample(**args)
204        res = self.stan_fit.draws()
205        (samples, c, columns) = res.shape
206        res = res.reshape((samples * c, columns))
207        params = self.stan_to_dict_numpy(self.stan_fit.column_names, res)
208
209        for par in params:
210            s = params[par].shape
211            if s[1] == 1:
212                params[par] = params[par].reshape((s[0],))
213
214            if par in ['delta', 'beta'] and len(s) < 2:
215                params[par] = params[par].reshape((-1, 1))
216
217        return params
218
219    def cleanup(self) -> None:
220        import cmdstanpy
221
222        if hasattr(self, "stan_fit") and self.stan_fit is not None:
223            fit_result: cmdstanpy.CmdStanMLE | cmdstanpy.CmdStanMCMC = self.stan_fit
224            to_remove = (
225                fit_result.runset.csv_files +
226                fit_result.runset.diagnostic_files +
227                fit_result.runset.stdout_files +
228                fit_result.runset.profile_files
229            )
230            for fpath in to_remove:
231                if pathlib.Path(fpath).is_file():
232                    pathlib.Path(fpath).unlink()
233
234    @staticmethod
235    def sanitize_custom_inits(
236        default_inits: dict[str, Any],
237        custom_inits: dict[str, Any],
238    ) -> dict[str, float | Any]:
239        """Validate that custom inits have the correct type and shape, otherwise use defaults."""
240        sanitized = {}
241        for param in ['k', 'm', 'sigma_obs']:
242            try:
243                sanitized[param] = float(custom_inits[param])
244            except Exception:
245                sanitized[param] = default_inits[param]
246        for param in ['delta', 'beta']:
247            if default_inits[param].shape == custom_inits[param].shape:
248                sanitized[param] = custom_inits[param]
249            else:
250                sanitized[param] = default_inits[param]
251        return sanitized
252
253    @staticmethod
254    def prepare_data(
255        init: dict[str, Any],
256        data: dict[str, Any],
257    ) -> tuple[dict[str, float | list[float]], dict[str, float | list[float]]]:
258        """Converts np.ndarrays to lists that can be read by cmdstanpy."""
259        cmdstanpy_data = {
260            'T': data['T'],
261            'S': data['S'],
262            'K': data['K'],
263            'tau': data['tau'],
264            'trend_indicator': data['trend_indicator'],
265            'y': data['y'].tolist(),
266            't': data['t'].tolist(),
267            'cap': data['cap'].tolist(),
268            't_change': data['t_change'].tolist(),
269            's_a': data['s_a'].tolist(),
270            's_m': data['s_m'].tolist(),
271            'X': data['X'].to_numpy().tolist(),
272            'sigmas': data['sigmas']
273        }
274
275        cmdstanpy_init = {
276            'k': init['k'],
277            'm': init['m'],
278            'delta': init['delta'].tolist(),
279            'beta': init['beta'].tolist(),
280            'sigma_obs': init['sigma_obs']
281        }
282        return (cmdstanpy_init, cmdstanpy_data)
283
284    @staticmethod
285    def stan_to_dict_numpy(
286        column_names: Sequence[str],
287        data: np.ndarray,
288    ) -> OrderedDict[str, np.ndarray]:
289        output: OrderedDict[str, np.ndarray] = OrderedDict()
290
291        prev: str | None = None
292
293        start = 0
294        end = 0
295        two_dims = len(data.shape) > 1
296        for cname in column_names:
297            parsed = cname.split(".") if "." in cname else cname.split("[")
298            curr = parsed[0]
299            if prev is None:
300                prev = curr
301
302            if curr != prev:
303                if prev in output:
304                    raise RuntimeError(
305                        "Found repeated column name"
306                    )
307                if two_dims:
308                    output[prev] = np.array(data[:, start:end])
309                else:
310                    output[prev] = np.array(data[start:end])
311                prev = curr
312                start = end
313            end += 1
314        if prev in output:
315            raise RuntimeError(
316                "Found repeated column name"
317            )
318        assert prev is not None
319        if two_dims:
320            output[prev] = np.array(data[:, start:end])
321        else:
322            output[prev] = np.array(data[start:end])
323        return output
324
325
326
327
328class StanBackendEnum(Enum):
329    CMDSTANPY = CmdStanPyBackend
330
331    @staticmethod
332    def get_backend_class(name: str) -> type[IStanBackend]:
333        try:
334            return StanBackendEnum[name].value
335        except KeyError as e:
336            raise ValueError(f"Unknown stan backend: {name}") from e
logger: logging.Logger = <Logger prophet.models (INFO)>
PLATFORM = 'unix'
class TrendIndicator(enum.Enum):
35class TrendIndicator(Enum):
36    LINEAR = 0
37    LOGISTIC = 1
38    FLAT = 2
LINEAR = <TrendIndicator.LINEAR: 0>
LOGISTIC = <TrendIndicator.LOGISTIC: 1>
FLAT = <TrendIndicator.FLAT: 2>
@dataclass
class ModelInputData:
40@dataclass
41class ModelInputData:
42    T: int
43    S: int
44    K: int
45    tau: float
46    trend_indicator: int
47    y: Sequence[float] | pd.Series  # length T
48    t: Sequence[float] | pd.Series  # length T
49    cap: Sequence[float] | np.ndarray | pd.Series  # length T
50    t_change: Sequence[float] | np.ndarray  # length S
51    s_a: Sequence[int] | pd.Series  # length K
52    s_m: Sequence[int] | pd.Series  # length K
53    X: Sequence[Sequence[float]] | pd.DataFrame  # shape (T, K)
54    sigmas: Sequence[float]  # length K
ModelInputData( T: int, S: int, K: int, tau: float, trend_indicator: int, y: Union[Sequence[float], pandas.Series], t: Union[Sequence[float], pandas.Series], cap: Union[Sequence[float], numpy.ndarray, pandas.Series], t_change: Union[Sequence[float], numpy.ndarray], s_a: Union[Sequence[int], pandas.Series], s_m: Union[Sequence[int], pandas.Series], X: Union[Sequence[Sequence[float]], pandas.DataFrame], sigmas: Sequence[float])
T: int
S: int
K: int
tau: float
trend_indicator: int
y: Union[Sequence[float], pandas.Series]
t: Union[Sequence[float], pandas.Series]
cap: Union[Sequence[float], numpy.ndarray, pandas.Series]
t_change: Union[Sequence[float], numpy.ndarray]
s_a: Union[Sequence[int], pandas.Series]
s_m: Union[Sequence[int], pandas.Series]
X: Union[Sequence[Sequence[float]], pandas.DataFrame]
sigmas: Sequence[float]
@dataclass
class ModelParams:
56@dataclass
57class ModelParams:
58    k: float
59    m: float
60    delta: Sequence[float] | np.ndarray  # length S
61    beta: Sequence[float] | np.ndarray  # length K
62    sigma_obs: float
ModelParams( k: float, m: float, delta: Union[Sequence[float], numpy.ndarray], beta: Union[Sequence[float], numpy.ndarray], sigma_obs: float)
k: float
m: float
delta: Union[Sequence[float], numpy.ndarray]
beta: Union[Sequence[float], numpy.ndarray]
sigma_obs: float
class IStanBackend(abc.ABC):
 65class IStanBackend(ABC):
 66    model: Any
 67    stan_fit: Any | None
 68    newton_fallback: bool
 69    
 70    def __init__(self) -> None:
 71        self.model = self.load_model()
 72        self.stan_fit = None
 73        self.newton_fallback = True
 74
 75    def set_options(self, **kwargs: Unpack[_IStanBackendOptions]) -> None:
 76        """
 77        Specify model options as kwargs.
 78         * newton_fallback [bool]: whether to fallback to Newton if L-BFGS fails
 79        """
 80        for k, v in kwargs.items():
 81            if k == 'newton_fallback':
 82                self.newton_fallback = cast(bool, v)
 83            else:
 84                raise ValueError(f'Unknown option {k}')
 85    
 86    def cleanup(self) -> None:
 87        """Clean up temporary files created during model fitting."""
 88        pass
 89
 90
 91    @staticmethod
 92    @abstractmethod
 93    def get_type() -> str:
 94        pass
 95
 96    @abstractmethod
 97    def load_model(self) -> Any:
 98        pass
 99
100    @abstractmethod
101    def fit(
102        self,
103        stan_init: dict[str, float],
104        stan_data: dict[str, Any],
105        **kwargs: Any,
106    ) -> dict[str, Any]:
107        pass
108
109    @abstractmethod
110    def sampling(
111        self,
112        stan_init: dict[str, float],
113        stan_data: dict[str, Any],
114        samples: int,
115        **kwargs: Any,
116    ) -> dict[str, Any]:
117        pass

Helper class that provides a standard way to create an ABC using inheritance.

model: Any
stan_fit: typing.Any | None
newton_fallback: bool
def set_options(self, **kwargs: 'Unpack[_IStanBackendOptions]') -> None:
75    def set_options(self, **kwargs: Unpack[_IStanBackendOptions]) -> None:
76        """
77        Specify model options as kwargs.
78         * newton_fallback [bool]: whether to fallback to Newton if L-BFGS fails
79        """
80        for k, v in kwargs.items():
81            if k == 'newton_fallback':
82                self.newton_fallback = cast(bool, v)
83            else:
84                raise ValueError(f'Unknown option {k}')

Specify model options as kwargs.

  • newton_fallback [bool]: whether to fallback to Newton if L-BFGS fails
def cleanup(self) -> None:
86    def cleanup(self) -> None:
87        """Clean up temporary files created during model fitting."""
88        pass

Clean up temporary files created during model fitting.

@staticmethod
@abstractmethod
def get_type() -> str:
91    @staticmethod
92    @abstractmethod
93    def get_type() -> str:
94        pass
@abstractmethod
def load_model(self) -> Any:
96    @abstractmethod
97    def load_model(self) -> Any:
98        pass
@abstractmethod
def fit( self, stan_init: dict[str, float], stan_data: dict[str, typing.Any], **kwargs: Any) -> dict[str, typing.Any]:
100    @abstractmethod
101    def fit(
102        self,
103        stan_init: dict[str, float],
104        stan_data: dict[str, Any],
105        **kwargs: Any,
106    ) -> dict[str, Any]:
107        pass
@abstractmethod
def sampling( self, stan_init: dict[str, float], stan_data: dict[str, typing.Any], samples: int, **kwargs: Any) -> dict[str, typing.Any]:
109    @abstractmethod
110    def sampling(
111        self,
112        stan_init: dict[str, float],
113        stan_data: dict[str, Any],
114        samples: int,
115        **kwargs: Any,
116    ) -> dict[str, Any]:
117        pass
class CmdStanPyBackend(IStanBackend):
120class CmdStanPyBackend(IStanBackend):
121    CMDSTAN_VERSION = "2.37.0"
122
123    model: CmdStanModel
124    stan_fit: CmdStanMLE | CmdStanMCMC | None
125    
126    def __init__(self) -> None:
127        import cmdstanpy
128        # this must be set before super.__init__() for load_model to work on Windows
129        local_cmdstan = cast(
130            pathlib.Path,
131            importlib.resources.files("prophet") / "stan_model" / f"cmdstan-{self.CMDSTAN_VERSION}",
132        )
133        if local_cmdstan.exists():
134            cmdstanpy.set_cmdstan_path(str(local_cmdstan))
135        super().__init__()
136
137    @staticmethod
138    def get_type() -> str:
139        return StanBackendEnum.CMDSTANPY.name
140
141    def load_model(self) -> CmdStanModel:
142        import cmdstanpy
143        model_file = importlib.resources.files("prophet") / "stan_model" / "prophet_model.bin"
144        return cmdstanpy.CmdStanModel(exe_file=str(model_file))
145
146    def fit(
147        self,
148        stan_init: dict[str, float], 
149        stan_data: dict[str, Any],
150        **kwargs: Any,
151    ) -> OrderedDict[str, np.ndarray]:
152        if 'inits' not in kwargs and 'init' in kwargs:
153            stan_init = self.sanitize_custom_inits(stan_init, kwargs['init'])
154            del kwargs['init']
155
156        inits_list, data_list = self.prepare_data(stan_init, stan_data)
157        args = dict(
158            data=data_list,
159            inits=inits_list,
160            algorithm='Newton' if cast(float, data_list['T']) < 100 else 'LBFGS',
161            iter=int(1e4),
162        )
163        args.update(kwargs)
164
165        try:
166            self.stan_fit = self.model.optimize(**args)
167        except RuntimeError as e:
168            # Fall back on Newton
169            if not self.newton_fallback or args['algorithm'] == 'Newton':
170                raise e
171            logger.warning('Optimization terminated abnormally. Falling back to Newton.')
172            args['algorithm'] = 'Newton'
173            self.stan_fit = self.model.optimize(**args)
174        params = self.stan_to_dict_numpy(
175            self.stan_fit.column_names, self.stan_fit.optimized_params_np)
176        for par in params:
177            params[par] = params[par].reshape((1, -1))
178        return params
179
180    def sampling(
181        self,
182        stan_init: dict[str, float],
183        stan_data: dict[str, Any],
184        samples: int,
185        **kwargs: Any,
186    ) -> OrderedDict[str, np.ndarray]:
187        if 'inits' not in kwargs and 'init' in kwargs:
188            stan_init = self.sanitize_custom_inits(stan_init, kwargs['init'])
189            del kwargs['init']
190
191        inits_list, data_list = self.prepare_data(stan_init, stan_data)
192        args = dict(
193            data=data_list,
194            inits=inits_list,
195        )
196        if 'chains' not in kwargs:
197            kwargs['chains'] = 4
198        iter_half = samples // 2
199        kwargs['iter_sampling'] = iter_half
200        if 'iter_warmup' not in kwargs:
201            kwargs['iter_warmup'] = iter_half
202        args.update(kwargs)
203
204        self.stan_fit = self.model.sample(**args)
205        res = self.stan_fit.draws()
206        (samples, c, columns) = res.shape
207        res = res.reshape((samples * c, columns))
208        params = self.stan_to_dict_numpy(self.stan_fit.column_names, res)
209
210        for par in params:
211            s = params[par].shape
212            if s[1] == 1:
213                params[par] = params[par].reshape((s[0],))
214
215            if par in ['delta', 'beta'] and len(s) < 2:
216                params[par] = params[par].reshape((-1, 1))
217
218        return params
219
220    def cleanup(self) -> None:
221        import cmdstanpy
222
223        if hasattr(self, "stan_fit") and self.stan_fit is not None:
224            fit_result: cmdstanpy.CmdStanMLE | cmdstanpy.CmdStanMCMC = self.stan_fit
225            to_remove = (
226                fit_result.runset.csv_files +
227                fit_result.runset.diagnostic_files +
228                fit_result.runset.stdout_files +
229                fit_result.runset.profile_files
230            )
231            for fpath in to_remove:
232                if pathlib.Path(fpath).is_file():
233                    pathlib.Path(fpath).unlink()
234
235    @staticmethod
236    def sanitize_custom_inits(
237        default_inits: dict[str, Any],
238        custom_inits: dict[str, Any],
239    ) -> dict[str, float | Any]:
240        """Validate that custom inits have the correct type and shape, otherwise use defaults."""
241        sanitized = {}
242        for param in ['k', 'm', 'sigma_obs']:
243            try:
244                sanitized[param] = float(custom_inits[param])
245            except Exception:
246                sanitized[param] = default_inits[param]
247        for param in ['delta', 'beta']:
248            if default_inits[param].shape == custom_inits[param].shape:
249                sanitized[param] = custom_inits[param]
250            else:
251                sanitized[param] = default_inits[param]
252        return sanitized
253
254    @staticmethod
255    def prepare_data(
256        init: dict[str, Any],
257        data: dict[str, Any],
258    ) -> tuple[dict[str, float | list[float]], dict[str, float | list[float]]]:
259        """Converts np.ndarrays to lists that can be read by cmdstanpy."""
260        cmdstanpy_data = {
261            'T': data['T'],
262            'S': data['S'],
263            'K': data['K'],
264            'tau': data['tau'],
265            'trend_indicator': data['trend_indicator'],
266            'y': data['y'].tolist(),
267            't': data['t'].tolist(),
268            'cap': data['cap'].tolist(),
269            't_change': data['t_change'].tolist(),
270            's_a': data['s_a'].tolist(),
271            's_m': data['s_m'].tolist(),
272            'X': data['X'].to_numpy().tolist(),
273            'sigmas': data['sigmas']
274        }
275
276        cmdstanpy_init = {
277            'k': init['k'],
278            'm': init['m'],
279            'delta': init['delta'].tolist(),
280            'beta': init['beta'].tolist(),
281            'sigma_obs': init['sigma_obs']
282        }
283        return (cmdstanpy_init, cmdstanpy_data)
284
285    @staticmethod
286    def stan_to_dict_numpy(
287        column_names: Sequence[str],
288        data: np.ndarray,
289    ) -> OrderedDict[str, np.ndarray]:
290        output: OrderedDict[str, np.ndarray] = OrderedDict()
291
292        prev: str | None = None
293
294        start = 0
295        end = 0
296        two_dims = len(data.shape) > 1
297        for cname in column_names:
298            parsed = cname.split(".") if "." in cname else cname.split("[")
299            curr = parsed[0]
300            if prev is None:
301                prev = curr
302
303            if curr != prev:
304                if prev in output:
305                    raise RuntimeError(
306                        "Found repeated column name"
307                    )
308                if two_dims:
309                    output[prev] = np.array(data[:, start:end])
310                else:
311                    output[prev] = np.array(data[start:end])
312                prev = curr
313                start = end
314            end += 1
315        if prev in output:
316            raise RuntimeError(
317                "Found repeated column name"
318            )
319        assert prev is not None
320        if two_dims:
321            output[prev] = np.array(data[:, start:end])
322        else:
323            output[prev] = np.array(data[start:end])
324        return output

Helper class that provides a standard way to create an ABC using inheritance.

CMDSTAN_VERSION = '2.37.0'
model: cmdstanpy.model.CmdStanModel
stan_fit: cmdstanpy.stanfit.mle.CmdStanMLE | cmdstanpy.stanfit.mcmc.CmdStanMCMC | None
@staticmethod
def get_type() -> str:
137    @staticmethod
138    def get_type() -> str:
139        return StanBackendEnum.CMDSTANPY.name
def load_model(self) -> cmdstanpy.model.CmdStanModel:
141    def load_model(self) -> CmdStanModel:
142        import cmdstanpy
143        model_file = importlib.resources.files("prophet") / "stan_model" / "prophet_model.bin"
144        return cmdstanpy.CmdStanModel(exe_file=str(model_file))
def fit( self, stan_init: dict[str, float], stan_data: dict[str, typing.Any], **kwargs: Any) -> collections.OrderedDict[str, numpy.ndarray]:
146    def fit(
147        self,
148        stan_init: dict[str, float], 
149        stan_data: dict[str, Any],
150        **kwargs: Any,
151    ) -> OrderedDict[str, np.ndarray]:
152        if 'inits' not in kwargs and 'init' in kwargs:
153            stan_init = self.sanitize_custom_inits(stan_init, kwargs['init'])
154            del kwargs['init']
155
156        inits_list, data_list = self.prepare_data(stan_init, stan_data)
157        args = dict(
158            data=data_list,
159            inits=inits_list,
160            algorithm='Newton' if cast(float, data_list['T']) < 100 else 'LBFGS',
161            iter=int(1e4),
162        )
163        args.update(kwargs)
164
165        try:
166            self.stan_fit = self.model.optimize(**args)
167        except RuntimeError as e:
168            # Fall back on Newton
169            if not self.newton_fallback or args['algorithm'] == 'Newton':
170                raise e
171            logger.warning('Optimization terminated abnormally. Falling back to Newton.')
172            args['algorithm'] = 'Newton'
173            self.stan_fit = self.model.optimize(**args)
174        params = self.stan_to_dict_numpy(
175            self.stan_fit.column_names, self.stan_fit.optimized_params_np)
176        for par in params:
177            params[par] = params[par].reshape((1, -1))
178        return params
def sampling( self, stan_init: dict[str, float], stan_data: dict[str, typing.Any], samples: int, **kwargs: Any) -> collections.OrderedDict[str, numpy.ndarray]:
180    def sampling(
181        self,
182        stan_init: dict[str, float],
183        stan_data: dict[str, Any],
184        samples: int,
185        **kwargs: Any,
186    ) -> OrderedDict[str, np.ndarray]:
187        if 'inits' not in kwargs and 'init' in kwargs:
188            stan_init = self.sanitize_custom_inits(stan_init, kwargs['init'])
189            del kwargs['init']
190
191        inits_list, data_list = self.prepare_data(stan_init, stan_data)
192        args = dict(
193            data=data_list,
194            inits=inits_list,
195        )
196        if 'chains' not in kwargs:
197            kwargs['chains'] = 4
198        iter_half = samples // 2
199        kwargs['iter_sampling'] = iter_half
200        if 'iter_warmup' not in kwargs:
201            kwargs['iter_warmup'] = iter_half
202        args.update(kwargs)
203
204        self.stan_fit = self.model.sample(**args)
205        res = self.stan_fit.draws()
206        (samples, c, columns) = res.shape
207        res = res.reshape((samples * c, columns))
208        params = self.stan_to_dict_numpy(self.stan_fit.column_names, res)
209
210        for par in params:
211            s = params[par].shape
212            if s[1] == 1:
213                params[par] = params[par].reshape((s[0],))
214
215            if par in ['delta', 'beta'] and len(s) < 2:
216                params[par] = params[par].reshape((-1, 1))
217
218        return params
def cleanup(self) -> None:
220    def cleanup(self) -> None:
221        import cmdstanpy
222
223        if hasattr(self, "stan_fit") and self.stan_fit is not None:
224            fit_result: cmdstanpy.CmdStanMLE | cmdstanpy.CmdStanMCMC = self.stan_fit
225            to_remove = (
226                fit_result.runset.csv_files +
227                fit_result.runset.diagnostic_files +
228                fit_result.runset.stdout_files +
229                fit_result.runset.profile_files
230            )
231            for fpath in to_remove:
232                if pathlib.Path(fpath).is_file():
233                    pathlib.Path(fpath).unlink()

Clean up temporary files created during model fitting.

@staticmethod
def sanitize_custom_inits( default_inits: dict[str, typing.Any], custom_inits: dict[str, typing.Any]) -> dict[str, float | typing.Any]:
235    @staticmethod
236    def sanitize_custom_inits(
237        default_inits: dict[str, Any],
238        custom_inits: dict[str, Any],
239    ) -> dict[str, float | Any]:
240        """Validate that custom inits have the correct type and shape, otherwise use defaults."""
241        sanitized = {}
242        for param in ['k', 'm', 'sigma_obs']:
243            try:
244                sanitized[param] = float(custom_inits[param])
245            except Exception:
246                sanitized[param] = default_inits[param]
247        for param in ['delta', 'beta']:
248            if default_inits[param].shape == custom_inits[param].shape:
249                sanitized[param] = custom_inits[param]
250            else:
251                sanitized[param] = default_inits[param]
252        return sanitized

Validate that custom inits have the correct type and shape, otherwise use defaults.

@staticmethod
def prepare_data( init: dict[str, typing.Any], data: dict[str, typing.Any]) -> tuple[dict[str, float | list[float]], dict[str, float | list[float]]]:
254    @staticmethod
255    def prepare_data(
256        init: dict[str, Any],
257        data: dict[str, Any],
258    ) -> tuple[dict[str, float | list[float]], dict[str, float | list[float]]]:
259        """Converts np.ndarrays to lists that can be read by cmdstanpy."""
260        cmdstanpy_data = {
261            'T': data['T'],
262            'S': data['S'],
263            'K': data['K'],
264            'tau': data['tau'],
265            'trend_indicator': data['trend_indicator'],
266            'y': data['y'].tolist(),
267            't': data['t'].tolist(),
268            'cap': data['cap'].tolist(),
269            't_change': data['t_change'].tolist(),
270            's_a': data['s_a'].tolist(),
271            's_m': data['s_m'].tolist(),
272            'X': data['X'].to_numpy().tolist(),
273            'sigmas': data['sigmas']
274        }
275
276        cmdstanpy_init = {
277            'k': init['k'],
278            'm': init['m'],
279            'delta': init['delta'].tolist(),
280            'beta': init['beta'].tolist(),
281            'sigma_obs': init['sigma_obs']
282        }
283        return (cmdstanpy_init, cmdstanpy_data)

Converts np.ndarrays to lists that can be read by cmdstanpy.

@staticmethod
def stan_to_dict_numpy( column_names: Sequence[str], data: numpy.ndarray) -> collections.OrderedDict[str, numpy.ndarray]:
285    @staticmethod
286    def stan_to_dict_numpy(
287        column_names: Sequence[str],
288        data: np.ndarray,
289    ) -> OrderedDict[str, np.ndarray]:
290        output: OrderedDict[str, np.ndarray] = OrderedDict()
291
292        prev: str | None = None
293
294        start = 0
295        end = 0
296        two_dims = len(data.shape) > 1
297        for cname in column_names:
298            parsed = cname.split(".") if "." in cname else cname.split("[")
299            curr = parsed[0]
300            if prev is None:
301                prev = curr
302
303            if curr != prev:
304                if prev in output:
305                    raise RuntimeError(
306                        "Found repeated column name"
307                    )
308                if two_dims:
309                    output[prev] = np.array(data[:, start:end])
310                else:
311                    output[prev] = np.array(data[start:end])
312                prev = curr
313                start = end
314            end += 1
315        if prev in output:
316            raise RuntimeError(
317                "Found repeated column name"
318            )
319        assert prev is not None
320        if two_dims:
321            output[prev] = np.array(data[:, start:end])
322        else:
323            output[prev] = np.array(data[start:end])
324        return output
class StanBackendEnum(enum.Enum):
329class StanBackendEnum(Enum):
330    CMDSTANPY = CmdStanPyBackend
331
332    @staticmethod
333    def get_backend_class(name: str) -> type[IStanBackend]:
334        try:
335            return StanBackendEnum[name].value
336        except KeyError as e:
337            raise ValueError(f"Unknown stan backend: {name}") from e
CMDSTANPY = <StanBackendEnum.CMDSTANPY: <class 'CmdStanPyBackend'>>
@staticmethod
def get_backend_class(name: str) -> type[IStanBackend]:
332    @staticmethod
333    def get_backend_class(name: str) -> type[IStanBackend]:
334        try:
335            return StanBackendEnum[name].value
336        except KeyError as e:
337            raise ValueError(f"Unknown stan backend: {name}") from e