package-variables.Rmd
Environmental variables are seemingly trivial but often overlooked
assets. If an argument in your code is recurrent, defining environmental
variables is a time saver. For example, consider you have several
scripts accessing the same online database, which requires user
credentials. If you need to modify those credentials, it can be
bothersome to change every single script. As an alternative, we can use
R’s options() to define a variable that contains those
credentials.
masDMT takes advantage of this feature through the
register_path(). This function registers paths to the MAS
database as well as to relevant documentation. This information is
recorded permanently together with your package installation, which
prevents you from repeating this step with every script. Every time the
masDMT loads, the pre-defined variables will be loaded.
To exemplify the use of this tool, let’s first register our database,
which is located in /mas/database/. To register this path,
we can use register_path as following:
# consult the current data path
register_path(list(dmt.data='/mas/database/'))
Note the input to the function is in the form of a list, and the keyword
dmt.data is used to register the database. This is the
go-to variable for functions that query the existing database, such as
list_data().
dmt.data is not the only variable we can set. First, we can
change the option mas.catalog, which changes the path to
the standardized data catalog of the MAS database. This catalog,
available
through GitHub, contains data descriptions for the datasets used at
MAS. However, if we wish to keep the catalog locally - or register a new
catalog- we can modify the the mas.catalog option.
Following the same premise, we can modify mas.toolbox,
which links us to the website of this package by default.
# change path to new catalog website
register_path(list(dmt.catalog='/new_catalog/'))
# change path to new toolbox website
register_path(list(dmt.toolbox='/new_toolbox/'))
In the previous examples, we changed one variable at a time for the sake
of simplicity. However, you can provide all variables at once. Since the
input is provided as a list, register_path() can update
several variables simultaneously, making use of the list names to find
the right variable to modify.
register_path(list(dmt.data='/mas/database/', dmt.catalog='/new_catalog/', dmt.toolbox='/new_toolbox/'))