HaverMetaData {Haver} | R Documentation

## HaverMetaData Object

### Description

A `HaverMetaData` object is the return type of `haver.metadata`.

A second use of `HaverMetaData` objects is to use them as input for `haver.data` (see Haver_advanced).

If you have not done so yet, have a look at `haver.metadata` before reading this help entry.

### Usage

    ## S3 method for class 'HaverMetaData'
    print(x, fields.disp = DEFAULT_FIELDS, desc.length = 30)
    ## S3 method for class 'HaverMetaData'
    dim(x)
    ## S3 method for class 'HaverMetaData'
    x[i]
    ## S3 method for class 'HaverMetaData'
    x[[j]]
    ## S3 method for class 'HaverMetaData'
    as.data.frame(x)

### Arguments

`x` | a `HaverMetaData` object
`fields.disp` | a character vector whose elements specify metadata fields to display. For a list of metadata fields and a description of their contents, see section ‘Metadata Fields’ below. In the syntax list above, `DEFAULT_FIELDS` stands for `c("database", "code", "startdate",` `"enddate", "frequency", "numobs", "descriptor")` Use `fields.disp=NA` to display all fields. Use `fields.disp=NULL` or `fields.disp=""` to only display summary information on the data set and to suppress printing of individual records.
`desc.length` | a numeric scalar in the range 2-80. You can also use `desc.length=NA` to set it to the maximum allowed length of 80.
`i` | a numeric or a logical index vector. If logical, the vector is subject to R's vector recycling rule.
`j` | a numeric scalar or string. If numeric, it must be in the range 1 to 18. If string, it must be a valid `HaverMetaData` field.

### Details

`print` is an alternative to `View`. Using `print` you can print metadata information or a subset thereof to the R output window. The print method takes two arguments in addition to the object to be printed. The first one specifies the field list to be printed (see the field list table below). The second one specifies how many characters of the series descriptors should be printed if this field is among the fields to be displayed. Haver metadata field names can be abbreviated, as long as the abbreviation uniquely implies a metadata field name. Note that such abbreviations are not allowed in `[[` indexing operations. See section ‘Examples’ below for illustrations.

A quick way to determine how many code records are contained within a `HaverMetaData` object is
`dim(hmd)[1]`

Single bracket `"["` indexing is restricted to row operations and therefore takes only one argument. Indexing operations allowed are very similar to the ones allowed by `[.data.frame`. One difference is that `HaverMetaData` indexing may be done with or without a trailing ‘comma’:
`> hmd[1:3, ]`
`> hmd[1:3]`
mean the same thing. With `data.frame`s,
`> df[1:3, ]`
`> df[1:3]`
are different operations. The row operations that we are considering correspond to the first statement on `data.frame`s.

Single bracket indexing using character index vectors is not allowed for `HaverMetaData` objects. If an indexing operation removes all rows, `NULL` is returned. If an indexing operation results in rows that contain `NA`s (e.g. by out-of-bounds indexes) an error is issued.

Double bracket `"[["` indexing is restricted to column operations.

Indexing replacement operations (`"[<-"` and `"[[<-"`) are not allowed.

A `HaverMetaData` object can be coerced into a `data.frame`. This is useful when you want to perform more elaborate indexing operations on the metadata than allowed by the `HaverMetaData` object. In addition, you have to coerce to `data.frame`s if you want to append the contents of two or more `HaverMetaData` objects (see `rbind`). Note that you can use the resulting `data.frame` as an input to `haver.data` (an illustration of this is contained in the ‘Examples’ section of the `haver.data` help entry).

You can assign aliases to Haver codes of the `HaverMetaData` object if you prefer to use your own series names in your analysis. Use `haver.setalias` to do this.

### Value

`print` prints the metadata and returns the `HaverMetaData` object (invisibly).

`dim` returns a numeric vector with two elements indicating the number of code records and the number of metadata fields. The latter is a fixed number for all `HaverMetaData` objects.

`[.HaverMetaData` returns a `HaverMetaData` object or `NULL`.

`[[.HaverMetaData` returns a vector whose type is either character, numeric, Date, or POSIXct.

`as.data.frame` returns a `data.frame`.

### Metadata Fields

A HaverMetaData object contains 18 pieces of information for each series code. These pieces of information are referred to as ‘fields’ in the following.

Side note: In the Haver Analytics data browser ‘DLXVG3’, a subset of these fields is called ‘series parameters’ and can be accessed from the ‘Tools’ menu or through the ‘Alt+F10’ keyboard shortcut.

field name | type/class | description
database | character | the database name (excluding the path to the database)
code | character | the Haver series code
alias | character | a user-defined series code
startdate | Date | an R Date object corresponding to the
|  | last day of the series starting period
enddate | Date | an R Date object corresponding to the
|  | last day of the series ending period
numobs | numeric | number of periods between (and including) startdate and enddate
frequency | char/numeric | the frequency code; one of C, D, W, M, Q, A
|  | (daily, weekly, monthly, quarterly, annual)
datetimemod | POSIXct | a POSIXct object indicating the time the series was last modified
magnitude | numeric | the magnitude of the series
|  | (e.g. 3 for series expressed in thousands)
decprecision | numeric | the decimal precision (number of digits after the decimal point)
diftype | numeric | 0/1 value: 1 if data can contain or contain
|  | non-positive values, 0 otherwise
aggtype | char/numeric | the aggregation type; one of AVG, SUM, EOP, UDF, NST
|  | (average, sum, end-of-period, undefined, not set)
datatype | character | one of US$, LocCur, US$/LC, LC/US$, INDEX, Units
|  | (where LocCur and LC stand for local currency)
geography1 | character | primary Haver geography code
geography2 | character | secondary Haver geography code
descriptor | character | the series description (label)
shortsource | character | the abbreviated name of the time series publisher
longsource | character | the full name of the time series publisher

When the `HaverMetaData` object is returned by `haver.metadata`, field ‘alias’ does not contain any entries since it is not part of the metadata provided by Haver Analytics. Rather, this field allocates space for storing user-defined series code names (aliases). For details, see `haver.setalias`.

Field ‘aggtype’ controls the temporal aggregation arithmetics for a particular series. `haver.data` performs temporal aggregation according to the values of this field. In some DLX software components it is possible to apply a custom setting to the aggregation type for a particular series. Within R, however, this functionality does not exist. Temporal aggregation is always performed according to the ‘aggtype’ field entry of a series.

Field ‘diftype’ is of limited interest since it is used internally in DLX software only. It controls the kinds of series transformations that are allowed for a particular series.

Internally, some fields are stored in an encoded format, i.e. as a numeric value. Changing the default behavior of `haver.metadata` by setting argument `decode=FALSE` will store numeric values in the returned `HaverMetaData` object. In rare cases, it may be useful to access the numeric values. The list of encodings is:

field name | encoding
frequency | 10=annual, 30=quarterly, 40=monthly, 51=weekly Monday ... 57=weekly Sunday, 60=daily, 61=calendar daily
aggtype | 1=AVG, 2=SUM, 3=EOP, 9=UDF, 0=NST

### See Also

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

### Examples

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

    ## We start out by pulling in all metadata for 'HAVERMQA'
    ## and looking at it in the viewer
    hmd_mqa <- haver.metadata(dat="havermqa")

    ## Not run:
    View(hmd_mqa)

    ## End(Not run)

    ## There are monthly series between rows 75 and 101 which
    ## we choose to assign to another HaverMetaData object using row-indexing.
    ## Note that only one index vector is supplied. It refers to rows.
    hmd_2 <- hmd_mqa[75:101]

    ## Double bracket indexing refers to columns.
    ## Let's do a frequency count:
    table(hmd_mqa[["frequency"]])

    ## More complex subsetting operations have to be done after converting
    ## to a data.frame.
    ex_df_mqa <- as.data.frame(hmd_mqa)

    ## We are interested in the monthly exchange rate series starting at
    ## row 79 of 'hmd_mqa'. Let's build a subset of codes that start with 'fx...'.
    ## We utilize regular expression functions (see the help entry for 'grep')
    hmd_3 <- hmd_mqa[grep("fx.*", hmd_mqa[["code"]])]

    ## Before we can use these series for analysis we must determine
    ## whether they are quoted in an unambiguous way (units of domestic currency
    ## per units of foreign currency, or vice versa).
    ## The 'datatype' metadata field can help in this.
    table(hmd_3[["datatype"]])

    ## We see that the rates are not quoted uniformly, so we must
    ## do adjustments after pulling in the data and before doing analysis.

    ## Let's say that we need exchange rate data going back to 1970.
    ## We can immediately determine which series fail this criterion:
    hmd_4 <- hmd_3[ hmd_3[["startdate"]] > as.Date("1970-12-31", format="%Y-%m-%d") ]
    print(hmd_4, fields=c("code","start","desc"), desc.len=70)

    ## Note that we were able to abbreviate metadata fields names in the above statement.
    ## This is only possible for the 'print' method, but not for indexing.

    ## We invert the above filtering criterion to get the series that have the desired
    ## coverage. Then we feed the returned object as 'codes' argument into 'haver.data':
    hmd_5 <- hmd_3[ hmd_3[["startdate"]] <= as.Date("1970-12-31", format="%Y-%m-%d") ]
    hd_5  <- haver.data(codes=hmd_5)

    ## If we want to investigate several full databases, the best way
    ## is to 'rbind' data.frames:
    ex_df_d <- as.data.frame(haver.metadata(dat="haverD"))

    ex_df_full <- rbind(ex_df_mqa, ex_df_d)
    table(ex_df_full[["database"]], ex_df_full[["frequency"]])

    haver.path("restore")

[Package Haver version 3.2 Index]