xtdata specification

This draft is about the xtdata pseudo-class that is defined within the qogdata package. The pseudo-class is defined by an attribute carried by data frames. If that convention proves useful through enough methods, it could be turned into a genuine class.

xt specification

The current xtdata specification is an object attribute that has been tested on data frames and might also work on data tables and objects of other classes. It aims at providing the user with some of the characteristics of the xt Stata commands.

The xtdata specification should serve users with panel data, typically cross-sectional time series of unique (un)balanced country-year observations. More complex time series are better handled by the zoo or xts packages, and other options exist for survey data.

At this early stage of development, xtdata is coded as a data frame attribute, not as a proper S3 or S4 class. Please feel free to suggest making it so in the Issues section, and I'' consider it the main goal of version 1.0 before submitting it to CRAN.

xtdata syntax

The xtdata attribute passed to data frames in the qogdata package contains a list of panel data attributes described in the documentation of the xtset function (required parameters are in bold):

• data, a character vector of identifier variable names, in the following order:
  1. unique identifier
  2. time period identifier
  3. alternative identifier (short)
  4. alternative identifier (long)
  5. any other identifier
  6. ...
• spec, a character vector that matches variable names with their formats
  1. format of unique identifier
  2. format of time period
  3. format of alternative identifier (short)
  4. format of alternative identifier (long)
  5. any other format for other identifier
  6. ...
• type, a character vector that defines the type of panel data
  1. primary type of panel data
  2. secondary type of panel data
  3. ...
• name, a character vector that defines a short description of the panel data
  1. primary name
  2. secondary name
  3. ...
• url, a character vector that defines a URI locator (a website address) to the panel
  1. primary URI
  2. secondary URI
  3. ...

The specification is internally set with xtset, accessed with xt and tested with xtdata (returns TRUE if required elements exist). The name and url are data cosmetics. To check for the presence of xtdata attributes, use !is.null(xt(data)$type).

Applications

In the qogdata package, this specification is used on QOG datasets to declare the type of data as country and maps the ccode, ccodealp and cname variables to their countrycode formats, iso3n, iso3c and country.name. It also cites the data source in name and url.

Similar specifications are passed to all datasets downloaded by get methods (currently: get_wdi, get_uds and get_gwpt). This allows to pass any of them to xtmerge to perform a safe merge of country-year observations. Any other dataset can carry an xtdata attribute.

As an example of how that specification can further be put to use, the xtmerge function calls the xtcountry function to use countrycode against unique and alternative identifiers of a data set, in order to find the largest number of ISO-3N country code matches in a country-level dataset.

The xtsubset and xtsample functions subset or sample from a data frame while preserving its xtdata attribute. The xtdes function returns its characteristics and T distribution.

Extensions

The time period stored in xt(data)$data[2] is currently used only to check that both datasets passed to xtmerge have identical time formats in xt(data)$spec[2], but only because testing the package with country-year observations provided little reason to use it any other way.

The xtdata specification should be extensible enough to deal with, for instance, quarterly data for FIPS units, or time series of NUTS-2 regional data. Feel free to declare one or more types of xtdata for a dataset: country and its helper functions for countrycode are only one example of what should be doable.

The next extension will use region and nuts attributes with the xtregion function to prepare data out of the QOG EU Regions and Eurostat datasets, which sometimes include both country and region data and use other time periods than year (most often quarter).

xtplots

• xtmissing, xtline and xtmap are companion plot functions:
  • xtmissing plots panel data missing values
  • xtmap plots one or more years of country data on world maps (see below)
  • xtplot plots one or more years of data in other ways

The xtmap function uses the t argument to apply panel data transformations:

• if t is NULL, no time period is used
• if t is equal to single number like 1945, a single time period is used
• if t is NULL and xt(data$)spec[2] exists, the maximum time period is used
• if t is a range like 1945:1950, a time period method is used

The xtplot method supports similar transformations:

• if t is NULL, dot or bar plot of values
• if t is 1945, dot or bar plot of values for period
• if t is NULL and xt(data$)spec[2] exists, the entire time range is used
• if t is 1945:1955, plot line/point/step/area/smooth/bar geoms for period

DRAFT NOTES:

• code t for xtmap:
  • min, max, mean, median, mode, sd, range, std, std01
  • quant.cut (externalize to utils and compare to questionr:quant.cut)
  • diff (average change), percent-diff (average rate of change)
• code t for xtplot: