getfame {fame}R Documentation

Fame Interface

Description

getfame and putfame read and write scalars (ti, numeric, character or logical objects of length 1) and numeric tis (Time Indexed Series) from and to Fame databases. FAME case series and series with string or FAME "date" types can be read by getfame, but not written with putfame.

fameWhats returns information about an object in a database, including its name, class, type, basis and observed attributes, as well as start (a ti Time Index) and length. If getDoc is TRUE, it will also include description and documentation components.

fameWhats is a wrapper around the function fameWhat, which provides the same information in a lower-level form.

fameWildlist returns a list giving the name, class, type and frequency of the objects in the database with names that match wildString.

Usage

getfame(sernames, db, save = F, envir = parent.frame(),
        start = NULL, end = NULL, getDoc = T)
putfame(serlist, db, access = "shared", update = T,
        checkBasisAndObserved = F, envir = parent.frame()) 
fameWhats(db, fname, getDoc = T)
fameWildlist(db, wildString = "?", nMax = 1000, charMode = T)

Arguments

sernames character vector of Fame names of series and/or scalars to retrieve.
db string giving the relative or full path to the Fame database to read or write from. If the fameLocalPath() function is defined, it will be called on this argument to obtain a path. At the Federal Reserve Board, fameLocalPath() knows how to look up the path for 'registered' databases given only their names, e.g., "us", "intl", and so on. Full path names are thus unnecessary for registered databases, and in fact are a bad idea, since the database might get moved.
save if T the retrieved series are individually saved in the environment specified by envir.
envir for getfame, the environment used by assign to save the retrieved series if save is T. For putfame, if serlist is a character vector, the environment in which to find the series that will be stored in the database. The default environment for both functions is the frame of the caller.
start a ti object, or something that the ti function can turn into a ti object. The time index for the first observation in the returned series. The default is the series start in the database.
end a ti object, or something that the ti function can turn into a ti object. The time index for the last observation in the returned series. The default is the series end in the database.
getDoc if TRUE (the default), also get the series description and documentation attributes, accessible via functions of the same names.
serlist the objects to be written to the database. This can be a character vector giving the names of the objects in the environment specified by envir, a list containing the objects, or an object itself. Objects that can be written to the database include scalars (single numbers, strings, and ti dates), and tis series.
access string specifying the access mode to open the database in. Should be one of c("create", "overwrite", "read", "shared", "update"). Warning: Opening an existing database in "overwrite" mode wipes out the database. You almost never want to do this.
update if TRUE (the default), existing series in the database will be updated. If FALSE, existing series in the database with the same names will be replaced by the series in serlist. Fame scalars (single strings, numbers or ti dates) always overwrite their previous incarnations.
checkBasisAndObserved if TRUE and update == TRUE, the basis and observed attributes of any existing series with the same name will be checked for consistency with the updating series from serlist. If the basis or observed attributes differ, the update will not happen. This argument has no effect with respect to non-series objects.
fname name of an object in a FAME database
wildString string containing FAME wildcards
nMax maximum number of matches to return
charMode if TRUE (the default) return class, type and freq components as strings, rather than integer codes.

Details

Fame names vs. R names:

The R names of series may differ from their Fame names. For getfame, names(sernames) holds the R names of the retrieved series. If sernames does not have a names attributes, the R names will be the same as the Fame names.

Naming for putfame is more complicated, because the series specified by serlist for putfame may be univariate or multivariate. For a multivariate series, the column names of the matrix become the Fame names. Not having a name for each column is thus an error.

A univariate series may be a single-column matrix. If it is, and it has a column name, that becomes the Fame name of the series. Otherwise, the Fame name of a univariate series is the corresponding element of names(serlist). If serlist is an actual list of series, names(serlist) must be of the same length. For character vector serlist a names attribute is optional. If there isn't one, the Fame names will be the same as the R names.

Consistency checking when update == TRUE:

If there is already an existing series in the database with the same name as one in serlist, the Fame class, type, and frequency are checked for consistency between the updating series and the existing series in the database. In addition, if checkBasisAndObserved is TRUE, those attributes are also checked. Inconsistencies for any of the checked attributes between the updating existing series will abort the update. The default value for checkBasisAndObserved is set to FALSE because this inconsistency is very common in MRA code.

Value

getfame returns a list of the retrieved objects. If save is T, the list is returned invisibly. The names of the list are the R names described in the details. Fame scalars are returned as strings, ti dates, or numbers. Case series are returned as vectors of the appropriate type, without any case numbers. If getDoc is TRUE (the default), retrieved objects will also have attributes named description and documentation.
putfame invisibly returns an empty string.

Note

These functions use the Fame HLI and a child server process. The function fameRunning is called to see if the server process is already running. If not, fameStart starts it and the HLI. Your .Last function should call fameStop to shut them down gracefully. In any given R session, once the Fame HLI has died for any reason, it cannot be restarted. This is a Fame limitation. On exit, getfame always closes whatever databases it opened, so there's no reason not to just leave the server running as long as the R session is alive. Death of the R process kills the server process as well.

See Also

ti, tis

Examples

## Not run: 
usdb <- "/fame/data/database/us.db"
boink <- getfame("gdp.q", db = usdb)     ## returns a list
gpd.q <- boink[[1]]                      ## or boink$gdp.q
getfame("gdp.q", db = usdb, save = TRUE) ## saves gdp.q in the current frame

## saves the series as "nominalIncome"
getfame(c(nominalIncome = "gdp.q"), db = usdb, save = TRUE)
seriesA <- tis(1:24, start = c(2002, 1), freq = 12)
seriesB <- tis(1:104, start = c(2002, 1), tif = "wmonday")
documentation(seriesB) <- paste("Line", 1:4, "of seriesB documentation")
## store them as "mser" and "wser"
putfame(c(mser = "seriesA", wser = "seriesB"), db = "myfame.db")

matrixSeries <- cbind(a = seriesA, b = seriesA + 3)
putfame(matrixSeries, db = "myfame.db") ## stores as "a" and "b" in Fame

## storing a scalar as "myscalar"
putfame(c(myscalar = 42), db = "myfame.db") 

fameWildlist("myfame.db")
fameWhats("myfame.db", fname = "wser", getDoc = TRUE)
## End(Not run)

[Package fame version 2.5 Index]