Getting Started with fredcli

This section describes how to get started with the FRED Command-Line Interface, or fredcli.

Note

This documentation assumes use of the bash shell for Linux / macOS environments; use of another shell is expected to be compatible but may require slight modifications to the commands shown in this document.

Preparing to Install

Before you install the FRED Local solution, this section provides some background and configuration steps that are important to install successfully.

Hardware Requirements

There are very few hardware requirements for running fredcli, other than the environment and tools needed to manage local data and files.

Installation Prerequisites

These instructions are for installing and running fredcli version 0.1. Before getting started, please ensure you have the following software installed on the computer where you plan to run FRED.

  • Python: Install the Python environment. We recommend running Python 3.8 or later. Instructions for installing python can be found here: https://www.python.org/.

  • API KEY: You should have been granted an API key for the Epistemix Python Package Index (PyPI) server.

  • FRED Cloud User: You should also have a FRED Cloud user name and password. Your user name should be your email address, your password should be kept secret.

If you do not have an API Key, a FRED Cloud user, or encounter other problems, please contact Epistemix support.

Configuring the FRED_API_KEY environment variable

It is also useful to create a local environment variable FRED_API_KEY that holds the API key provided by Epistemix. This is not strictly required, though we will assume this environment variable exists in our examples and discussions. It is suggested but not required that you make this environment variable “permanent” via mechanisms appropriate to your operating system (such as modifying your .bashrc file).

$ FRED_API_KEY=<key>
$

Here, the <key> is replaced with the API key provided by Epistemix. For example, if you are given the key ABC12DEF34GHI56JKL78MNO90PQR then you could set this environment variable on a macOS platform with the following command:

$ FRED_API_KEY=ABC12DEF34GHI56JKL78MNO90PQR
$

Installing fredcli

Installing fredcli requires that you add the Epistemix PyPI server to the pip install command using the --index-url option. Since there are also dependencies on the public PyPI server, you also need to specify the public server with the --extra-index-url option. For more information on using the pip command with these or other options, please see the official documentation at https://pip.pypa.io/en/stable/cli/pip_install/.

The following examples show sample output.

$ pip install fredcli \
--index-url https://:${FRED_API_KEY}@epistemix.jfrog.io/artifactory/api/pypi/pypi/simple \
--extra-index-url=https://pypi.org/simple
Looking in indexes: https://:****@epistemix.jfrog.io/artifactory/api/pypi/pypi/simple, https://pypi.org/simple, https://pypi.org/simple
Collecting fredcli
Using cached https://epistemix.jfrog.io/artifactory/api/pypi/pypi/fredcli/0.1.1/fredcli-0.1.1-py3-none-any.whl (27 kB)
Collecting pyyaml
Using cached PyYAML-6.0-cp38-cp38-macosx_10_9_x86_64.whl (192 kB)
Collecting requests
Using cached requests-2.26.0-py2.py3-none-any.whl (62 kB)
Collecting click>=8.0.1
Using cached click-8.0.3-py3-none-any.whl (97 kB)
Collecting tabulate
Using cached tabulate-0.8.9-py3-none-any.whl (25 kB)
Collecting charset-normalizer~=2.0.0
Using cached charset_normalizer-2.0.9-py3-none-any.whl (39 kB)
Collecting idna<4,>=2.5
Using cached idna-3.3-py3-none-any.whl (61 kB)
Collecting urllib3<1.27,>=1.21.1
Using cached urllib3-1.26.7-py2.py3-none-any.whl (138 kB)
Requirement already satisfied: certifi>=2017.4.17 in /Users/eeb/opt/anaconda3/envs/test/lib/python3.8/site-packages (from requests->fredcli) (2021.10.8)
Installing collected packages: urllib3, idna, charset-normalizer, tabulate, requests, pyyaml, click, fredcli
Successfully installed charset-normalizer-2.0.9 click-8.0.3 fredcli-0.1.1 idna-3.3 pyyaml-6.0 requests-2.26.0 tabulate-0.8.9 urllib3-1.26.7
$ fredcli --version
fredcli, version 0.1.1

Configuring fredcli

After fredcli is installed, we can configure the command to run against FRED Cloud. This section walk through the initial configuration required and demonstrates some of the available commands.

Getting an Access Token

An access is required to tell fredcli where to find the FRED Cloud server and to verify your permissions. To obtain a token and configure fredcli please use the following steps.

  1. Visit https://studio.epistemix.cloud/access-token. You will be asked to log in to the site with your user name and password.

FRED Studio Access Token Page
  1. Click the GET CLI ACCESS TOKEN button to generate a token. The token will display on the page and is automatically copied to the clipboard. You can also click the Copy icon to copy the token directly. A small popup window will display at the base of the page to confirm the token was copied.

Copy Access Token Notification

Storing the Access Token

Once you have an access token, you can configure fredcli to use it with the fredcli user login command.

  1. To store the token, add the access token to the login command. This will store the token in your local file system.

$ fredcli user login brJhbGci7iJIUwI1N..Tw2fbFfxIRbF
$

This command creates the configuration file config.json in the .fredcli directory of your user home directory. If you are saving an access token when a token previous exists, you should use the --overwrite-existing option with the above command. See the fredcli user documentation for details.

Running a FRED model

At this point, you should have fredcli installed and configured to interact with FRED Cloud. This section walks through running a FRED model to illustrate how some additional fredcli commands are used.

Download a Sample Model

Epistemix provides a public Tutorials repository with a collection of models that demonstrate essential features of the FRED Modeling Language. The documentation for these models is part of the Epistemix Documentation and you can download this repository from GitHub.

$ cd $FRED_HOME/models
$ git clone https://github.com/Epistemix-com/FRED-tutorials.git
Cloning into 'FRED-tutorials'...
remote: Enumerating objects: 300, done.
remote: Counting objects: 100% (300/300), done.
remote: Compressing objects: 100% (175/175), done.
remote: Total 300 (delta 176), reused 231 (delta 120), pack-reused 0
Receiving objects: 100% (300/300), 2.14 MiB | 6.32 MiB/s, done.
Resolving deltas: 100% (176/176), done.

Run a Sample Model

Now that you have the tutorial models, you can execute the sample model in the FRED-tutorials directory. We mounted this in the container as the /fred/models directory, and the container’s current working directory should be this location as well.

You will see a few models in the directory. While any of these can be used, in our example we will use the model in the simpleflu directory, which simulates a simple Influenza strain in Jefferson Country, Pennsylvania.

By convention, the core FRED program file for a model is called main.fred. If using FRED locally, a sample run script file to test the model is called METHODS. In our case we want to run the model in the cloud. To do this, fredcli uses a configuration file.

The simpleflu model contains a sample configuration file fredconfig.json suitable for use with fredcli. For details on the configuration file format, see Batch Configuration Files.

Here are the steps required to run this model in FRED Cloud.

  1. Change to the simpleflu directory.

$ cd FRED-tutorials
$ cd simpleflu
$
  1. Submit the model directory as a batch to FRED Cloud. Note that the batch guid you receive will be different than what is shown here.

$ fredcli batch submit --config-file
Packaging model code.
Uploading model code.
Model code successfully uploaded.
Starting execution.
Your batch guid is 7d362052eb35456990f4e252d4df7245
To track the status of your batch use fredcli batch get-status 7d362052eb35456990f4e252d4df7245
  1. Check the status of the submitted batch. It will likely show as either Queued if the batch is still pending, or Submitted if FRED Cloud is scheduling the batch for processing.

$ fredcli batch get-status 7d362052eb35456990f4e252d4df7245
Labels:
Submitted by:  [email protected]
Submitted on:  2021-12-07 21:50:42.136000 EST-0500

Status set on:  2021-12-07 21:50:46.613000 EST-0500
Status:  Submitted

Tasks:
|   ID |    Status |                       Status set on |
|------|-----------|-------------------------------------|
| 3365 | Submitted | 2021-12-07 21:50:42.136000 EST-0500 |
$
  1. After a few minutes, the batch should complete and you will see a Succeeded status.

$ fredcli batch get-status 7d362052eb35456990f4e252d4df7245
Labels:
Submitted by:  [email protected]
Submitted on:  2021-12-07 21:50:42.136000 EST-0500

Status set on:  2021-12-07 21:53:46.185000 EST-0500
Status:  Succeeded

Tasks:
|   ID |    Status |                       Status set on |
|------|-----------|-------------------------------------|
| 3365 | Succeeded | 2021-12-07 21:53:46.167000 EST-0500 |

Some additional commands you should review and try with this batch include:

Next Steps

At this point, your FRED Cloud Environment is installed, verified, and ready! We recommend reading the rest of this guide for some ideas to get you started.