<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>Frepple / Forecast module </title>
<link rel='stylesheet' href='../styles.css' type='text/css' />
<!--PageHeaderFmt-->
</head>
<body>
<div id="container">
<div id="menubar">
<div id="logo" align="center">
<br/><img src='../frepple.bmp' alt="frepple" /><br/>
<a href='http://www.frepple.com/'>
<strong>a Free<br/>Production Planning<br/>Library</strong>
</a></div>
<div id="menu">
<br/>
<h3><a href='../Main/HomePage.html'>Main</a></h3>
<h3><a href='../UI/Main.html'>User Manual</a></h3>
<h3><a href='../Tutorial/Main.html'>Tutorial</a></h3>
<h3><a href='Main.html'>Reference Manual</a></h3>
<h3><a href='../Main/FAQ.html'>FAQ</a></h3>
<h3><a href='../reference/index.html'>C++ API</a></h3>
<br/><div>
</div>
</div>
</div>
<div id="content">
<br/>
<!--PageText-->
<div id='wikitext'>
<p><a class='wikilink' href='../Main/HomePage.html'>Main</a> > <span class='wikitrail'><a class='wikilink' href='Main.html'>Reference Manual</a> > <a class='wikilink' href='Modules.html'>Extension modules</a> > <a class='selflink' href='ModulesForecast.html'>Forecast module</a></span>
</p>
<p class='vspace'>The forecast module provides the following functionality for representing forecasted future demand:
</p>
<div class='vspace'></div><ul><li>A <strong>new demand type</strong> to model forecasts.<br /> A calendar model is used to divide the time horizon into a number of time buckets. A demand is automatically created for each time bucket.<br /> See the example below.
<div class='vspace'></div></li><li>A forecasting algorithm to <strong>extrapolate historical demand data to the future</strong>.<br /> The test case forecast_6 contains a benchmark test that demonstrates frePPLe is able to compute a valid forecast that is competitive with other tools in the market.<br /> The following forecasting methods are implemented:
<ul><li><strong>Single exponential smoothing</strong>, which is applicable for constant demands
</li><li><strong>Double exponential smoothing</strong>, which is applicable for trended demands
</li><li><strong>Holt-Winter's exponential smoothing with mutiplicative seasonality</strong>, which is applicable for seasonal demands
</li><li><strong>Croston's method</strong>, which is applicable for intermittent demand (i.e. demand patterns with a lot of zero demand buckets)
</li><li><strong>Moving average</strong>, which is applicable when there is little demand history
</li></ul>The forecast method giving the smallest symmetric mean absolute percentage error (aka "sMAPE"-error) will be automatically picked to produce the forecast.<br /> The forecast methods are also implemented to perform sanity checks on their applicability. E.g. It is not reasonable to apply a trending forecast when we only have very few data points. E.g. The seasonal forecast method is only used when a clear cyclical pattern is found in the data.<br /> The algorithm will automatically tune the parameters for the forecasting methods (i.e. alfa for the single exponential smoothing, alfa and gamma for the double exponential smoothing, etc) to their optimal value. The user can specify minimum and maximum boundaries for the parameters and the maximum allowed number of iterations for the algorithm.<br /> <img src='../uploads/Frepple/fcst_timeseries.png' alt='' title='' />
<div class='vspace'></div></li><li>Functionality for <strong>distributing / profiling forecast numbers into smaller time buckets</strong>.<br /> This functionality allows to translate between different time granularities.<br /> The forecast entered by the sales department could for instance be in monthly buckets, while the manufacturing department requires the forecast to be in weekly or even daily buckets to generate accurate manufacturing and procurement plans.<br /> Another usage is to model a delivery date profile of the customers. Each bucket has a weight that is used to model situations where the demand is not evenly spread across buckets: e.g. when more orders are expected due on a monday than on a friday, or when a peak of orders is expected for delivery near the end of a month.<br /> <img src='../uploads/Frepple/fcst_profiling.png' alt='' title='' />
<div class='vspace'></div></li><li>A solver for <strong>netting orders from the forecast</strong>.<br /> As customer orders are being received they need to be deducted from the forecast to avoid double-counting it. The netting solver will for each order search for a matching forecast and reduce the remaining net quantity of the forecast.<br /> For example, assume the forecast for customer A in January is 100 pieces, and we have already received orders of 20 from the customer.<br /> Without the netting algorithm the demand in January will be 120 pieces, which is (very likely) not correct.<br /> The netting solver will deduct the orders of 20 from the forecast. The total demand that is planned in January will then be equal to 100: 80 remaining forecast + 20 orders.<br /> The solver algorithm has logic to match a demand with the most appropriate forecast, and can also consider netting in previous and subsequent time buckets.<br /> <img src='../uploads/Frepple/fcst_netting.png' alt='' title='' />
<div class='vspace'></div></li><li>The different functionalities can be used together.<br /> Depending on your business process and needs you can also choose not to use them all.
</li></ul><p class='vspace'>The module enables the following new objects:
</p><ul><li><a href='ModulesForecast.html#DEMAND_FORECAST'>demand_forecast</a> is a specialized representation of the demand.
</li><li><a href='ModulesForecast.html#SOLVER_FORECAST'>solver_forecast</a> is a solver for performing the forecast netting calculations.
</li></ul><div class='vspace'></div><h2>Module configuration</h2>
<p>The module support the following configuration parameters:
</p>
<div class='vspace'></div><ul><li><strong>DueAtEndOfBucket</strong>:<br /> By default forecast demand is due at the start of the forecasting bucket. Since the actual customer demand will come in any time in the bucket this is a conservative setting.<br /> By setting this flag to true, the forecast will be due at the end of the forecast bucket. This more relaxed setting may give more realistic plans in some cases.
<div class='vspace'></div></li><li><strong>Net_CustomerThenItemHierarchy</strong>:<br /> As part of the forecast netting a demand is assiociated with a certain forecast. When no matching forecast is found for the customer and item of the demand, frePPLe looks for forecast at higher level customers and items.<br /> This flag allows us to control whether we first search the customer hierarchy and then the item hierarchy, or the other way around.<br /> The default value is true, ie search higher customer levels before searching higher levels of the item.
<div class='vspace'></div></li><li><strong>Net_MatchUsingDeliveryOperation</strong>:<br /> Specifies whether or not a demand and a forecast require to have the same delivery operation to be a match.<br /> The default value is true.
<div class='vspace'></div></li><li><strong>Net_NetEarly</strong>:<br /> Defines how much time before the due date of an order we are allowed to search for a forecast bucket to net from.<br /> The default value is 0, meaning that we can net only from the bucket where the demand is due.
<div class='vspace'></div></li><li><strong>Net_NetLate</strong>:<br /> Defines how much time after the due date of an order we are allowed to search for a forecast bucket to net from.<br /> The default value is 0, meaning that we can net only from the bucket where the demand is due.
<div class='vspace'></div></li><li><strong>Forecast_Iterations</strong>:<br /> Specifies the maximum number of iterations allowed for a forecast method to tune its parameters.<br /> Only positive values are allowed and the default value is 10.<br /> Set the parameter to 1 to disable the tuning and generate a forecast based on the user-supplied parameters.
<div class='vspace'></div></li><li><strong>Forecast_smapeAlfa</strong>:<br /> Specifies how the sMAPE forecast error is weighted for different time buckets. The sMPAPE value in the most recent bucket is 1.0, and the weight decreases exponentially for earlier buckets.<br /> Acceptable values are in the interval 0.5 and 1.0, and the default is 0.95.
<div class='vspace'></div></li><li><strong>Forecast_Skip</strong>:<br /> Specifies the number of time series values used to initialize the forecasting method. The forecast error in these bucket isn't counted.
<div class='vspace'></div></li><li><strong>Forecast_MovingAverage_buckets</strong><br /> This parameter controls the number of buckets to be averaged by the moving average forecast method.
<div class='vspace'></div></li><li><strong>Forecast_SingleExponential_initialAlfa</strong>, <br /> <strong>Forecast_SingleExponential_minAlfa</strong>, <br /> <strong>Forecast_SingleExponential_maxAlfa</strong>:<br /> Specifies the initial value and the allowed range of the smoothing parameter in the single exponential forecasting method.<br /> The allowed range is between 0 and 1. Values lower than about 0.05 are not advisible.
<div class='vspace'></div></li><li><strong>Forecast_DoubleExponential_initialAlfa</strong>, <br /> <strong>Forecast_DoubleExponential_minAlfa</strong>, <br /> <strong>Forecast_DoubleExponential_maxAlfa</strong>:<br /> Specifies the initial value and the allowed range of the smoothing parameter in the double exponential forecasting method.<br /> The allowed range is between 0 and 1. Values lower than about 0.05 are not advisible.
<div class='vspace'></div></li><li><strong>Forecast_DoubleExponential_initialGamma</strong>, <br /> <strong>Forecast_DoubleExponential_minGamma</strong>, <br /> <strong>Forecast_DoubleExponential_maxGamma</strong>:<br /> Specifies the initial value and the allowed range of the trend smoothing parameter in the double exponential forecasting method.<br /> The allowed range is between 0 and 1.
<div class='vspace'></div></li><li><strong>Forecast_DoubleExponential_dampenTrend</strong><br /> Specifies how the trend is dampened for future buckets.<br /> The allowed range is between 0 and 1, and the default value is 0.8.
<div class='vspace'></div></li><li><strong>Forecast_Seasonal_initialAlfa</strong>, <br /> <strong>Forecast_Seasonal_minAlfa</strong>, <br /> <strong>Forecast_Seasonal_maxAlfa</strong>:<br /> Specifies the initial value and the allowed range of the smoothing parameter in the seasonal forecasting method.<br /> The allowed range is between 0 and 1. Values lower than about 0.05 are not advisible.
<div class='vspace'></div></li><li><strong>Forecast_Seasonal_initialBeta</strong>, <br /> <strong>Forecast_Seasonal_minBeta</strong>, <br /> <strong>Forecast_Seasonal_maxBeta</strong>:<br /> Specifies the initial value and the allowed range of the trend smoothing parameter in the seasonal forecasting method.<br /> The allowed range is between 0 and 1.
<div class='vspace'></div></li><li><strong>Forecast_Seasonal_initialGamma</strong>, <br /> <strong>Forecast_Seasonal_minGamma</strong>, <br /> <strong>Forecast_Seasonal_maxGamma</strong>:<br /> Specifies the initial value and the allowed range of the seasonal smoothing parameter in the seasonal forecasting method.<br /> The allowed range is between 0 and 1.
<div class='vspace'></div></li><li><strong>Forecast_Seasonal_minPeriod</strong>, <br /> <strong>Forecast_Seasonal_maxPeriod</strong>:<br /> Specifies the periodicity of the seasonal cycles to check for.<br /> The interval of cycles we try to detect should be broad enough. For instance, if we expect to find a yearly cycle use a minimum period of 10 and maximum period of 14.
<div class='vspace'></div></li><li><strong>Forecast_Seasonal_dampenTrend</strong><br /> Specifies how the trend is dampened for future buckets.<br /> The allowed range is between 0 and 1, and the default value is 0.8.
<div class='vspace'></div></li><li><strong>Forecast_Croston_initialAlfa</strong>, <br /> <strong>Forecast_Croston_minAlfa</strong>, <br /> <strong>Forecast_Croston_maxAlfa</strong>:<br /> Specifies the initial value and the allowed range of the smoothing parameter in the Croston forecasting method.<br /> The allowed range is between 0 and 1. Values lower than about 0.05 are not advisible.
<div class='vspace'></div></li><li><strong>Forecast_Croston_minIntermittence</strong>:<br /> Minimum intermittence (defined as the percentage of zero demand buckets) before the Croston method is applied.<br /> When the intermittence exceeds this value, only Croston and moving average are considered suitable forecast methods.<br /> The default value is 0.33.
</li></ul><p class='vspace'><a name='DEMAND_FORECAST' id='DEMAND_FORECAST'></a>
</p><h2>Demand subclass demand_forecast</h2>
<p>All fields available on the demand model are allowed on a forecast.<br />In particular the item and customer field are important, since these are used to match a demand with a certain forecast for netting.
</p>
<p class='vspace'>The following fields are available in addition to the demand fields.
</p>
<div class='vspace'></div>
<table border='1' width='100%' ><tr><td width='20%' valign='top'><strong>Field</strong>
</td><td width='20%' valign='top'><strong>Type</strong>
</td><td width='60%' valign='top'><strong>Description</strong>
</td></tr><tr><td valign='top'>calendar
</td><td valign='top'>non-empty string
</td><td valign='top'>
<p>Name of the calendar used to define time buckets for distributing the forecast numbers.
</p></td></tr><tr><td valign='top'>discrete
</td><td valign='top'>boolean
</td><td valign='top'>
<p>Specifies whether forecast should be rounded to integer numbers.<br />The default value is true.
</p></td></tr><tr><td valign='top'>bucket<br />buckets
</td><td valign='top'>xml
</td><td valign='top'>
<p>Speficies the forecast value for a date range.<br />See example below.
</p></td></tr></table>
<div class='vspace'></div>
<table border='1' width='100%' ><tr><td width='30%' valign='top'><strong>Method</strong>
</td><td width='70%' valign='top'><strong>Description</strong>
</td></tr><tr><td valign='top'>timeseries([list of demand history data],[list of future time bucket boundaries])
</td><td valign='top'>
<p>This method runs the timeseries algorithms on the input historical demand data, and sets the forecasted value in the specified future time buckets.
</p></td></tr></table>
<p class='vspace'><a name='SOLVER_FORECAST' id='SOLVER_FORECAST'></a>
</p><h2>Solver solver_forecast</h2>
<p>This solver runs the forecast netting calculations.<br />The solver loops through the demands in order of their priority, and for each demand a matching forecast is searched. When a matching forecast is identified, the solver looks for a time bucket to net from: first in the bucket where it is due, then in earlier buckets within the chosen time window, and finally in later buckets within the chosen time window. The net forecast in the forecast buckets is decreased.
</p>
<p class='vspace'>Note the the profiling of the forecast is not handled by this solver. The profiling happens during the data load, i.e. when the forecast demand is read in.
</p>
<p class='vspace'>In addition to the regular solver fields, the following fields are available.
</p>
<div class='vspace'></div>
<table border='1' width='100%' ><tr><td width='20%' valign='top'><strong>Field</strong>
</td><td width='20%' valign='top'><strong>Type</strong>
</td><td width='60%' valign='top'><strong>Description</strong>
</td></tr><tr><td valign='top'>loglevel
</td><td valign='top'>0 - 2
</td><td valign='top'>
<p>Amount of logging and debugging messages:
</p><ul><li>0: Silent operation. Default logging level.
</li><li>1: Log demands being netted and the matching forecast.
</li><li>2: Same as 1, plus details on forecast buckets being netted.
</li></ul></td></tr></table>
<h2>Example XML structures</h2>
<ul><li>Forecast input
</li></ul><pre> <plan>
<demands>
<demand name="Forecast 1" xsi:type="demand_forecast">
<item name="Product 1" />
<customer name="Customer 1" />
<calendar name="planningbuckets" />
<discrete>true</discrete>
<buckets>
<bucket>
<start>2007-01-01T00:00:00</start>
<end>2007-02-01T00:00:00</end>
<total>200</total>
</bucket>
<bucket>
<start>2007-02-01T00:00:00</start>
<end>2007-03-01T00:00:00</end>
<total>200</total>
</bucket>
</buckets>
</demand>
</demands>
</plan>
</pre><div class='vspace'></div><h2>Example Python code</h2>
<ul><li>Adding or changing a forecast
</li></ul><pre> it = frepple.item(name="item")
cust = frepple.customer(name="customer")
cal = frepple.calendar(name="planningbuckets")
fcst = frepple.demand_forecast(name="My forecast",
item=it, customer=cust, calendar=cal)
</pre><div class='vspace'></div><ul><li>Loading the module
</li></ul><pre> frepple.loadmodule("mod_forecast.so",
Net_CustomerThenItemHierarchy=True,
Net_MatchUsingDeliveryOperation=True,
Net_NetEarly="P7D",
Net_NetLate="P7D")
</pre><div class='vspace'></div><ul><li>Creating a time series forecast<br /> The first argument is the demand history in previous buckets.<br /> The second argument are the time buckets where we want to create a forecast value.
</li></ul><pre> thebuckets = [ i.start for i in thecalendar.buckets ]
fcst.timeseries([10,12,9,11,8,15,19,11], thebuckets)
</pre><div class='vspace'></div><ul><li>Netting customer orders from the forecast
</li></ul><pre> frepple_forecast.solver_forecast(name="Netting", loglevel=1).solve()
</pre>
</div>
<!--PageFooterFmt-->
<!--HTMLFooter-->
</div></div>
</body>
</html>
