dataset

dataset

Functions

#define dataset_is_cross_section()
#define dataset_is_time_series()
#define dataset_is_seasonal()
#define custom_time_series()
#define dataset_is_daily()
#define dataset_is_incomplete_daily()
#define dataset_is_weekly()
#define dataset_is_hourly()
#define dataset_is_decennial()
#define dated_daily_data()
#define dated_seven_day_data()
#define dated_weekly_data()
#define calendar_data()
#define quarterly_or_monthly()
#define annual_data()
#define decennial_data()
#define dataset_is_panel()
#define dataset_is_seasonal_panel()
#define dataset_has_markers()
#define dataset_has_panel_time()
#define sample_size()
#define dset_get_data()
#define dset_set_data()
void free_Z ()
DATASET * datainfo_new ()
void datainfo_init ()
DATASET * create_new_dataset ()
DATASET * create_auxiliary_dataset ()
void destroy_dataset ()
void clear_datainfo ()
int allocate_Z ()
int dataset_allocate_varnames ()
int dataset_allocate_obs_markers ()
void dataset_destroy_obs_markers ()
void dataset_obs_info_default ()
void copy_dataset_obs_info ()
void copy_varinfo ()
int shrink_varinfo ()
void set_sorted_markers ()
void dataset_set_regular_markers ()
int start_new_Z ()
int is_trend_variable ()
int is_periodic_dummy ()
int dataset_add_observations ()
int dataset_drop_observations ()
int dataset_shrink_obs_range ()
int dataset_add_series ()
int dataset_add_NA_series ()
int dataset_add_allocated_series ()
int dataset_add_series_as ()
int dataset_copy_series_as ()
int overwrite_err ()
int series_is_parent ()
int dataset_replace_series ()
int dataset_replace_series_data ()
int dataset_rename_series ()
int dataset_drop_listed_variables ()
int dataset_drop_variable ()
int dataset_destroy_hidden_variables ()
int dataset_drop_last_variables ()
int dataset_renumber_variable ()
int renumber_series_with_checks ()
int maybe_prune_dataset ()
int build_stacked_series ()
int dataset_sort_by ()
int dataset_set_matrix_name ()
const char * dataset_get_matrix_name ()
const char * dataset_period_label ()
const char * dataset_get_mapfile ()
void dataset_set_mapfile ()
int series_is_log ()
void series_set_discrete ()
int series_record_display_name ()
int series_record_label ()
const char * series_get_graph_name ()
unsigned int get_resampling_seed ()
int dataset_resample ()
int dataset_op_from_string ()
int modify_dataset ()
int dataset_get_structure ()
int panel_sample_size ()
int multi_unit_panel_sample ()
int dataset_purge_missing_rows ()
int check_dataset_is_changed ()
void set_dataset_is_changed ()
void dataset_clear_sample_record ()
int dataset_set_time_series ()
int series_is_discrete ()
int series_is_hidden ()
int series_is_generated ()
int series_is_listarg ()
int series_is_coded ()
int series_is_integer_valued ()
VarFlags series_get_flags ()
void series_set_flag ()
void series_unset_flag ()
void series_zero_flags ()
const char * series_get_label ()
const char * series_get_display_name ()
const char * series_get_parent_name ()
int series_get_parent_id ()
int series_get_compact_method ()
int series_get_stack_level ()
int series_get_transform ()
int series_get_lag ()
int series_get_string_width ()
void series_set_mtime ()
gint64 series_get_mtime ()
void series_set_label ()
void series_set_display_name ()
void series_set_compact_method ()
void series_set_parent ()
void series_set_transform ()
void series_delete_metadata ()
void series_set_lag ()
void series_set_stack_level ()
void series_increment_stack_level ()
void series_decrement_stack_level ()
void series_ensure_level_zero ()
void series_attach_string_table ()
void series_destroy_string_table ()
int is_string_valued ()
series_table * series_get_string_table ()
const char * series_get_string_for_obs ()
const char * series_get_string_for_value ()
int series_set_string_val ()
int string_series_assign_value ()
int series_set_string_vals ()
int series_set_string_vals_direct ()
int series_recode_strings ()
double series_decode_string ()
char ** series_get_string_vals ()
int steal_string_table ()
int merge_string_tables ()
int set_panel_groups_name ()
const char * get_panel_group_name ()
int panel_group_names_ok ()
const char * panel_group_names_varname ()
int is_panel_group_names_series ()
series_table * get_panel_group_table ()
int is_dataset_series ()
int postprocess_daily_data ()
int series_get_midas_period ()
void series_set_midas_period ()
int series_get_midas_freq ()
int series_set_midas_freq ()
int series_is_midas_anchor ()
void series_set_midas_anchor ()
int series_get_orig_pd ()
void series_set_orig_pd ()
void series_unset_orig_pd ()
gretl_bundle * series_info_bundle ()
gretl_matrix * list_info_matrix ()
gretl_bundle * get_current_map ()

Types and Values

Description

Functions

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).

Parameters

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).

Parameters

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).

Parameters

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).

Parameters

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).

Parameters

p

pointer to data information struct.

 

dataset_is_incomplete_daily()

#define             dataset_is_incomplete_daily(p)

Attempt to determine whether a dataset contains daily on an incomplete calendar (1) or not (0).

Parameters

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).

Parameters

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).

Parameters

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).

Parameters

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).

Parameters

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).

Parameters

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).

Parameters

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).

Parameters

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).

Parameters

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).

Parameters

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).

Parameters

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).

Parameters

p

pointer to data information struct.

 

dataset_is_seasonal_panel()

#define             dataset_is_seasonal_panel(p)

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

Parameters

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).

Parameters

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).

Parameters

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.

Parameters

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 .

Parameters

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 .

Parameters

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.

Parameters

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().

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

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).

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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 .

Parameters

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 .

Parameters

targ

pointer to target dataset.

 

src

pointer to source dataset.

 

copy_varinfo ()

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

Copies relevant information from src to targ .

Parameters

targ

target to which to copy.

 

src

source to copy from.

 

shrink_varinfo ()

int
shrink_varinfo (DATASET *dset,
                int nv);

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).

Parameters

dset

pointer to dataset.

 

opt

if includes OPT_R we're sub-sampling from a full data set; if includes OPT_P, do not null out dset->S and markers.

 

Returns

0 on successful completion, non-zero on error.


is_trend_variable ()

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

Parameters

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);

Parameters

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.

Parameters

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; use OPT_T to extend in the time dimension in the case of panel data.

 

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.

Parameters

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 .

Parameters

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.

Parameters

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,
                       int newvars);

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

Parameters

dset

pointer to dataset.

 

newvars

number of series to add.

 

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.

Parameters

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.

Parameters

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.

Parameters

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);

Parameters

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.

Parameters

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 in x to dset->Z[v ].

 

Returns

0 on success, non-zero on error.


dataset_replace_series_data ()

int
dataset_replace_series_data (DATASET *dset,
                             int v,
                             const double *x,
                             int t1,
                             int t2,
                             const char *descrip);

Replaces the description and numerical content of series v over the given sample range, with the information provided.

Parameters

dset

pointer to dataset.

 

v

ID number of the series to be modified.

 

x

replacement values.

 

t1

start of sample range.

 

t2

end of sample range.

 

descrip

replacement description.

 

Returns

0 on success, non-zero on error.


dataset_rename_series ()

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

Parameters

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 series given in list from the dataset. Remaining series may have their ID numbers changed as a consequence. If renumber is not NULL, this location receives 1 in case series have been renumbered, 0 otherwise.

Parameters

list

list of series 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.

Parameters

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).

Parameters

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).

Parameters

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.

Parameters

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 int *list,
                             const char *param,
                             int fixmax,
                             DATASET *dset,
                             PRN *prn);

maybe_prune_dataset ()

int
maybe_prune_dataset (DATASET **pdset,
                     gretl_string_table *st);

build_stacked_series ()

int
build_stacked_series (double **pstack,
                      int *list,
                      int length,
                      int offset,
                      DATASET *dset);

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

Parameters

pstack

location for returning stacked series.

 

list

list of series to be stacked.

 

length

number of observations to use per input series.

 

offset

offset at which to start drawing observations.

 

dset

pointer to dataset.

 

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);

dataset_get_mapfile ()

const char *
dataset_get_mapfile (const DATASET *dset);

dataset_set_mapfile ()

void
dataset_set_mapfile (DATASET *dset,
                     const char *fname);

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.

Parameters

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.

Parameters

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,
                gretlopt opt,
                PRN *prn);

dataset_get_structure ()

int
dataset_get_structure (const DATASET *dset);

panel_sample_size ()

int
panel_sample_size (const DATASET *dset);

Parameters

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);

Parameters

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 dated daily data only.

Parameters

dset

pointer to dataset.

 

Returns

0 on success, non-zero code on error.


check_dataset_is_changed ()

int
check_dataset_is_changed (DATASET *dset);

Parameters

dset

dataset to check.

 

Returns

1 if dset has been modified since the last call to this function.


set_dataset_is_changed ()

void
set_dataset_is_changed (DATASET *dset,
                        int s);

Sets the internal boolean "changed" flag to s .

Parameters

dset

dataset.

 

s

1 or 0.

 

dataset_clear_sample_record ()

void
dataset_clear_sample_record (DATASET *dset);

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.

Parameters

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);

Parameters

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);

Parameters

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);

Parameters

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,
                   const char **lname);

Parameters

dset

pointer to dataset.

 

i

index number of series.

 

lname

location to receive list name, or NULL.

 

Returns

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


series_is_coded ()

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

Parameters

dset

pointer to dataset.

 

i

index number of series.

 

Returns

non-zero iff series i has been marked as "coded", meaning that its numerical values represent an arbitrary encoding of qualitative characteristics.


series_is_integer_valued ()

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

Parameters

dset

pointer to dataset.

 

i

index number of series.

 

Returns

non-zero iff all values in series i are representable as integers (ignoring missing values).


series_get_flags ()

VarFlags
series_get_flags (const DATASET *dset,
                  int i);

Parameters

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,
                 VarFlags flag);

Sets the given flag on series i .

Parameters

dset

pointer to dataset.

 

i

index number of series.

 

flag

flag to set.

 

series_unset_flag ()

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

Unsets the given flag on series i .

Parameters

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.

Parameters

dset

pointer to dataset.

 

i

index number of series.

 

series_get_label ()

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

Parameters

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);

Parameters

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);

Parameters

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);

Parameters

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);

Parameters

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);

Parameters

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_get_string_width ()

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

Parameters

dset

pointer to dataset.

 

i

index number of series.

 

Returns

the maximum of (a) the number of characters in the name of series i and (b) the number of bytes in the longest "string value" attached to series i , if applicable; or 0 if i is not a valid series index.


series_set_mtime ()

void
series_set_mtime (DATASET *dset,
                  int i);

series_get_mtime ()

gint64
series_get_mtime (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_delete_metadata ()

void
series_delete_metadata (DATASET *dset,
                        int i);

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_ensure_level_zero ()

void
series_ensure_level_zero (DATASET *dset);

series_attach_string_table ()

void
series_attach_string_table (DATASET *dset,
                            int i,
                            series_table *st);

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);

Parameters

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);

Parameters

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);

Parameters

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. Note that NULL will be returned if the observation is missing.


series_get_string_for_value ()

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

Parameters

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.

Parameters

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.


string_series_assign_value ()

int
string_series_assign_value (DATASET *dset,
                            int i,
                            int t,
                            double x);

Attempts to set the value for observation t of series i to x . This will fail if the x falls outside of the range of values supported by the string table for the series.

Parameters

dset

pointer to dataset.

 

i

index number of string-valued series.

 

t

0-based index of observation.

 

x

the numeric value to set.

 

Returns

0 on success, non-zero code on error.


series_set_string_vals ()

int
series_set_string_vals (DATASET *dset,
                        int i,
                        gretl_array *a);

series_set_string_vals_direct ()

int
series_set_string_vals_direct (DATASET *dset,
                               int i,
                               char **S,
                               int ns);

series_recode_strings ()

int
series_recode_strings (DATASET *dset,
                       int v,
                       gretlopt opt,
                       int *changed);

This function "trims" the array of string values associated with series v so that it contains no redundant elements -- that is, values of which there is no instance in the current sample -- and resets the numeric codes for the strings if necessary.

By default the original "series_table" attached to series v is destroyed, but if opt contains OPT_P it is replaced but not freed; this make sense only if another pointer to the original table exists.

If it happens that the current sample contains instances of all the strings in the full dataset, this function will not actually make any changes to dset . The changed argument provides a means of determining whether any change has been made.

Parameters

dset

pointer to dataset.

 

v

index number of target string-valued series.

 

opt

may contain OPT_P (see below).

 

changed

location to receive "changed" feedback, or NULL.

 

Returns

0 on success, non-zero code on error.


series_decode_string ()

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

Parameters

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 ()

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

Parameters

dset

pointer to dataset.

 

i

index number of series.

 

n_strs

location to receive the number of strings, or NULL.

 

subsample

non-zero to restrict to current sample range.

 

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 ,

Parameters

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.


merge_string_tables ()

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

Translates the encoding of the string-values of series rvar in r_dset to that of series lvar in l_dset , adding extra strings as needed.

Parameters

l_dset

pointer to current dataset.

 

lvar

index number of target series.

 

r_dset

pointer to dataset to be appended.

 

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_name ()

const char *
get_panel_group_name (const DATASET *dset,
                      int obs);

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);

get_panel_group_table ()

series_table *
get_panel_group_table (const DATASET *dset,
                       int maxlen,
                       int *pv);

is_dataset_series ()

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

postprocess_daily_data ()

int
postprocess_daily_data (DATASET *dset,
                        const int *list);

series_get_midas_period ()

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

series_set_midas_period ()

void
series_set_midas_period (const DATASET *dset,
                         int i,
                         int period);

series_get_midas_freq ()

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

series_set_midas_freq ()

int
series_set_midas_freq (const DATASET *dset,
                       int i,
                       int freq);

series_is_midas_anchor ()

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

series_set_midas_anchor ()

void
series_set_midas_anchor (const DATASET *dset,
                         int i);

series_get_orig_pd ()

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

series_set_orig_pd ()

void
series_set_orig_pd (const DATASET *dset,
                    int i,
                    int pd);

series_unset_orig_pd ()

void
series_unset_orig_pd (const DATASET *dset,
                      int i);

series_info_bundle ()

gretl_bundle *
series_info_bundle (const DATASET *dset,
                    int i,
                    int *err);

list_info_matrix ()

gretl_matrix *
list_info_matrix (const int *list,
                  const DATASET *dset,
                  gretlopt opt,
                  int *err);

get_current_map ()

gretl_bundle *
get_current_map (const DATASET *dset,
                 const int *list,
                 int *err);

Types and Values

enum DatasetMarkerType

Members

NO_MARKERS

   

REGULAR_MARKERS

   

DAILY_DATE_STRINGS

   

enum VarFlags

Members

VAR_DISCRETE

   

VAR_HIDDEN

   

VAR_GENERATED

   

VAR_LISTARG

   

VAR_TIMECOL

   

VAR_HFANCHOR

   

VAR_CODED

   

enum DatasetOp

Members

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

   

DS_PAD_DAILY

   

DS_UNPAD_DAILY

   

enum DataCopyFlag

Members

DS_COPY_VALUES

   

DS_GRAB_VALUES

   

enum 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.

Members

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_SPREAD

spread out into multiple series

 

COMPACT_MAX

sentinel value

 

series_table

typedef struct series_table_ series_table;