7 #include <sys/types.h> /* size_t */
11 * This file defines the API for the Network Weather Service forecast-
12 * generation library. The functions defined here allow programs to compute
13 * forecasts from time-stamp/value pairs. The logic of operation is:
14 * - create a new ForecasterState
15 * - Update the state with values you observe
16 * - get a forecast back
18 * NOTE: In order to avoid name collisions, all names defined here begin with
19 * FORECASTAPI_. To avoid having to use this prefix, #define
20 * FORECASTAPI_SHORTNAMES before #include'ing this file.
25 * A description of a measurement. The time the measurement was taken
26 * (represented as a number of seconds since midnight, 1/1/1970 GMT) and the
32 } FORECASTAPI_Measurement;
36 * A description of a forecast. The forecast value itself, an estimate of the
37 * precision of the forecast, and an index for the method used to generate it.
42 unsigned int methodUsed;
43 } FORECASTAPI_Forecast;
47 * A description of a collection of forecasts, each one based on minimizing a
48 * different measurement of the error (MAE == MEAN_ABSOLUTE_ERROR, MSE ==
49 * MEAN_SQUARE_ERROR). The actual measurement taken at the same time is
50 * included for convenience when available.
52 #define FORECASTAPI_FORECAST_TYPE_COUNT 2
53 #define FORECASTAPI_MAE_FORECAST 0
54 #define FORECASTAPI_MSE_FORECAST 1
56 FORECASTAPI_Measurement measurement;
57 FORECASTAPI_Forecast forecasts[FORECASTAPI_FORECAST_TYPE_COUNT];
58 } FORECASTAPI_ForecastCollection;
62 * A description of a forecasting state. Client code should obtain these
63 * structures via NewForecastState(), update them with new values via
64 * UpdateForecastState(), then delete them via FreeForecastState().
66 struct FORECASTAPI_ForecastStateStruct;
67 typedef struct FORECASTAPI_ForecastStateStruct FORECASTAPI_ForecastState;
71 * Frees the memory occupied by the forecasting state pointed to by #state#
72 * and sets #state# to NULL.
75 FORECASTAPI_FreeForecastState(FORECASTAPI_ForecastState **state);
79 * Returns the name of the #methodIndex#th forecasting method used by the
80 * forecasting library, or NULL if #methodIndex# is out of range.
83 FORECASTAPI_MethodName(unsigned int methodIndex);
87 * Allocates and returns a new forecasting state, or NULL if memory is
88 * exhausted. The caller should eventually call FreeForecastingState() to
91 FORECASTAPI_ForecastState *
92 FORECASTAPI_NewForecastState(void);
96 * Incorporates the #howManyMeasurements#-long series #measurements# into the
97 * forecasting state #state#. If #forecasts# is non-NULL, it points to a
98 * #howManyForecasts#-long array into which the function should store
99 * forecasts generated during the course of the update If #howManyForecasts#
100 * is less than #howManyMeasurements#, the forecasts derived from the later
101 * measurements (which appear at the beginning of #measurements#) are stored.
104 FORECASTAPI_UpdateForecastState(FORECASTAPI_ForecastState *state,
105 const FORECASTAPI_Measurement *measurements,
106 size_t howManyMeasurements,
107 FORECASTAPI_ForecastCollection *forecasts,
108 size_t howManyForecasts);
109 #define FORECASTAPI_UpdateForecast(state, measurements, howMany) \
110 FORECASTAPI_UpdateForecastState(state, measurements, howMany, NULL, 0)
113 * Return a set of forecast base on the current state of the forecaster.
114 * #forecast# need to have space for at least one ForecastCollection.
116 * Return 1 in case of error, 0 otherwise.
118 * Warning: The measurement insite the Collection is not meaningful.
121 FORECASTAPI_ComputeForecast( FORECASTAPI_ForecastState *state,
122 FORECASTAPI_ForecastCollection *forecast);
124 #ifdef FORECASTAPI_SHORTNAMES
126 #define Measurement FORECASTAPI_Measurement
127 #define Forecast FORECASTAPI_Forecast
128 #define FORECAST_TYPE_COUNT FORECASTAPI_FORECAST_TYPE_COUNT
129 #define MAE_FORECAST FORECASTAPI_MAE_FORECAST
130 #define MSE_FORECAST FORECASTAPI_MSE_FORECAST
131 #define ForecastCollection FORECASTAPI_ForecastCollection
132 #define ForecastStateStruct FORECASTAPI_ForecastStateStruct
133 #define ForecastState FORECASTAPI_ForecastState
134 #define FreeForecastState FORECASTAPI_FreeForecastState
135 #define MethodName FORECASTAPI_MethodName
136 #define NewForecastState FORECASTAPI_NewForecastState
137 #define UpdateForecastState FORECASTAPI_UpdateForecastState
138 #define UpdateForecast FORECASTAPI_UpdateForecast
139 #define ComputeForecast FORECASTAPI_ComputeForecast