prophet-rb 0.3.1 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0656a4f1c6761438bfd9e6eeaed0bc30547cd10e794cdf2d12d208309fd57fd5
-  data.tar.gz: 8e6e1304ae81f33ac648a93bb287f9f206be2d800a40cbc82fffe295a285546d
+  metadata.gz: 69d58f060a9bda44b1ab8666ded81b3e61ff1b95b08ae40727fa7a2dfee57ee0
+  data.tar.gz: dc76685a8b45ca7cad79561f986af9c66e5e49bd45dd5e10c72f91088d9b470a
 SHA512:
-  metadata.gz: 9954683d0197627894eb1727690bf6007f05e94e896783f70ca66c4dff748a00829e68478ab155a30dcfbc971c4646032b046e58d7cc01bf0e38be98b851c504
-  data.tar.gz: 145e6f2974f79ba8cfe0836d7d71f39924b7f4800f73a776d9c17e3f10b7aa3e889ef82a8b9c30795df51b5c13f0fd189ca83fe7d841215572d6cc857301ddc9
+  metadata.gz: 34d2fd0587110c6de9db334c44a4859a5de92d1cc124efb5f865c845d504816f3d3cd34d63776a709de396af8f9b2cf82a390cfb9f3e49e685ef8be4f469fb3e
+  data.tar.gz: '0587986407bb68a9ca97928ad65bcbb42fe101bd9d2e50a44b2126df38d67c04544932ec39009c6f1d6467736aa0a8404ac4aad04187dcb953285d4d5ee80a77'

data/CHANGELOG.md

@@ -1,8 +1,23 @@
-## 0.3.1 (2021-04-28)
+## 0.4.1 (2022-07-10)
+
+- Added support for cross validation and performance metrics
+- Added support for updating fitted models
+- Added support for saturating minimum forecasts
+
+## 0.4.0 (2022-07-07)
+
+- Added support for saving and loading models
+- Updated holidays
+
+## 0.3.2 (2022-05-15)
+
+- Added advanced API options to `forecast` and `anomalies` methods
+
+## 0.3.1 (2022-04-28)
 
 - Improved error message for missing columns
 
-## 0.3.0 (2021-04-24)
+## 0.3.0 (2022-04-24)
 
 - Switched to precompiled models
 - Dropped support for Ruby < 2.7

data/LICENSE.txt

@@ -1,7 +1,7 @@
 MIT License
 
 Copyright (c) Facebook, Inc. and its affiliates.
-Copyright (c) 2020 Andrew Kane
+Copyright (c) 2020-2022 Andrew Kane
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -22,6 +22,8 @@ gem "prophet-rb"
 
 ## Simple API
 
+### Forecasting
+
 Get future predictions for a time series
 
 ```ruby
@@ -48,16 +50,47 @@ series = User.group_by_day(:created_at).count
 Prophet.forecast(series)
 ```
 
+And supports [advanced API](#advanced-api) options
+
+```ruby
+Prophet.forecast(series, growth: "logistic", weekly_seasonality: false)
+```
+
+### Anomaly Detection
+
 Detect anomalies in a time series
 
 ```ruby
 Prophet.anomalies(series)
 ```
 
+Specify the width of uncertainty intervals (decrease for more anomalies)
+
+```ruby
+Prophet.anomalies(series, interval_width: 0.99)
+```
+
+Also supports [advanced API](#advanced-api) options
+
+```ruby
+Prophet.anomalies(series, growth: "logistic", weekly_seasonality: false)
+```
+
 ## Advanced API
 
 Check out the [Prophet documentation](https://facebook.github.io/prophet/docs/quick_start.html) for a great explanation of all of the features. The advanced API follows the Python API and supports the same features. It uses [Rover](https://github.com/ankane/rover) for data frames.
 
+- [Quick Start](#advanced-quick-start)
+- [Plots](#plots)
+- [Saturating Forecasts](#saturating-forecasts)
+- [Trend Changepoints](#trend-changepoints)
+- [Holidays and Special Events](#holidays-and-special-events)
+- [Multiplicative Seasonality](#multiplicative-seasonality)
+- [Uncertainty Intervals](#uncertainty-intervals)
+- [Non-Daily Data](#non-daily-data)
+- [Diagnostics](#diagnostics)
+- [Additional Topics](#additional-topics)
+
 ## Advanced Quick Start
 
 [Explanation](https://facebook.github.io/prophet/docs/quick_start.html)
@@ -145,11 +178,24 @@ df = Rover.read_csv("example_wp_log_R.csv")
 df["cap"] = 8.5
 m = Prophet.new(growth: "logistic")
 m.fit(df)
-future = m.make_future_dataframe(periods: 365)
+future = m.make_future_dataframe(periods: 1826)
 future["cap"] = 8.5
 forecast = m.predict(future)
 ```
 
+Saturating minimum
+
+```ruby
+df["y"] = 10 - df["y"]
+df["cap"] = 6
+df["floor"] = 1.5
+future["cap"] = 6
+future["floor"] = 1.5
+m = Prophet.new(growth: "logistic")
+m.fit(df)
+forecast = m.predict(future)
+```
+
 ## Trend Changepoints
 
 [Explanation](https://facebook.github.io/prophet/docs/trend_changepoints.html)
@@ -206,7 +252,7 @@ Add country-specific holidays
 
 ```ruby
 m = Prophet.new
-m.add_country_holidays(country_name: "US")
+m.add_country_holidays("US")
 m.fit(df)
 ```
 
@@ -276,6 +322,107 @@ future = m.make_future_dataframe(periods: 300, freq: "H")
 forecast = m.predict(future)
 ```
 
+## Diagnostics
+
+[Explanation](http://facebook.github.io/prophet/docs/diagnostics.html)
+
+Cross validation
+
+```ruby
+df_cv = Prophet::Diagnostics.cross_validation(m, initial: "730 days", period: "180 days", horizon: "365 days")
+```
+
+Custom cutoffs
+
+```ruby
+cutoffs = ["2013-02-15", "2013-08-15", "2014-02-15"].map { |v| Time.parse("#{v} 00:00:00 UTC") }
+df_cv2 = Prophet::Diagnostics.cross_validation(m, cutoffs: cutoffs, horizon: "365 days")
+```
+
+Get performance metrics
+
+```ruby
+df_p = Prophet::Diagnostics.performance_metrics(df_cv)
+```
+
+Plot cross validation metrics
+
+```ruby
+Prophet::Plot.plot_cross_validation_metric(df_cv, metric: "mape")
+```
+
+Hyperparameter tuning
+
+```ruby
+param_grid = {
+  changepoint_prior_scale: [0.001, 0.01, 0.1, 0.5],
+  seasonality_prior_scale: [0.01, 0.1, 1.0, 10.0]
+}
+
+# Generate all combinations of parameters
+all_params = param_grid.values[0].product(*param_grid.values[1..-1]).map { |v| param_grid.keys.zip(v).to_h }
+rmses = [] # Store the RMSEs for each params here
+
+# Use cross validation to evaluate all parameters
+all_params.each do |params|
+  m = Prophet.new(**params).fit(df) # Fit model with given params
+  df_cv = Prophet::Diagnostics.cross_validation(m, cutoffs: cutoffs, horizon: "30 days")
+  df_p = Prophet::Diagnostics.performance_metrics(df_cv, rolling_window: 1)
+  rmses << df_p["rmse"][0]
+end
+
+# Find the best parameters
+tuning_results = Rover::DataFrame.new(all_params)
+tuning_results["rmse"] = rmses
+p tuning_results
+```
+
+## Additional Topics
+
+[Explanation](https://facebook.github.io/prophet/docs/additional_topics.html)
+
+Save a model
+
+```ruby
+File.write("model.json", m.to_json)
+```
+
+Load a model
+
+```ruby
+m = Prophet.from_json(File.read("model.json"))
+```
+
+Uses the same format as Python, so models can be saved and loaded in either language
+
+Flat trend
+
+```ruby
+m = Prophet.new(growth: "flat")
+```
+
+Updating fitted models
+
+```ruby
+def stan_init(m)
+  res = {}
+  ["k", "m", "sigma_obs"].each do |pname|
+    res[pname] = m.params[pname][0, true][0]
+  end
+  ["delta", "beta"].each do |pname|
+    res[pname] = m.params[pname][0, true]
+  end
+  res
+end
+
+df = Rover.read_csv("example_wp_log_peyton_manning.csv")
+df1 = df[df["ds"] <= "2016-01-19"] # All data except the last day
+m1 = Prophet.new.fit(df1) # A model fit to all data except the last day
+
+m2 = Prophet.new.fit(df) # Adding the last day, fitting from scratch
+m2 = Prophet.new.fit(df, init: stan_init(m1)) # Adding the last day, warm-starting from m1
+```
+
 ## Resources
 
 - [Forecasting at Scale](https://peerj.com/preprints/3190.pdf)

data/data-raw/LICENSE-holidays.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2017-2022 <maurizio.montel@gmail.com>
+Copyright (c) 2014-2017 <ryanssdev@icloud.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/data-raw/README.md

@@ -0,0 +1,3 @@
+Holidays from 1995 through 2044 are generated from [this script](https://github.com/facebook/prophet/blob/main/python/scripts/generate_holidays_file.py).
+
+The data is primarily based on the Python [holidays](https://pypi.org/project/holidays/) package.