[Gretl-devel] bundles and series

Herewith a note on the status of series as members of bundles. This is not well documented and -- I have to admit -- was not very well thought out at first. The basic point is that series are not exactly "first-class citizens" in bundles. With most objects that can be put into bundles, you should be able to get exactly the same object back out; if that fails it's a bug that ought to be (and can be) fixed. But series are different: a series can exist only as an element of a dataset, and the "meaning" of a series is dependent on the characteristics of the dataset (cross sectional sample of a certain size, time series of some definite frequency, panel with some definite time-series dimension). It's easy enough to put a series into a bundle (assuming a dataset is in place when the bundle is constructed), but whether you can get the "same series" back out later depends on what has happened to the dataset in the meantime. A bundle can "survive" changes to the dataset -- observations added or removed, or the dataset switched altogether using the --preserve option, or even the removal of any dataset (if the bundle is written to file then read back from file when no dataset is in place). All we can guarantee is that you can get the data back from a bundled series in some form, but if no suitable dataset is in place to "host" the data as a series you'll only be able to get the values back as a "free-floating" column vector. In the following I'll use N to denote the full length, or number of observations, of the current dataset at a specific point in time. In the original implementation, here's what happened: when you added a series to a bundle we stored it as a simple array of doubles, along with a record of its length (which was always the current N). If you later tried to get it out as a series, we checked whether the recorded length matched the now-current N: if not you'd get an error -- but you could still extract it as a matrix (column vector) OK. Here's what's new in git. When you add a series to a bundle we store a column vector (gretl_matrix) of length equal to the current sample range, and on this matrix we record the current sample-range limits, t1 and t2. We can then be a bit more flexible in getting the data back out as a series: the criterion is now that t2 <= N. Given t1 and t2 we can fit the data back into the "right place" even if the length of the vector != N. Below is a hansl snippet which illustrates a possible procedure for a function writer. We first put a series into a bundle. The "..." indicates intervening actions by the user, which might alter the characteristics of the dataset. So when we later want to get a series out of b we should allow for the possibility than b.x is not valid as a series any more. <hansl> bundle b series b.x = x ... catch series x = b.x if $error # fallback matrix m = b.x endif </hansl> Allin