haver.metadata {Haver} | R Documentation

## Access Haver Analytics Time Series Metadata

### Description

`haver.metadata` queries metadata information on time series contained in Haver Analytics databases. The information is returned either as a `HaverMetaData` object or as a `data.frame`.

This help entry assumes that you are familiar with Haver_introduction.

### Usage

    haver.metadata(codes, database, decode = TRUE, cbreak = 1000, histcodes = 'keep'
                   caldaily = FALSE, wecodes = 'keep')

### Arguments

`codes` | is either a character vector or it is an object that fulfills the conditions of `haver.hasfullcodes`. If a character vector is supplied, the elements can be regular series codes or additionally supply the database where the code resides, in which case the elements must be specified in database:seriescode format. Examples of character vector elements are ‘gdp’ and ‘usecon:gdp’. Haver series codes may also be supplied through an object that passes `haver.hasfullcodes`. The only difference of usage of the `codes` argument in comparison to `haver.data` is that it IS optional here (see section ‘Details’ below).
`database` | is a character string. This argument is optional and specifies a default Haver database (excluding the path to the database, and excluding any file extension). If this argument is omitted, all elements of ‘codes’ must be in database:seriescode format. Otherwise the function errors out.
`decode` | is a logical TRUE / FALSE. This option is rarely used. By default (`decode=TRUE`), metadata information that is numerically encoded will be translated to meaningful character strings. For example, internally the aggregation type ‘AVG’ (average) is encoded as ‘1’, and the default `decode=TRUE` will re-translate this into ‘AVG’.
`cbreak` | is an integer. This option is rarely needed and specifies the number of codes after which each C-level function of the Haver package checks for user interrupts. If you want to switch off checking for interrupts, specify a very large value, such as `cbreak=1e8`.
`histcodes` | is a string. Only matters for queries that a) are run on entire databases and b) contain daily and/or weekly series. One of ‘keep’ (default), ‘drop’, ‘sequential’, ‘nonsequential’, or any abbreviation thereof. ‘keep’ and ‘drop’ keep or drop historical component series in the database from the returned object. ‘sequential’ keeps only proper historical component series. ‘nonsequential’ keeps only codes that could be confused with historical component series. For more details, see section ‘Dealing with Historical Component Series when Querying Entire Databases’ below.
`caldaily` | is a logical TRUE / FALSE. If `TRUE`, calendar daily series receive a frequency value of ‘C’ (or ‘61’ under `decode=FALSE`). The default `caldaily=FALSE` shows calendar daily series as regular series with a frequency code of ‘D’.
`wecodes` | is a string. This argument is similar to `histcodes`. It only matters for queries that a) are run on entire databases and b) contain calendar daily series. One of ‘keep’ (default) or ‘drop’ (or any abbreviation thereof) with the implied actions of keeping or dropping weekend component series in the database from the output. For more details, see section ‘Calendar Daily Series and Their Weekend Component Series’ below.

### Details

Argument `codes` may be omitted if the argument `database` is supplied, in which case the request is interpreted as ‘all series from database database’. Note that this is not possible with `haver.data`.

There are three possible combinations of using arguments `codes` and `database`.

1. only supply `codes`. In this case all elements of `codes` have to be in database:seriescode format.

2. only supply `database`. This will retrieve metadata for all series contained in database.

3. supply both `codes` and `database`. Metadata for all elements of `codes` is queried. If an element of `codes` is not in database:seriescode format, the value of `database` will serve as the default database.

The order of series records within the returned object corresponds to the order of series in the input argument `codes`.

As is generally the case with Haver functions, (character) values of arguments supplied are not case-sensitive.

### Value

An object of class `HaverMetaData`. They contain various fields with information on series metadata. For a detailed description of these fields, see `HaverMetaData`.

In the case of invalid series code and/or database specifications, a `HaverErrorReport` is returned.

### Query Errors

As soon as one series code or one database specified in a query cannot be found, `haver.metadata` returns a `HaverErrorReport`. This object contains details on what went wrong with the query. The function `haver.codelists` enables you to get at lists of series codes that could not be found.

### Interrupting Execution

If you have specified a query that is taking a long time to conclude, you can cancel it in the usual way (ESC key).

### Dealing with Historical Component Series when Querying Entire Databases

There is an upper limit on the length of a Haver time series: It can span at most 2100 time periods (2100 business days, 2100 weeks, etc.). This corresponds to about 8 years of business daily data and 39 years of weekly data. The limit is not relevant for lower frequencies.

For many daily series and for some weekly series, this constraint is binding. Haver databases deal with this limit in the following way: If a series covers more than 2100 time periods, additional history can be stored in auxiliary series that have the same base code but also have sequence numbers 2-9 appended to it. For example, suppose that a database contains a daily series FXCAN that has 5000 observations. Then the database contains the base code FXCAN along with the historical component series FXCAN2 and FXCAN3. If such a set of series exists in a database and you query the time series data of the base code, all data history is automatically spliced together. That is to say, when executing a data query on FXCAN you never notice that the data is actually stored in separate series.

However, there is one instance when you actually may come across the existence of historical component series, and this is when you query all metadata of a database that contains long daily and/or long weekly series. In the example above, a metadata query on the full database would result in three separate entries in the HaverMetaData object that are related to FXCAN: It would have entries for codes FXCAN, FXCAN2, and FXCAN3. Option `histcodes='drop'` now allows you to skip historical component series in your query, so the entries for FXCAN2 and FXCAN3, which are rarely of any use, do not show up in the query result.

This technique will matter if a database contains many long daily series. For example, if you would like to query all data of Haver's DAILY database, which contains daily economic statistics for the US economy, you can issue

      hmd <- haver.metadata(database='daily', histcodes='drop')
      hd  <- haver.data(hmd)

For databases like DAILY, this may reduce the number of series - and consequently the memory requirements and execution speed of the query - by 50-70

### Calendar Daily Series and Their Weekend Component Series

The calendar daily frequency records seven data points per week, as opposed to the regular Haver daily frequency, which is based on five observations per week.

IMPORTANT The default is to not show calendar daily series separately, that is, in the returned HaverMetaData object their frequency is, by default, indicated as ‘D’, as it is for regular daily series. If you want to identify calendar daily series, you must explicitly specify the argument `caldaily=TRUE`. Then their frequency is shown as ‘C’.

The calendar daily frequency is implemented using a technique similar to the one used for historical component series described in the previous section: A (5-day) daily series code is combined with two weekly series codes that hold data for Saturday and Sunday. The two weekly series' codes correspond to the code of the daily series with a 0 and 1 appended (Saturday and Sunday data, respectively). These series are referred to as 'weekend component series'. When querying an entire database, the argument `wecodes` works very similar as argument `histcodes` (see the previous section). Specifying `wecodes='drop'` will prevent weekend component series from appearing in the returned HaverMetaData object.

### Time Zone Settings

The datetimemod field of the HaverMetaData object records the time of the last series update by Haver Analytics. When you run a metadata query, this information is adjusted in accordance with the time zone setting of your R session. If your time zone is not set correctly, issuing a metadata query will result in a warning. Below is an example of how you set a valid time zone:

      options(tz="Europe/Berlin")
      Sys.setenv(TZ="Europe/Berlin")

For a list of valid time zones that you can use, type

      OlsonNames()

After you set a time zone, the warning message no longer appears.

### See Also

See Haver_package for all help entries related to the Haver package.

### Examples

    haver.path()
    haver.path("examples")

    ## The following statements illustrate how you can specify series codes and
    ## database names. Argument usage of 'codes' and 'database' is identical to
    ## the statements of the 'Examples' section in 'haver.data'.
    ## All queries below are equivalent.
    haver.metadata(cod=c(       "fxtwb",        "fxtwm",        "fxtwotp"), dat="haverd"  )
    haver.metadata(cod=c(       "FXTWB",        "FXTWM",        "FXTWOTP"), dat="HAVERD"  )
    haver.metadata(cod=c("haverd:fxtwb",        "fxtwm",        "fxtwotp"), dat="haverd"  )
    haver.metadata(cod=c("haverd:fxtwb", "haverd:fxtwm", "haverd:fxtwotp")                )
    haver.metadata(cod=c("haverd:fxtwb", "haverd:fxtwm", "haverd:fxtwotp"), dat="havermqa")

    ## Querying codes from multiple databases is possible:
    hmd_1 <- haver.metadata( cod=c("haverD:fxtwb", "haverW:lic", "fcm1") , dat="haverMQA")
    hmd_1

    ## Querying all codes of a database is not possible with 'haver.data',
    ## but it is with 'haver.metadata':
    hmd_2 <- haver.metadata( dat="haverd" )
    hmd_2

    ## Note that when querying an entire database, you must name the
    ## argument 'database' explicitly.
    ## Not run:
    haver.metadata("haverd")

    ## End(Not run)

    ## The statement above produces an error since the first argument of
    ## 'haver.metadata' is 'codes', but we meant to specify 'database',
    ## so to accomplish what we want to do we have to run:
    haver.metadata(database="haverd")

    ## When setting the argument 'decode=FALSE', some metadata remain encoded as
    ## numeric values. In rare cases it may be helpful to look at these numeric
    ## values. For example:
    hmd_w <- haver.metadata(database="haverw", decode=FALSE)
    table(hmd_w[["frequency"]])

    ## shows a frequency count of the series in 'HAVERW'. 9 of those series have
    ## a release day-of-week of 53, 12 series of 56. These values correspond to
    ## Wednesday and Saturday, respectively (see 'HaverMetaData'). This can
    ## be confirmed by looking at one of the fields 'startdate' or 'enddate':
    table(weekdays(hmd_w[["enddate"]]))

    haver.path("restore")

[Package Haver version 3.2 Index]