Haver_introduction {Haver} | R Documentation

## Introduction to the Haver Package

### Description

This document provides an introductory overview of functions that allow you to access data stored in Haver Analytics databases from within R. It also defines terminology and conventions that are relevant for the entire documentation of the package.

The objects and functions of the Haver package are designed to let you conveniently and efficiently access data and metadata of Haver Analytics databases. This is their only task: They are not designed for data analysis. Once you are past the query stage and you want to do data analysis, convert the data objects created by database queries into R objects that are more suitable for this purpose. To do so, you can use coercion functions provided by the Haver package.

### Getting to Know the Haver Package Quickly

The basic operations of Haver data queries are easy and can be learned quickly. In a nutshell, the functions that access Haver Analytics databases are called `haver.data` and `haver.metadata`. Both take as arguments specifications for databases and time series codes to be retrieved. The data and metadata are returned in objects `HaverData` and `HaverMetaData`, respectively. Data and metadata are linked closely: A time series retrieval results in a `HaverData` object and this object internally contains the corresponding metadata, which can be accessed at any time. Conversely, a `HaverMetaData` object resulting from a metadata query can be used as an input argument to `haver.data` in order to query the corresponding time series data.

This help entry and some other help entries for the Haver package are somewhat lengthy, but this is not because usage is complicated. Rather, they provide much detail that can be skipped by beginning users but that may become useful at a later stage.

If you want to get a very quick introduction, read (sub-)sections ‘Old and New Haver Functions’, ‘Where to Go from here’, and ‘Examples’ of this help entry, and do take note of the other section and subsection headings so you know where to look up information at a later point.

The other sections than the ones just mentioned define terminology and/or provide information for efficiently gaining a deeper understanding of the package. If you decide to only skim through them for now, we recommend that you do not postpone a more thorough reading for too long.

### Preliminaries

#### DLX, Access to Databases, Operating System

‘Haver’ is short for the company name Haver Analytics, whereas ‘DLX’ refers to a software bundle that is distributed by Haver Analytics (‘DLX’ is short for ‘Data Link Express’). DLX comprises all software components that update and provide access to Haver Analytics databases. For the practical purposes of this help file this distinction does not matter and you can read ‘Haver’ and ‘DLX’ interchangeably. This package uses the term ‘Haver’ mostly when referring to databases, series codes, etc., related to Haver Analytics or the DLX software.

Accessing Haver databases requires that you have access to Haver databases on a local or on a network drive. You do not need to have any Haver desktop client software installed.

The Haver package is only available on Windows operating systems.

#### Old and New Haver Functions

As you will see, the names of the featured set of functions provided by the Haver package start with ‘haver’. Previous versions of this package contained functions whose names started with ‘dlx’. To distinguish older from newer functions, help documents will refer to the old functions as the “legacy ‘dlx’ family of functions” and to the new functions as the “recommended ‘haver’ family of functions”.

As this terminology implies, usage of the legacy ‘dlx’ family of functions is discouraged since the recommended ‘haver’ family of functions provides improved functionality. However, the legacy ‘dlx’ family of functions is still available in the current Haver package for backward compatibility reasons. Any existing scripts based on these functions will continue to work without modification. If you are already familiar with the workings of the legacy ‘dlx’ family of functions you can jump to Haver_legacy which will tell you about the most important differences between the two function families.

Unless otherwise noted, any Haver help document that is not explicitly geared towards describing the legacy ‘dlx’ family of functions will solely be concerned with the recommended ‘haver’ family of functions. For example, the statements of the following section on conventions of functions and help files of the Haver package only apply to the recommended ‘haver’ family of functions, as do statements of all subsequent sections in this help file.

#### Conventions of Haver Functions and Objects and of Haver Help Files

##### Usage of Terms ‘code’, ‘symbol’, ‘variable’, etc.

Codes of Haver time series are referred to as series codes, Haver codes, or Haver series codes. The time series themselves are referred to as Haver series or Haver time series.

To unambiugously identify a Haver time series, you must indicate the series code and the database name. The term series code may or may not imply this full specification. If it should be stressed that a full specification is necessary, the word full is prepended to ‘Haver code’, ‘series code’, etc. If this is done using the form database name - colon - series code, the specification is said to be in database:seriescode format. The database:seriescode format within R corresponds to the seriescode@database format that is e.g. used in the DLX add-in for Excel. Conversely, if it should be stressed that a series code specification does NOT include the database name, the word regular is prepended to ‘Haver code’, ‘series code’, etc.

The following table summarizes this information, with examples of full series codes given in database:seriescode format.

term | example
Haver code, series code, Haver series code | gdp, usecon:gdp
full Haver code, full series code, etc. | usecon:gdp
regular Haver code, etc. | gdp

Side note: If a regular series code exists in two databases, it usually refers to the same concept, potentially with differences in frequencies (e.g. ‘daily:ffed’ and ‘weekly:ffed’). Cases where a regular series code exists in multiple databases and refers to different concepts are very rare.

The term ‘variable’ is mostly avoided since it can mean many different things (a variable of a statistical model, a variable within computer code, an R symbol, Haver codes, etc.).

‘variables’ of R code are called symbols or R symbols. For example, `x` and `y` of the expression
`> x <- y + 7`
are R symbols.

##### Casing

Arguments to Haver functions are not case-sensitive (if the argument is of type character). In particular, you can specify Haver series codes in upper case or lower case or any mixture thereof.

Function names of Haver functions are always lower case (e.g. `haver.data`). Names of objects of the Haver package are in ‘UpperCamelCase’, i.e. in lower case with the starting letter of a word capitalized (e.g. `HaverMetaData`).

Almost all symbols and field names returned by Haver functions are lower case. In particular, Haver series codes or database names returned by Haver functions are always lower case. The field names of a HaverMetaData object are also lower case (see `HaverMetaData`). The exception to the ‘return character values in lower case’ convention of Haver functions are the values of most fields of HaverMetaData objects.

##### Example Code Symbol Names

The most important objects of the Haver package are `HaverData` and `HaverMetaData` objects, to be described below and in other help files. Whenever an example R code statement in a help file assigns such an object to a symbol, symbols ‘hd’ and ‘hmd’ are used, possibly with suffixes that are easily understood within the context (‘hd_1’, ‘hd_2’, ‘hmd_d’, etc.). Objects of type `HaverErrorReport` are called ‘her’. Any other R symbols that are defined in example code start with ‘ex_’.

All of these symbols are available for interactive exploration after `example` concludes. Note that executing the ‘Examples’ section will overwrite any symbols with identical names in the global workspace. If you want to prevent this, use the `local=TRUE` option of `example`.

##### Date Format

Dates are always in the format yyyy-mm-dd. For example, 24 March 2014 is denoted 2014-03-24.

##### Missing Values

Missing values for time series data are frequently referred to as ‘NAs’. In data sets missing values are recorded as (numeric) NAs.

### DLX Direct: Accessing Databases Directly from a Haver Server

While this guide is mainly written in terms of DLX queries to local databases, the Haver package for R also integrates with DLX Direct, which is a Haver subscription service that enables you to connect to Haver Analytics servers for database access. Depending on your institution's DLX subscriptions, you may be able to access only one of the two services, or both.

In R you can switch between the two different modes of query with a single function call. If you would like to use DLX Direct in R, make sure to give `haver.direct` a thorough read.

### Reinstalling the Haver Package

If you want to uninstall the Haver package, simply issuing
`> remove.packages("Haver")`
may result in an incomplete deinstallation, which may cause problems for reinstalling the package (you may have to quit R and manually delete the remnants of the old installation). If the Haver package is attached to your R search path, be sure to issue
`> detach("package:Haver", unload=TRUE)`
before calling `remove.packages`.

### Preparatory Steps for R Code Examples

#### Example Databases

The Haver package comes with three example databases that are used frequently in the ‘Examples’ section of Haver help entries: ‘HAVERD’, ‘HAVERW’, and ‘HAVERMQA’. They contain daily, weekly, and monthly/quarterly/annual data, respectively. These databases are subsequently referred to as the ‘example databases’.

Do not use data contained in example databases for analysis. They are shipped for demonstration purposes only. The data contained in these databases is several years old.

The Haver databases that your institution subscribes to and that you can use in analysis are referred to as the ‘actual databases’ or ‘actual Haver databases’. Keep in mind that, while the example databases contain only between 3 and 161 series, actual Haver databases contain thousands or even hundreds of thousands of series.

In rare cases, help files will refer to series in actual databases. Such references are only made outside of ‘Examples’ sections.

#### Setting the Haver Database Path to Actual and Example Databases

Before Haver database queries can be executed the correct database directory path has to be set. This is done with `haver.path`. In most cases you will not have to do this as `haver.path` tries to set the correct path to the actual Haver databases automatically.

The path to the example databases is different than the path to the actual databases. `haver.path` provides a convenient syntax shortcut for setting the path to example databases and for restoring the path to the actual databases. This is done by the statements
`> haver.path("examples")`
`> haver.path("restore")`
which you will find at the beginning and at the end (respectively) of each ‘Examples’ section of Haver help entries. As an additional safeguard there is a statement
`> haver.path()`
at the very top of each ‘Examples’ section which displays the path setting that was in place before the ‘Examples’ section was entered.

Depending on the configuration of R and of DLX on your machine, it may occur that calling `haver.path("examples")` and `haver.path("restore")` does not work. In this case, executing the examples using `example` will not be possible. However, you can still set the path to the example databases manually and copy & paste statements from the ‘Examples’ sections to the R command prompt.

To set the path to the example databases manually, first take note of the path setting to the actual databases, which is displayed by
`> haver.path()`
Then, execute
`> haver.path(set=EXAMPLE_PATH)`
where `EXAMPLE_PATH` is the subdirectory ‘dat’ of the installation directory of the Haver package. For example, if you had installed the Haver package to ‘c:\r\r-3.0.2\library’, you would have to execute
`> haver.path(set="c:\\r\\r-3.0.2\\library\\Haver\\dat")`
Note the use of a double backslash as directory separator. Once you are done looking at the examples, manually set the path back to the actual Haver databases.

#### Turning DLX Direct Mode Off

Since the example databases reside on your local network, any example code must be executed with DLX Direct mode turned off:

    > haver.direct("off")

This statement is implicit in code examples. It is not shown explicitly. If you try to execute code examples with DLX Direct mode turned on, the example statements will fail.

### Where to Go from Here

First, read and/or execute the ‘Examples’ section below (to execute the examples, use the R function `example`). It provides introductory examples to give you a first idea on how to use functions of the Haver package.

You can then go on to a more detailed exposition of the functions `haver.metadata` and `haver.data`. The help files for the two functions contain a lot of detail, too much detail probably for a beginning Haver user. You absolutely do not have to read everything, but do take note of the (sub-) section headings in these help files so you know where to look up information at a later point. You should read the files thoroughly enough to be able to understand the ‘Examples’ sections of both files.

You can then examine the three objects involved and learn how to manipulate them: `HaverMetaData`, `HaverData`, and `HaverErrorReport`. Along the way, you will come across functions `haver.codelists`, `haver.datamd`, and `haver.setalias`.

Finally, Haver_advanced provides an extended real-world data query example with further illustrations of how you can use the Haver interface in practice.

If at any point you have trouble retrieving data because of path settings, look at `haver.path`.

The Haver package imposes artificial limits on the size of data queries. These limits may never become relevant for you. If they do, you can change the settings for these limits. Should a Haver routine notify you that a query is not possible because of query size limits, `haver.limits` provides information on the customization of query limits.

### Author(s)

Haver Analytics <tech@haver.com>

Maintainer: Haver Analytics <tech@haver.com>

### See Also

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

### Examples

    ## This section provides introductory examples.
    ## It's purpose is to give you an overview of the Haver package.
    ## Detailed explanations are skipped at this point.

    ## Display current path setting:
    haver.path()

    ## Set the database path to the directory of the example databases:
    haver.path("examples")

    ## This directory contains three databases: HAVERD, HAVERW, and HAVERMQA.
    ## Function 'haver.metadata' accesses metadata information of Haver databases.
    ## We use it here to get an overview of what is in the databases.
    haver.metadata(database="haverd")
    haver.metadata(database="haverw")

    ## Actual Haver Analytics databases have thousands or even hundreds of thousands
    ## of series. In such and other cases, assigning the output to a symbol
    ## is appropriate. As usual, this prevents printing:
    hmd_mqa <- haver.metadata(database="havermqa")

    ## Symbol 'hmd_mqa' now holds a HaverMetaData object.
    ## You can view its contents in the viewer:
    ## Not run:
    View(hmd_mqa)

    ## End(Not run)

    ## Let's pull in three exchange rate series from 'HAVERD'.
    ## 'haver.data' is the function to retrieve time series data.
    ## We specify a starting date in order to limit the output.
    hd_1 <- haver.data(codes=c("fxtwb", "fxtwm", "fxtwotp"),
                       database="haverd", start=as.Date("2012-02-15", format="%Y-%m-%d"))

    ## 'hd_1' is of class 'HaverData':
    hd_1

    ## The metadata has automatically been saved within this object.
    ## We can access it using function 'haver.datamd':
    haver.datamd(hd_1)

    ## Alternatively, we can assign the HaverMetaData object to a symbol
    ## and then customize the output:
    hmd_1 <- haver.datamd(hd_1)
    print(hmd_1, fields=c("code", "descriptor"), desc.length=60)

    ## We can pull in data from more than one database using the
    ## 'database:seriescode' format in the 'codes' argument. Note that in the
    ## following query the daily series gets aggregated to weekly frequency.
    ## The frequency of the resulting data set is weekly.
    hd_2 <- haver.data(codes=c("haverD:fxtwb", "haverW:farbn"),
                       start=as.Date("2012/01/01", format="%Y/%m/%d"))
    hd_2

    ## Next, we pull in data from the entire 'HAVERMQA' database. To do this,
    ## we use the HaverMetaData object hmd_mqa which we have created earlier
    ## and feed it into the data retrieval.
    ## Since the lowest frequency of the queried series is annual, series with higher
    ## frequencies get aggregated. 'haver.data' also informs us that two series
    ## cannot be aggregated. They get dropped from the query.
    hd_mqa  <- haver.data(codes=hmd_mqa)

    ## You can look at the data set in the viewer:
    ## Not run:
    View(hd_mqa)

    ## End(Not run)

    ## You can specify a higher frequency if you want, say, quarterly.
    ## Then 'haver.data' drops annual series from the query:
    hd_mqa2 <- haver.data(codes=hmd_mqa, freq="q")

    ## To summarize statistical information, or for plotting, you must convert
    ## the HaverData object to another object, for example, an R 'ts' object:
    library(stats)
    ex_ts <- as.ts(hd_mqa2)
    plot(ex_ts[,1:6])

    haver.path("restore")

[Package Haver version 3.2 Index]