FAME Reference

global chli

The internal state of FAME.jl. There is no reason for users to play with this.

struct Chli ⋯ end

The internal state of FAME.jl. There is no reason for users to play with this.

mutable struct FameDatabase … end

Fame database. See also opendb, closedb!, postdb, listdb.

FameDate

64-bit integer type that FAME uses to encode dates of different frequencies.

FameIndex

Integer 64-bit type that represents the internal index FAME uses to access elements of series.

mutable struct FameObject{CL,FT,FR,DT} … end

FAME object of class CL, type FT, frequency FR and data type DT.

A FameObject is returned by quick_info and a vector of FameObjects is returned by listdb.

Also, a FameObject can be constructed directly by calling FameObject(name, class, type, frequency) or FameObject(name, class, type, frequency, first_index, last_index). The values of class, type, and frequency can be symbols (like, :scalar, :precision, etc.) or integers. Refer to the FAME CHLI documentation for the code values.

struct FameRange … end

Range includes a frequency code and two endpoints start and end. This is a type used by the CHLI library.

struct HLIError <: Exception … end

Exception type for errors returned by CHLI calls.

struct Period{FREQ} … end

A FAME period includes the frequency, year and period.

check_status(status)

Check the status code returned by cfmXYZ functions. If status indicates success we do nothing, otherwise we trigger an HLIError with the error code and the message.

close_chli()

Finalize FAME and unload the CHLI library. Normally, it should not be necessary to call this function. If you want to restart FAME, e.g., in order to clear the work database, call init_chli.

closedb!(db::FameDatabase)

Close the given FAME database.

do_read!(obj::FameObject, db::FameDatabase)

Read data for the given FameObject from the given FameDatabase. obj is modified in place and returned.

A FameObject can be created directly, or it could be returned by quick_info or listdb.

do_write(obj::FameObject, db::FameDatabase)

Write the given FameObject to the given FameDatabase. If an object by the same name already exists, it is deleted before the new object is written.

fame(io, command::String)
fame(command::String; quiet=false)

Run the FAME command command and write the output to io or the screen. If io is not specified the output can be suppressed with quiet=true.

init_chli()

Load the CHLI library and initialize FAME. If it is already loaded, we first close it and then load it fresh. See also close_chli.

item_option(name, values...)

Set ITEM option. These are used when matching a wildcard to database objects. Option names include "CLASS", "TYPE", "FREQUENCY", "ALIAS".

When the values argument is not given, it defaults to "ON". Otherwise values should be strings and indicate which ITEMs are to be turned on.

listdb(db::FameDatabase, [wc; filters...])

List objects in the database that match the given wildcard and filters. Return a Vector{FameObject}.

The wildcard wc is a string containing wildcard characters. '^' matches any one character, while '?' matches any zero or more characters. If not given, the default is '?' which would list the entire database.

The filters:

• alias::Bool - whether or not to match alias names.
• class::String - which class of object to match. Multiple classes can be given in a comma-separated string, e.g., class="SERIES,SCALAR".
• type::String - which type of object to match, e.g., type="NUMERIC,PRECISION".
• freq::String - which frequency of object to match, e.g., freq="QUARTERLY".

opendb(dbname, [mode])

Open a FAME database and return an instance of FameDatabase for it.

dbname can be a path to a .db file or a string specifying a database over a remote connection in the following format.

"[<tcp_port>@]<host> [<username> [<password>] ] <db>"

mode can be an integer (consult the CHLI help), or a Symbol. Valid modes include :readonly, :create, :overwrite, :update, :shared, :write, :direct_write.

postdb(db::FameDatabase)

Post the given FAME database. If you've made any updates to the database you must post it before closing, otherwise all your changes will be lost.

quick_info(db, name)

Get information about object named name in the given database. The information inlcudes its class, type, frequency, and range. Return a FameObject in which all these attributes are set correctly, but the data does not contain the correct values.

readfame(db, args...; 
    namecase=lowercase,
    prefix=nothing, glue="_",
    collect=[], 
    wc_options...)

Read data from FAME database into Julia. The data is returned in a Workspace.

db is a FameDatabase or a String. If db is a String, the database will be opened in :readonly mode and closed after loading the data.

If the db string containing a path to a file, the path should be encapsulated in escaped double quotes whenever the path contains spaces.

If db is the only argument, then all objects in the database will be loaded. Arguments and options can be used to restrict which objects will be loaded.

Each positional argument after the first one should be a string or a Symbol.

• If it is a string that contains a wildcard character ('?' or '^', see Fame help about wildcards) then we call listdb to obtain a list of objects matching the given wildcard. In this case, we pass the given wc_options... to listdb. You can use them to limit the wildcard search to specific class, type, frequency, etc. See listdb for details.
• Otherwise (Symbol or a string not containing wildcard characters), an object with the given name will be loaded. wc_options... are ignored, meaning that the object will be loaded no matter its class, type, frequency, etc.

The following options can be used to modify how the Julia identifiers are constructed from the FAME names.

• namecase - FAME identifiers are case-insensitive and FAME always returns them in upper case. By default we convert the names to lower case. You can pass any function that takes a string and returns a string as the value of the namecase option. The default is lowercase. For example, this may be a good idea if your database contains names with symbols that are not allowed in Julia identifiers. Currently, we just call Symbol(namecase(fo.name)), but you may want to substitute such symbols for something else, e.g. namecase=(x->lowercase(replace(x, "@"=>"_"))).
• prefix, if given, will be stripped (together with glue) from the beginning of the FAME name. If the name does not begin with the given prefix then it will remain unchanged. If you want to load only names starting with the given prefix you must use the appropriate wildcard. Default is prefix=nothing, which disables this functionality. Note that prefix=nothing and prefix="" are not the same.
• collect can be a string/symbol, a vector whose elements are strings/symbols or vectors of strings/symbols, etc. If the name begins with one of the given collect values (together with the glue), then the object will be loaded in a nested Workspace. The idea is that nested Workspaces written to the database would be loaded in the same structure by providing the list of names of the nested Workspaces in the collect option value. See the examples below.
• glue is used to join the prefix or the collect strings to the rest of the name. Use the same value as in writefame in order for this to work.

Examples

julia> w = Workspace(; a = 1, b=TSeries(2020Q1, randn(10)),
       s = MVTSeries(2020M1, (:q, :p), randn(24,2)),
       c = Workspace(; alpha = 0.1, beta = 0.8, 
       n = Workspace(; s = "Hello World")
       ))
Workspace with 4-variables
  a ⇒ 1
  b ⇒ 10-element TSeries{Quarterly} with range 2020Q1:2022Q2
  s ⇒ 24×2 MVTSeries{Monthly} with range 2020M1:2021M12 and variables (q,p)
  c ⇒ Workspace with 3-variables

julia> writefame("data.db", w); listdb("data.db")
7-element Vector{FameObject}:
 A: scalar,numeric,undefined,0:0,0:0
 B: series,precision,quarterly_december,2020:1,2022:2
 C_ALPHA: scalar,precision,undefined,0:0,0:0
 C_BETA: scalar,precision,undefined,0:0,0:0
 C_N_S: scalar,string,undefined,0:0,0:0
 S_P: series,precision,monthly,2020:1,2021:12
 S_Q: series,precision,monthly,2020:1,2021:12

julia> # read only variables in the list
julia> readfame("data.db", "a", "b")
Workspace with 2-variables
  a ⇒ 1.0
  b ⇒ 10-element TSeries{Quarterly} with range 2020Q1:2022Q2

julia> # read everything as it is in the database
julia> readfame("data.db")
Workspace with 7-variables
        a ⇒ 1.0
        b ⇒ 10-element TSeries{Quarterly} with range 2020Q1:2022Q2
  c_alpha ⇒ 0.1
   c_beta ⇒ 0.8
    c_n_s ⇒ 11-codeunit String
      s_p ⇒ 24-element TSeries{Monthly} with range 2020M1:2021M12
      s_q ⇒ 24-element TSeries{Monthly} with range 2020M1:2021M12

julia> # prefix is stripped where it appears (still loading everything)
julia> readfame("data.db", prefix="c")
Workspace with 7-variables
      a ⇒ 1.0
      b ⇒ 10-element TSeries{Quarterly} with range 2020Q1:2022Q2
  alpha ⇒ 0.1
   beta ⇒ 0.8
    n_s ⇒ 11-codeunit String
    s_p ⇒ 24-element TSeries{Monthly} with range 2020M1:2021M12
    s_q ⇒ 24-element TSeries{Monthly} with range 2020M1:2021M12

julia> # wildcard search, no prefix (name remains unchanged)
julia> readfame("data.db", "s?")
Workspace with 2-variables
  s_p ⇒ 24-element TSeries{Monthly} with range 2020M1:2021M12
  s_q ⇒ 24-element TSeries{Monthly} with range 2020M1:2021M12

julia> # prefix (stripped) with matching wildcard search
julia> readfame("data.db", "s?", prefix="s")  
Workspace with 2-variables
  p ⇒ 24-element TSeries{Monthly} with range 2020M1:2021M12
  q ⇒ 24-element TSeries{Monthly} with range 2020M1:2021M12

julia> # collect with matching wildcard
julia> readfame("data.db", "c?", collect="c")   
Workspace with 1-variables
  c ⇒ Workspace with 3-variables

julia> # nested collect - matches the original structure of nested Workspaces
julia> readfame("data.db", collect=["c"=>["n"], "s"])  
Workspace with 4-variables
  a ⇒ 1.0
  b ⇒ 10-element TSeries{Quarterly} with range 2020Q1:2022Q2
  c ⇒ Workspace with 3-variables
  s ⇒ Workspace with 2-variables

julia> readfame(""/home/usr/my data directory/data.db"", "a", "b")   
Workspace with 2-variables
  a ⇒ 1.0
  b ⇒ 10-element TSeries{Quarterly} with range 2020Q1:2022Q2

refame(name, value)

Convert the given value to a FameObject

• Real => NUMERIC SCALAR (includes integers)
• Float64 => PRECISION SCALAR
• Bool => BOOLEAN SCALAR
• MIT => DATE SCALAR
• String => NAMELIST, if it is in the form "{name1,name2,...}", otherwise STRING SCALAR
• Vector{String} => CASE SERIES of STRING
• TSeries => a SERIES of the same frequency and type. The type conversions are the same as for scalars.

unfame(fo::FameObject)

Convert a FameObject to a Julia type.

• PRECISION SCALAR => Float64
• NUMERIC SCALAR => Float32
• STRING SCALAR => String
• BOOLEAN SCALAR => Bool
• NAMELIST => String (Formatted as "{NAME1,NAME2,ETC}", see Fame help for details.)
• DATE SCALAR => MIT (CASE becomes MIT{Unit}, Frequencies not supported by TimeSeriesEcon throw an ErrorException)
• PRECISION SERIES => TSeries
• NUMERIC SERIES => TSeries with element type Float32
• BOOLEAN SERIES => TSeries with element type Bool
• DATE SERIES => TSeries with element type MIT
• STRING SERIES => Vector{String} (the time series metadata is lost)

version()

Return the version of FAME in use.

workdb()

Return a FameDatabase instance for the work database.

Since the work database can be open only once, we create an instance the first time and return the existing instance each subsequent time.

writefame(db, data; options)

Write Julia data to a FAME database.

Arguments:

• db can be a string containing the path to a FAME .db file or an instance of FameDatabase.
• data is a collection of data which will be written to the database.
  • If data is an MVTSeries, each series will be written to the database.
  • If data is a Workspace, each element will be written as a separate FAME object. In this case any nested Workspace of MVTSeries objects will be written recursively by prepending the names.

Options:

• mode::Symbol - if db is a string, the database is opened with the given mode. The default is :overwrite.
• prefix::Union{Nothing,String} - the given prefix will be prepended to the name of each object written in the database. The default is nothing, i.e. nothing will be prepended. NOTE: prefix=nothing and prefix="" are not the same.
• glue::String - the glue is used to join the prefix to the name. The default is "_".

Examples:

julia> w = Workspace(; a=1, b=TSeries(2020Q1,ones(10)), s=MVTSeries(2020M1, collect("ab"), randn(24,2)))
Workspace with 2-variables
  a ⇒ 1.0
  b ⇒ 10-element TSeries{Quarterly} with range 2020Q1:2022Q2
  s ⇒ 24×2 MVTSeries{Monthly} with range 2020M1:2021M12 and variables …

julia> writefame("w.db", w)

julia> listdb("w.db")
2-element Vector{FAME.FameObject}:
 A: scalar,precision,undefined,0:0,0:0
 B: series,precision,quarterly_december,2020:1,2022:2
 S_A: series,precision,monthly,2020:1,2021:12
 S_B: series,precision,monthly,2020:1,2021:12

@cfm_call(:cfmXYZ, argTypes, args...)

Build an appropriate ccall to the given cfmXYZ function. When using this macro, include the status variable and check it yourself.

See also: @cfm_call_check

@cfm_call_check(:cfmXYZ, argTypes, args...)

Call the cfm function and check status. When using this macro, do not include the status variable.

See also: @cfm_call

@cfm_global(:cfmXYZ, type)

Fetch the value of a constant by the given name from the CHLI library.

See also: @cfm_call_check

@fame_call(:fame_XYZ, argTypes, args...)

Build an appropriate ccall to the given fame_XYZ function.

See also: @cfm_call_check

@fame_call_check(:fame_XYZ, argTypes, args...)

Build an appropriate ccall to the given fame_XYZ function. This macro also checks the status and throws an error if not success.

See also: @cfm_call_check

fame"command"
fame"command"q

Run the the FAME command and write the output to the screen, or suppress the output if the q flag is present.