dataset

dataset

Synopsis

enum                DatasetStructure;
enum                DatasetMarkerType;
enum                VarinfoFlags;
enum                DatasetOp;
enum                DataCopyFlag;
enum                CompactMethod;
#define             dataset_is_cross_section            (p)
#define             dataset_is_time_series              (p)
#define             dataset_is_seasonal                 (p)
#define             custom_time_series                  (p)
#define             dataset_is_daily                    (p)
#define             dataset_is_weekly                   (p)
#define             dataset_is_hourly                   (p)
#define             dataset_is_decennial                (p)
#define             dated_daily_data                    (p)
#define             dated_seven_day_data                (p)
#define             dated_weekly_data                   (p)
#define             calendar_data                       (p)
#define             quarterly_or_monthly                (p)
#define             annual_data                         (p)
#define             decennial_data                      (p)
#define             dataset_is_panel                    (p)
#define             dataset_has_markers                 (p)
#define             dataset_has_panel_time              (p)
#define             sample_size                         (p)
#define             dset_get_data                       (d,
                                                         i,
                                                         t)
#define             dset_set_data                       (d,
                                                         i,
                                                         t,
                                                         x)
void                free_Z                              (DATASET *dset);
DATASET *           datainfo_new                        (void);
void                datainfo_init                       (DATASET *dset);
DATASET *           create_new_dataset                  (int nvar,
                                                         int nobs,
                                                         int markers);
DATASET *           create_auxiliary_dataset            (int nvar,
                                                         int nobs,
                                                         gretlopt opt);
void                destroy_dataset                     (DATASET *dset);
void                clear_datainfo                      (DATASET *dset,
                                                         int code);
int                 allocate_Z                          (DATASET *dset,
                                                         gretlopt opt);
int                 dataset_allocate_varnames           (DATASET *dset);
int                 dataset_allocate_obs_markers        (DATASET *dset);
void                dataset_destroy_obs_markers         (DATASET *dset);
void                dataset_obs_info_default            (DATASET *dset);
void                copy_dataset_obs_info               (DATASET *targ,
                                                         const DATASET *src);
void                copy_varinfo                        (VARINFO *targ,
                                                         const VARINFO *src);
void                set_sorted_markers                  (DATASET *dset,
                                                         int v,
                                                         char **S);
void                dataset_set_regular_markers         (DATASET *dset);
int                 start_new_Z                         (DATASET *dset,
                                                         gretlopt opt);
int                 is_trend_variable                   (const double *x,
                                                         int n);
int                 is_periodic_dummy                   (const double *x,
                                                         const DATASET *dset);
int                 dataset_add_observations            (DATASET *dset,
                                                         int n,
                                                         gretlopt opt);
int                 dataset_drop_observations           (DATASET *dset,
                                                         int n);
int                 dataset_shrink_obs_range            (DATASET *dset);
int                 dataset_add_series                  (DATASET *dset,
                                                         int newvars);
int                 dataset_add_NA_series               (DATASET *dset);
int                 dataset_add_allocated_series        (DATASET *dset,
                                                         double *x);
int                 dataset_add_series_as               (DATASET *dset,
                                                         double *x,
                                                         const char *name);
int                 dataset_copy_series_as              (DATASET *dset,
                                                         int v,
                                                         const char *name);
int                 overwrite_err                       (const char *name);
int                 series_is_parent                    (const DATASET *dset,
                                                         int v);
int                 dataset_replace_series              (DATASET *dset,
                                                         int v,
                                                         double *x,
                                                         const char *descrip,
                                                         DataCopyFlag flag);
int                 dataset_rename_series               (DATASET *dset,
                                                         int v,
                                                         const char *name);
int                 dataset_drop_listed_variables       (int *list,
                                                         DATASET *dset,
                                                         int *renumber,
                                                         PRN *prn);
int                 dataset_drop_variable               (int v,
                                                         DATASET *dset);
int                 dataset_destroy_hidden_variables    (DATASET *dset,
                                                         int vmin);
int                 dataset_drop_last_variables         (DATASET *dset,
                                                         int delvars);
int                 dataset_renumber_variable           (int v_old,
                                                         int v_new,
                                                         DATASET *dset);
int                 renumber_series_with_checks         (const char *s,
                                                         int fixmax,
                                                         DATASET *dset,
                                                         PRN *prn);
int                 maybe_prune_dataset                 (DATASET **pdset,
                                                         void *p);
int                 dataset_stack_variables             (const char *vname,
                                                         const char *line,
                                                         DATASET *dset,
                                                         PRN *prn);
int                 dataset_sort_by                     (DATASET *dset,
                                                         const int *list,
                                                         gretlopt opt);
int                 dataset_set_matrix_name             (DATASET *dset,
                                                         const char *name);
const char *        dataset_get_matrix_name             (const DATASET *dset);
const char *        dataset_period_label                (const DATASET *dset);
int                 series_is_log                       (const DATASET *dset,
                                                         int i,
                                                         char *parent);
void                series_set_discrete                 (DATASET *dset,
                                                         int i,
                                                         int s);
int                 series_record_display_name          (DATASET *dset,
                                                         int i,
                                                         const char *s);
int                 series_record_label                 (DATASET *dset,
                                                         int i,
                                                         const char *s);
const char *        series_get_graph_name               (const DATASET *dset,
                                                         int i);
unsigned int        get_resampling_seed                 (void);
int                 dataset_resample                    (DATASET *dset,
                                                         int n,
                                                         unsigned int seed);
int                 dataset_op_from_string              (const char *s);
int                 modify_dataset                      (DATASET *dset,
                                                         int op,
                                                         const int *list,
                                                         const char *s,
                                                         PRN *prn);
int                 dataset_get_structure               (const DATASET *dset);
int                 panel_sample_size                   (const DATASET *dset);
int                 multi_unit_panel_sample             (const DATASET *dset);
int                 dataset_purge_missing_rows          (DATASET *dset);
int                 check_dataset_is_changed            (void);
void                set_dataset_is_changed              (void);
int                 dataset_set_time_series             (DATASET *dset,
                                                         int pd,
                                                         int yr0,
                                                         int minor0);
int                 series_is_discrete                  (const DATASET *dset,
                                                         int i);
int                 series_is_hidden                    (const DATASET *dset,
                                                         int i);
int                 series_is_generated                 (const DATASET *dset,
                                                         int i);
int                 series_is_listarg                   (const DATASET *dset,
                                                         int i);
int                 series_get_flags                    (DATASET *dset,
                                                         int i);
void                series_set_flag                     (DATASET *dset,
                                                         int i,
                                                         int flag);
void                series_unset_flag                   (DATASET *dset,
                                                         int i,
                                                         int flag);
void                series_zero_flags                   (DATASET *dset,
                                                         int i);
const char *        series_get_label                    (const DATASET *dset,
                                                         int i);
const char *        series_get_display_name             (const DATASET *dset,
                                                         int i);
const char *        series_get_parent_name              (const DATASET *dset,
                                                         int i);
int                 series_get_parent_id                (const DATASET *dset,
                                                         int i);
int                 series_get_compact_method           (const DATASET *dset,
                                                         int i);
int                 series_get_stack_level              (const DATASET *dset,
                                                         int i);
int                 series_get_transform                (const DATASET *dset,
                                                         int i);
int                 series_get_lag                      (const DATASET *dset,
                                                         int i);
void                series_set_label                    (DATASET *dset,
                                                         int i,
                                                         const char *s);
void                series_set_display_name             (DATASET *dset,
                                                         int i,
                                                         const char *s);
void                series_set_compact_method           (DATASET *dset,
                                                         int i,
                                                         int method);
void                series_set_parent                   (DATASET *dset,
                                                         int i,
                                                         const char *parent);
void                series_set_transform                (DATASET *dset,
                                                         int i,
                                                         int transform);
void                series_set_lag                      (DATASET *dset,
                                                         int i,
                                                         int lag);
void                series_set_stack_level              (DATASET *dset,
                                                         int i,
                                                         int level);
void                series_increment_stack_level        (DATASET *dset,
                                                         int i);
void                series_decrement_stack_level        (DATASET *dset,
                                                         int i);
void                series_attach_string_table          (DATASET *dset,
                                                         int i,
                                                         void *ptr);
void                series_destroy_string_table         (DATASET *dset,
                                                         int i);
int                 is_string_valued                    (const DATASET *dset,
                                                         int i);
series_table *      series_get_string_table             (const DATASET *dset,
                                                         int i);
const char *        series_get_string_for_obs           (const DATASET *dset,
                                                         int i,
                                                         int t);
const char *        series_get_string_for_value         (const DATASET *dset,
                                                         int i,
                                                         double val);
int                 series_set_string_val               (DATASET *dset,
                                                         int i,
                                                         int t,
                                                         const char *s);
double              series_decode_string                (const DATASET *dset,
                                                         int i,
                                                         const char *s);
const char **       series_get_string_vals              (const DATASET *dset,
                                                         int i,
                                                         int *n_strs);
int                 steal_string_table                  (DATASET *l_dset,
                                                         int lvar,
                                                         DATASET *r_dset,
                                                         int rvar);
int                 set_panel_groups_name               (DATASET *dset,
                                                         const char *vname);
char const **       get_panel_group_names               (DATASET *dset);
int                 panel_group_names_ok                (const DATASET *dset);
const char *        panel_group_names_varname           (const DATASET *dset);
int                 is_panel_group_names_series         (const DATASET *dset,
                                                         int v);
                    series_table;

Description

Details

enum DatasetStructure

typedef enum {
    DATA_NONE,
    DATA_XSECT,
    DATA_TS,
    DATA_PANEL
} DatasetStructure;

DATA_NONE

DATA_XSECT

DATA_TS

DATA_PANEL


enum DatasetMarkerType

typedef enum {
    NO_MARKERS = 0,
    REGULAR_MARKERS,
    DAILY_DATE_STRINGS
} DatasetMarkerType;

NO_MARKERS

REGULAR_MARKERS

DAILY_DATE_STRINGS


enum VarinfoFlags

typedef enum {
    VAR_DISCRETE   = 1 << 0,
    VAR_HIDDEN     = 1 << 1,
    VAR_GENERATED  = 1 << 2,
    VAR_LISTARG    = 1 << 3,
    VAR_TIMECOL    = 1 << 4
} VarinfoFlags;

VAR_DISCRETE

VAR_HIDDEN

VAR_GENERATED

VAR_LISTARG

VAR_TIMECOL


enum DatasetOp

typedef enum {
    DS_NONE,
    DS_ADDOBS,
    DS_COMPACT,
    DS_EXPAND,
    DS_TRANSPOSE,
    DS_DELETE,
    DS_KEEP,
    DS_SORTBY,
    DS_DSORTBY,
    DS_RESAMPLE,
    DS_RESTORE,
    DS_CLEAR,
    DS_RENUMBER,
    DS_INSOBS
} DatasetOp;

DS_NONE

DS_ADDOBS

DS_COMPACT

DS_EXPAND

DS_TRANSPOSE

DS_DELETE

DS_KEEP

DS_SORTBY

DS_DSORTBY

DS_RESAMPLE

DS_RESTORE

DS_CLEAR

DS_RENUMBER

DS_INSOBS


enum DataCopyFlag

typedef enum {
    DS_COPY_VALUES,
    DS_GRAB_VALUES
} DataCopyFlag;

DS_COPY_VALUES

DS_GRAB_VALUES


enum CompactMethod

typedef enum {
    COMPACT_NONE,
    COMPACT_SUM,
    COMPACT_AVG,
    COMPACT_SOP,
    COMPACT_EOP,
    COMPACT_WDAY,
    COMPACT_MAX
} CompactMethod;

Symbolic codes for various methods of compacting data series (i.e. converting from a higher to a lower frequency). COMPACT_WDAY is applicable only when converting from daily to weekly frequency.

COMPACT_NONE

no data compaction

COMPACT_SUM

take sum of higher frequency data

COMPACT_AVG

take mean of higher frequency data

COMPACT_SOP

use start-of-period value

COMPACT_EOP

use end-of-period value

COMPACT_WDAY

use a specified day of the week

COMPACT_MAX

sentinel value

dataset_is_cross_section()

#define dataset_is_cross_section(p) (p != NULL && p->structure == CROSS_SECTION)

Attempt to determine whether a dataset contains cross-sectional data (1) or not (0).

p :

pointer to data information struct.

dataset_is_time_series()

#define             dataset_is_time_series(p)

Attempt to determine whether a dataset contains time series data (1) or not (0).

p :

pointer to data information struct.

dataset_is_seasonal()

#define             dataset_is_seasonal(p)

Attempt to determine whether a dataset contains seasonal time series data (1) or not (0).

p :

pointer to data information struct.

custom_time_series()

#define custom_time_series(p) (p != NULL && p->structure == SPECIAL_TIME_SERIES)

Attempt to determine whether a dataset contains time series data with custom (non-standard) frequency (1) or not (0).

p :

pointer to data information struct.

dataset_is_daily()

#define             dataset_is_daily(p)

Attempt to determine whether a dataset contains daily time series data (1) or not (0).

p :

pointer to data information struct.

dataset_is_weekly()

#define             dataset_is_weekly(p)

Attempt to determine whether a dataset contains weekly time series data (1) or not (0).

p :

pointer to data information struct.

dataset_is_hourly()

#define             dataset_is_hourly(p)

Attempt to determine whether a dataset contains hourly time series data (1) or not (0).

p :

pointer to data information struct.

dataset_is_decennial()

#define             dataset_is_decennial(p)

Attempt to determine whether a dataset contains decennial time series data (1) or not (0).

p :

pointer to data information struct.

dated_daily_data()

#define             dated_daily_data(p)

Attempt to determine whether a dataset contains dated daily time series data (1) or not (0).

p :

pointer to data information struct.

dated_seven_day_data()

#define             dated_seven_day_data(p)

Attempt to determine whether a dataset contains dated daily (seven-day) time series data (1) or not (0).

p :

pointer to data information struct.

dated_weekly_data()

#define             dated_weekly_data(p)

Attempt to determine whether a dataset contains dated weekly time series data (1) or not (0).

p :

pointer to data information struct.

calendar_data()

#define             calendar_data(p)

Attempt to determine whether a dataset uses calendar dates for observation strings (1) or not (0).

p :

pointer to data information struct.

quarterly_or_monthly()

#define             quarterly_or_monthly(p)

Attempt to determine whether a dataset is a quarterly or monthly time series (1), or something else (0).

p :

pointer to data information struct.

annual_data()

#define             annual_data(p)

Attempt to determine whether a dataset is an annual time series (1), or something else (0).

p :

pointer to data information struct.

decennial_data()

#define             decennial_data(p)

Attempt to determine whether a dataset is a decemmial time series (1), or something else (0).

p :

pointer to data information struct.

dataset_is_panel()

#define dataset_is_panel(p) (p != NULL && p->structure == STACKED_TIME_SERIES)

Attempt to determine whether a dataset contains panel data (1) or not (0).

p :

pointer to data information struct.

dataset_has_markers()

#define dataset_has_markers(p) (p != NULL && p->markers && p->S != NULL)

Determine whether a dataset has observation marker strings (1) or not (0).

p :

pointer to data information struct.

dataset_has_panel_time()

#define             dataset_has_panel_time(p)

Determine whether a panel dataset has information on its time dimension recorded (1) or not (0).

p :

pointer to data information struct.

sample_size()

#define sample_size(p) ((p == NULL)? 0 : (p->t2 - p->t1 + 1))

Retrieves the length of the current sample range.

p :

pointer to data information struct.

dset_get_data()

#define dset_get_data(d,i,t) (d->Z[i][t])

Gets the value of series i at observation t.

d :

pointer to dataset.

i :

index number of variable.

t :

observation number.

dset_set_data()

#define dset_set_data(d,i,t,x) (d->Z[i][t]=x)

Sets the value of series i at observation t.

d :

pointer to dataset.

i :

index number of variable.

t :

observation number.

x :

value to set.

free_Z ()

void                free_Z                              (DATASET *dset);

Does a deep free on the data matrix.

dset :

dataset information.

datainfo_new ()

DATASET *           datainfo_new                        (void);

Creates a new data information struct pointer from scratch, properly initialized as empty (no variables, no observations).

Returns :

pointer to data information struct, or NULL on error.

datainfo_init ()

void                datainfo_init                       (DATASET *dset);

Zeros all members of dset and sets it as a plain cross-section. Designed for use with a DATASET structure that has not been obtained via datainfo_new().

dset :

pointer to DATASET struct.

create_new_dataset ()

DATASET *           create_new_dataset                  (int nvar,
                                                         int nobs,
                                                         int markers);

Allocates space in the dataset to hold the specified number of variables and observations.

nvar :

number of variables.

nobs :

number of observations per variable.

markers :

1 if space should be allocated for "case markers" for the observations, 0 otherwise.

Returns :

pointer to dataset struct, or NULL on error.

create_auxiliary_dataset ()

DATASET *           create_auxiliary_dataset            (int nvar,
                                                         int nobs,
                                                         gretlopt opt);


destroy_dataset ()

void                destroy_dataset                     (DATASET *dset);

Frees all resources associated with dset.

dset :

pointer to dataset.

clear_datainfo ()

void                clear_datainfo                      (DATASET *dset,
                                                         int code);

Frees the allocated content of a data information struct; note that dset itself is not freed.

dset :

data information struct.

code :

either CLEAR_FULL or CLEAR_SUBSAMPLE.

allocate_Z ()

int                 allocate_Z                          (DATASET *dset,
                                                         gretlopt opt);

Allocates the two-dimensional data array Z, based on the v (number of variables) and n (number of observations) members of dset. The variable at position 0 is initialized to all 1s; other variables are initialized to NADBL (unless OPT_B is given).

dset :

pointer to dataset.

opt :

may include OPT_B to indicate that the data columns will be "borrowed".

Returns :

0 on success, E_ALLOC on error.

dataset_allocate_varnames ()

int                 dataset_allocate_varnames           (DATASET *dset);

Given a blank dset, which should have been obtained using datainfo_new(), allocate space for the names of variables. The v member of dset (representing the number of variables, including the automatically added constant at position 0) must be set before calling this function.

dset :

pointer to dataset.

Returns :

0 on sucess, E_ALLOC on failure.

dataset_allocate_obs_markers ()

int                 dataset_allocate_obs_markers        (DATASET *dset);

Allocates space in dset for strings indentifying the observations and initializes all of the markers to empty strings. Note that These strings have a fixed maximum length of OBSLEN - 1.

dset :

pointer to dataset

Returns :

0 on success, E_ALLOC on error.

dataset_destroy_obs_markers ()

void                dataset_destroy_obs_markers         (DATASET *dset);

Frees any allocated observation markers for dset.

dset :

data information struct.

dataset_obs_info_default ()

void                dataset_obs_info_default            (DATASET *dset);

Sets the "date" or observations information in dset to a simple default of cross-sectional data, observations 1 to n, where n is the n element (number of observations) in dset.

dset :

pointer to dataset.

copy_dataset_obs_info ()

void                copy_dataset_obs_info               (DATASET *targ,
                                                         const DATASET *src);

Sets the "date" or observations information in targ to that found in src.

targ :

pointer to target dataset.

src :

pointer to source dataset.

copy_varinfo ()

void                copy_varinfo                        (VARINFO *targ,
                                                         const VARINFO *src);

Copies all relevant information from src to targ.

targ :

target to which to copy.

src :

source to copy from.

set_sorted_markers ()

void                set_sorted_markers                  (DATASET *dset,
                                                         int v,
                                                         char **S);


dataset_set_regular_markers ()

void                dataset_set_regular_markers         (DATASET *dset);


start_new_Z ()

int                 start_new_Z                         (DATASET *dset,
                                                         gretlopt opt);

Initializes the data array within dset (adding the constant in position 0).

dset :

pointer to dataset.

opt :

if includes OPT_R we're sub-sampling from a full data set.

Returns :

0 on successful completion, non-zero on error.

is_trend_variable ()

int                 is_trend_variable                   (const double *x,
                                                         int n);

x :

array to examine.

n :

number of elements in array.

Returns :

1 if x is a simple linear trend variable, with each observation equal to the preceding observation plus 1, or if x is a quadratic trend starting at 1 for the first observation in the data set, and 0 otherwise.

is_periodic_dummy ()

int                 is_periodic_dummy                   (const double *x,
                                                         const DATASET *dset);

x :

array to examine.

dset :

pointer to dataset.

Returns :

1 if x is a periodic dummy variable, 0 otherwise.

dataset_add_observations ()

int                 dataset_add_observations            (DATASET *dset,
                                                         int n,
                                                         gretlopt opt);

Extends all series in the dataset by the specified number of extra observations. The added values are initialized to the missing value code, NADBL, with the exception of simple deterministic variables when OPT_A is given.

dset :

pointer to dataset.

n :

number of observations to add.

opt :

use OPT_A to attempt to recognize and automatically extend simple deterministic variables such as a time trend and periodic dummy variables; use OPT_D to drop any observation markers rather than expanding the set of markers and padding it out with dummy values.

Returns :

0 on success, non-zero code on error.

dataset_drop_observations ()

int                 dataset_drop_observations           (DATASET *dset,
                                                         int n);

Deletes n observations from the end of each series in the dataset.

dset :

pointer to dataset.

n :

number of observations to drop.

Returns :

0 on success, non-zero code on error.

dataset_shrink_obs_range ()

int                 dataset_shrink_obs_range            (DATASET *dset);

Truncates the range of observations in the dataset, based on the current values of the t1 and t2 members of dset.

dset :

pointer to dataset.

Returns :

0 on success, non-zero code on error.

dataset_add_series ()

int                 dataset_add_series                  (DATASET *dset,
                                                         int newvars);

Adds space for the specified number of additional series in the dataset. Values are initialized to zero.

dset :

pointer to dataset.

newvars :

number of series to add.

Returns :

0 on success, E_ALLOC on error.

dataset_add_NA_series ()

int                 dataset_add_NA_series               (DATASET *dset);

Adds space for one additional series in the dataset; the values of the new series are initialized to NADBL.

dset :

pointer to dataset.

Returns :

0 on success, E_ALLOC on error.

dataset_add_allocated_series ()

int                 dataset_add_allocated_series        (DATASET *dset,
                                                         double *x);

Adds x as an additional series in the dataset. The array x is not copied; it should be treated as belonging to dset after this operation.

dset :

pointer to dataset.

x :

one-dimensional data array.

Returns :

0 on success, E_ALLOC on error.

dataset_add_series_as ()

int                 dataset_add_series_as               (DATASET *dset,
                                                         double *x,
                                                         const char *name);

Adds to the dataset a new series with name name and values given by x. The new variable is added at one level "deeper" (in terms of function execution) than the current level. This is for use with user-defined functions.

dset :

pointer to dataset.

x :

array to be added.

name :

name to give the new variable.

Returns :

0 on success, E_ALLOC on error.

dataset_copy_series_as ()

int                 dataset_copy_series_as              (DATASET *dset,
                                                         int v,
                                                         const char *name);

Makes a copy of series v under the name name. The copy exists in a variable namespace one level "deeper" (in terms of function execution) than the variable being copied. This is for use with user-defined functions: a variable supplied to a function as an argument is copied into the function's namespace under the name it was given as a parameter.

dset :

pointer to dataset.

v :

index number of variable to copy.

name :

name to give the copy.

Returns :

0 on success, E_ALLOC on error.

overwrite_err ()

int                 overwrite_err                       (const char *name);


series_is_parent ()

int                 series_is_parent                    (const DATASET *dset,
                                                         int v);

dset :

dataset information.

v :

ID number of series to test.

Returns :

1 if variable v is "parent" to a transformed variable (e.g. a log, lag or difference), othewise 0.

dataset_replace_series ()

int                 dataset_replace_series              (DATASET *dset,
                                                         int v,
                                                         double *x,
                                                         const char *descrip,
                                                         DataCopyFlag flag);

Replaces the description and numerical content of series v with the information provided.

dset :

pointer to dataset.

v :

ID number of the series to be replaced.

x :

replacement values.

descrip :

replacement description.

flag :

if = DS_GRAB_VALUES then replace dset->Z[v] with x, otherwise copy the values the values in x to dset->Z[v];

Returns :

0 on success, non-zero on error.

dataset_rename_series ()

int                 dataset_rename_series               (DATASET *dset,
                                                         int v,
                                                         const char *name);

dset :

dataset information.

v :

ID number of the series to be renamed.

name :

new name to give the series.

Returns :

0 on success, non-zero on error.

dataset_drop_listed_variables ()

int                 dataset_drop_listed_variables       (int *list,
                                                         DATASET *dset,
                                                         int *renumber,
                                                         PRN *prn);

Deletes the variables given in list from the dataset. Remaining variables may have their ID numbers changed as a consequence. If renumber is not NULL, this location receives 1 in case variables have been renumbered, 0 otherwise.

list :

list of variable to drop, by ID number.

dset :

pointer to dataset.

renumber :

location for return of information on whether remaining variables have been renumbered as a result, or NULL.

prn :

pointer to printing struct.

Returns :

0 on success, E_ALLOC on error.

dataset_drop_variable ()

int                 dataset_drop_variable               (int v,
                                                         DATASET *dset);

Deletes variable v from the dataset.

v :

ID number of variable to drop.

dset :

pointer to dataset.

Returns :

0 on success, E_ALLOC on error.

dataset_destroy_hidden_variables ()

int                 dataset_destroy_hidden_variables    (DATASET *dset,
                                                         int vmin);

Deletes from the dataset any "hidden" variables that have been added automatically (for example, auto-generated variables used for the x-axis in graph plotting), and that have ID numbers greater than or equal to vmin. Never deletes the automatically generated constant (ID number 0).

dset :

pointer to dataset.

vmin :

do not drop variables with ID numbers less than this.

Returns :

0 on success, E_ALLOC on error.

dataset_drop_last_variables ()

int                 dataset_drop_last_variables         (DATASET *dset,
                                                         int delvars);

Deletes from the dataset the number delvars of variables that were added most recently (that have the highest ID numbers).

dset :

pointer to dataset.

delvars :

number of variables to be dropped.

Returns :

0 on success, E_ALLOC on error.

dataset_renumber_variable ()

int                 dataset_renumber_variable           (int v_old,
                                                         int v_new,
                                                         DATASET *dset);

Moves the variable that was originally at position v_old in the datset to position v_new, renumbering other variables as required.

v_old :

original ID number of variable.

v_new :

new ID number.

dset :

dataset information.

Returns :

0 on success, error code on error;

renumber_series_with_checks ()

int                 renumber_series_with_checks         (const char *s,
                                                         int fixmax,
                                                         DATASET *dset,
                                                         PRN *prn);


maybe_prune_dataset ()

int                 maybe_prune_dataset                 (DATASET **pdset,
                                                         void *p);


dataset_stack_variables ()

int                 dataset_stack_variables             (const char *vname,
                                                         const char *line,
                                                         DATASET *dset,
                                                         PRN *prn);

Really for internal use. Don't worry about it.

vname :

name for new variable, to be produced by stacking.

line :

instructions for stacking existing variables.

dset :

pointer to dataset.

prn :

printing apparatus.

Returns :

0 on success, non-zero code on error.

dataset_sort_by ()

int                 dataset_sort_by                     (DATASET *dset,
                                                         const int *list,
                                                         gretlopt opt);


dataset_set_matrix_name ()

int                 dataset_set_matrix_name             (DATASET *dset,
                                                         const char *name);


dataset_get_matrix_name ()

const char *        dataset_get_matrix_name             (const DATASET *dset);


dataset_period_label ()

const char *        dataset_period_label                (const DATASET *dset);


series_is_log ()

int                 series_is_log                       (const DATASET *dset,
                                                         int i,
                                                         char *parent);

Tries to determine if the variable with ID number i is the logarithm of some other variable.

dset :

dataset information.

i :

ID number of series.

parent :

location to which to write the name of the "parent" variable if any.

Returns :

1 if variable i appears to be a log, else 0.

series_set_discrete ()

void                series_set_discrete                 (DATASET *dset,
                                                         int i,
                                                         int s);

Mark a variable as being discrete or not.

dset :

pointer to data information struct.

i :

index number of series.

s :

non-zero to mark variable as discrete, zero to mark as not discrete.

series_record_display_name ()

int                 series_record_display_name          (DATASET *dset,
                                                         int i,
                                                         const char *s);


series_record_label ()

int                 series_record_label                 (DATASET *dset,
                                                         int i,
                                                         const char *s);


series_get_graph_name ()

const char *        series_get_graph_name               (const DATASET *dset,
                                                         int i);


get_resampling_seed ()

unsigned int        get_resampling_seed                 (void);


dataset_resample ()

int                 dataset_resample                    (DATASET *dset,
                                                         int n,
                                                         unsigned int seed);


dataset_op_from_string ()

int                 dataset_op_from_string              (const char *s);


modify_dataset ()

int                 modify_dataset                      (DATASET *dset,
                                                         int op,
                                                         const int *list,
                                                         const char *s,
                                                         PRN *prn);


dataset_get_structure ()

int                 dataset_get_structure               (const DATASET *dset);


panel_sample_size ()

int                 panel_sample_size                   (const DATASET *dset);

dset :

pointer to data information struct.

Returns :

the numbers of units/individuals in the current sample range, or 0 if the dataset is not a panel.

multi_unit_panel_sample ()

int                 multi_unit_panel_sample             (const DATASET *dset);

dset :

pointer to dataset.

Returns :

1 if the dataset is a panel and the current sample range includes two or more individuals, otherwise 0.

dataset_purge_missing_rows ()

int                 dataset_purge_missing_rows          (DATASET *dset);

Removes empty rows from the dataset -- that is, observations at which there are no non-missing values. This is intended for daily data only.

dset :

pointer to dataset.

Returns :

0 on success, non-zero code on error.

check_dataset_is_changed ()

int                 check_dataset_is_changed            (void);

Returns :

1 if the current dataset has been modified since the last call to this function, or since the library was initialized if this function has not yet been called; otherwise 0.

set_dataset_is_changed ()

void                set_dataset_is_changed              (void);

Sets the internal "dataset changed" flag to 1


dataset_set_time_series ()

int                 dataset_set_time_series             (DATASET *dset,
                                                         int pd,
                                                         int yr0,
                                                         int minor0);

Sets time-series properties on dset: frequency pd with starting observation yr0, minor0. If the data are annual (pd = 1) then minor0 is ignored.

dset :

pointer to dataset.

pd :

time series annual frequency (1 for annual, 4 for quarterly or 12 for monthly).

yr0 :

starting year.

minor0 :

starting "minor" period, 1-based (quarter or month).

Returns :

0 on success, non-zero code on error.

series_is_discrete ()

int                 series_is_discrete                  (const DATASET *dset,
                                                         int i);

dset :

pointer to dataset.

i :

index number of series.

Returns :

non-zero iff series i should be treated as discrete.

series_is_hidden ()

int                 series_is_hidden                    (const DATASET *dset,
                                                         int i);

dset :

pointer to dataset.

i :

index number of series.

Returns :

non-zero iff series i is hidden.

series_is_generated ()

int                 series_is_generated                 (const DATASET *dset,
                                                         int i);

dset :

pointer to dataset.

i :

index number of series.

Returns :

non-zero iff series i was generated using a formula or transformation function.

series_is_listarg ()

int                 series_is_listarg                   (const DATASET *dset,
                                                         int i);

dset :

pointer to dataset.

i :

index number of series.

Returns :

non-zero iff series i has been marked as belonging to a list argument to a function.

series_get_flags ()

int                 series_get_flags                    (DATASET *dset,
                                                         int i);

dset :

pointer to dataset.

i :

index number of series.

Returns :

the flags set series i.

series_set_flag ()

void                series_set_flag                     (DATASET *dset,
                                                         int i,
                                                         int flag);

Sets the given flag on series i.

dset :

pointer to dataset.

i :

index number of series.

flag :

flag to set.

series_unset_flag ()

void                series_unset_flag                   (DATASET *dset,
                                                         int i,
                                                         int flag);

Unsets the given flag on series i.

dset :

pointer to dataset.

i :

index number of series.

flag :

flag to remove.

series_zero_flags ()

void                series_zero_flags                   (DATASET *dset,
                                                         int i);

Sets flags on series i to zero.

dset :

pointer to dataset.

i :

index number of series.

series_get_label ()

const char *        series_get_label                    (const DATASET *dset,
                                                         int i);

dset :

pointer to dataset.

i :

index number of series.

Returns :

the descriptive label for series i.

series_get_display_name ()

const char *        series_get_display_name             (const DATASET *dset,
                                                         int i);

dset :

pointer to dataset.

i :

index number of series.

Returns :

the display name for series i.

series_get_parent_name ()

const char *        series_get_parent_name              (const DATASET *dset,
                                                         int i);

dset :

pointer to dataset.

i :

index number of series.

Returns :

the name of the "parent" of series i (e.g. if series i is a lag of some other series) or NULL if the series has no parent.

series_get_parent_id ()

int                 series_get_parent_id                (const DATASET *dset,
                                                         int i);

dset :

pointer to dataset.

i :

index number of series.

Returns :

the ID number of the "parent" of series i (e.g. if series i is a lag of some other series) or -1 if the series has no parent.

series_get_compact_method ()

int                 series_get_compact_method           (const DATASET *dset,
                                                         int i);

dset :

pointer to dataset.

i :

index number of series.

Returns :

the compaction method set for series i.

series_get_stack_level ()

int                 series_get_stack_level              (const DATASET *dset,
                                                         int i);

dset :

pointer to dataset.

i :

index number of series.

Returns :

the stack level of series i.

series_get_transform ()

int                 series_get_transform                (const DATASET *dset,
                                                         int i);


series_get_lag ()

int                 series_get_lag                      (const DATASET *dset,
                                                         int i);


series_set_label ()

void                series_set_label                    (DATASET *dset,
                                                         int i,
                                                         const char *s);


series_set_display_name ()

void                series_set_display_name             (DATASET *dset,
                                                         int i,
                                                         const char *s);


series_set_compact_method ()

void                series_set_compact_method           (DATASET *dset,
                                                         int i,
                                                         int method);


series_set_parent ()

void                series_set_parent                   (DATASET *dset,
                                                         int i,
                                                         const char *parent);


series_set_transform ()

void                series_set_transform                (DATASET *dset,
                                                         int i,
                                                         int transform);


series_set_lag ()

void                series_set_lag                      (DATASET *dset,
                                                         int i,
                                                         int lag);


series_set_stack_level ()

void                series_set_stack_level              (DATASET *dset,
                                                         int i,
                                                         int level);


series_increment_stack_level ()

void                series_increment_stack_level        (DATASET *dset,
                                                         int i);


series_decrement_stack_level ()

void                series_decrement_stack_level        (DATASET *dset,
                                                         int i);


series_attach_string_table ()

void                series_attach_string_table          (DATASET *dset,
                                                         int i,
                                                         void *ptr);


series_destroy_string_table ()

void                series_destroy_string_table         (DATASET *dset,
                                                         int i);


is_string_valued ()

int                 is_string_valued                    (const DATASET *dset,
                                                         int i);

dset :

pointer to dataset.

i :

index number of series.

Returns :

1 if series i has a table of string values (that is, a mapping from numerical values to associated string values), otherwise 0.

series_get_string_table ()

series_table *      series_get_string_table             (const DATASET *dset,
                                                         int i);

dset :

pointer to dataset.

i :

index number of series.

Returns :

the string table attched to series i or NULL if there is no such table.

series_get_string_for_obs ()

const char *        series_get_string_for_obs           (const DATASET *dset,
                                                         int i,
                                                         int t);

dset :

pointer to dataset.

i :

index number of series.

t :

0-based index of observation.

Returns :

the string associated with the numerical value of series i at observation t, or NULL if there is no such string.

series_get_string_for_value ()

const char *        series_get_string_for_value         (const DATASET *dset,
                                                         int i,
                                                         double val);

dset :

pointer to dataset.

i :

index number of series.

val :

the value to look up.

Returns :

the string associated with numerical value val of series i, or NULL if there is no such string.

series_set_string_val ()

int                 series_set_string_val               (DATASET *dset,
                                                         int i,
                                                         int t,
                                                         const char *s);

Attempts to set the string value for observation t of series i to s. This will fail if the series in question does not have an associated table of string values.

dset :

pointer to dataset.

i :

index number of series.

t :

0-based index of observation.

s :

the string value to set.

Returns :

0 on success, non-zero code on error.

series_decode_string ()

double              series_decode_string                (const DATASET *dset,
                                                         int i,
                                                         const char *s);

dset :

pointer to dataset.

i :

index number of series.

s :

string to decode.

Returns :

the numerical value associated with the string s for series i, or NADBL if there's no such value.

series_get_string_vals ()

const char **       series_get_string_vals              (const DATASET *dset,
                                                         int i,
                                                         int *n_strs);

dset :

pointer to dataset.

i :

index number of series.

n_strs :

location to receive the number of strings, or NULL.

Returns :

the array of strings associated with distinct numerical values of series i, or NULL if there's no such array. The returned array should not be modified in any way; copy the strings first if you need to modify them.

steal_string_table ()

int                 steal_string_table                  (DATASET *l_dset,
                                                         int lvar,
                                                         DATASET *r_dset,
                                                         int rvar);

Detaches the string table from rvar in r_dset and attaches it to lvar in l_dset,

l_dset :

pointer to recipient dataset.

lvar :

index number of target series.

r_dset :

pointer to donor dataset.

rvar :

index number of source series.

Returns :

0 on success, non-zero code on error.

set_panel_groups_name ()

int                 set_panel_groups_name               (DATASET *dset,
                                                         const char *vname);


get_panel_group_names ()

char const **       get_panel_group_names               (DATASET *dset);


panel_group_names_ok ()

int                 panel_group_names_ok                (const DATASET *dset);


panel_group_names_varname ()

const char *        panel_group_names_varname           (const DATASET *dset);


is_panel_group_names_series ()

int                 is_panel_group_names_series         (const DATASET *dset,
                                                         int v);


series_table

typedef struct _series_table series_table;