erikwestlund / soar

🦅 Soar: A CLI Helper for the Johns Hopkins University Crunchr Platform

This package is a CLI helper for the Johns Hopkins University Crunchr platform. It is designed to automate tasks that would otherwise be tedious, such as:

• Mounting network volumes.
• Preparing containers with the necessary software and dependencies, such as Java runtimes, database drivers, and R/Python packages.
• Managing credentials in a secure vault that can be easily accessed from R/Python.
• Storing known-working database drivers and other dependencies.
• Generating config files for analysis notebooks, including database connection strings.
• Enhancing the shell environment to be more productive.
• Configuring RStudio settings on new container instances.

Installation

Install the tool by running this command from an RStudio terminal in a Crunchr container:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/erikwestlund/soar/master/install.sh)" && source ~/.bashrc

This will install the package on your persistent storage, and add the soar command to your shell. The package will thus be available across containers.

Usage

All commands must be run from a Terminal window in RStudio.

Upon a successful first-time installation, type soar to configure your container. You will be asked to enter a keyring password, which will be used to encrypt your credentials. You will also be asked to enter your JHED username and password.

After configuration, you can use the soar command to access the various options available. You can type crunchr, which is an alias for the soar command.

Most commands will prompt you for actions, making it easy to use the tool without memorizing all the options.

However, you can also type soar <command> --help to see the various options available for each command.

Configuration

To update your configuration at any time, type soar configure. You will be prompted with a list of options for what you would like to update.

Your configuration is stored in the config.yml file in your soar package directory. This file is sym-linked to your workspace directory in your container, making you able to access it using the R config package by simply running config::get().

Features

Mounting Network Volumes

The soar mount commands allow you to mount network volumes. This is useful for accessing your JHU network drives from your container, as well as other SAFE volumes.

• soar mount home mounts your home directory to /homes/idies/workspace/home.
• soar mount project mounts a SAFE project directory to /homes/idies/workspace/project, where project is the name of the project.

Installing Software

The soar install commands allow you to install software and dependencies.

• soar install r-data-tools installs useful R packages for managing and manipulating data, such as the Tidyverse suite and numerous database connection utilities.
• soar install r-data-analysis installs useful R packages for analyzing data, such as packages for applied regression analysis, multilevel modeling, Bayesian analysis, and more.
• soar install r-ohdsi installs useful OHDSI-related packages, such as rJava.
• soar install r-data-suite installs the R data tools and analysis packages.
• soar install all installs all of the above packages.

Enhancing Your Container

The soar enhance commands allow you to enhance your container environment.

• soar enhance shell install the Zsh shell, tells RStudio to use it, and installs Oh My Zsh for a better shell experience. This command also installs the alias helpers described below.
• soar enhance rstudio-keybindings configures RStudio keybindings to be more like popular text editors, such as VSCode and Sublime Text. For example, Ctrl+D will allow for selecting multiple instances of a word with multiple cursors.
• soar enhance aliases installs useful aliases for the shell, such as git convenience commands like ac for git commit -am and s for git status.

Managing Credentials

The soar configure commands allow you to manage your credentials. It does so by creating a secure keyring that is encrypted with a password you provide.

The keyring is split up by services. For example, there is a jhed service for your JHED credentials, and a github service for your Github credentials.

To access your credentials from R, use the keyring package. For example:

• To access your JHED password, you would run keyring::key_get("jhed", "[jhed_username]").
• To access your Github Personal Access Token, you would run keyring::key_get("github", "[github_username]").

Should you forget or mis-type your keyring password, you can reset it by typing soar keyring-reset.

Managing Projects

The soar project commands allow you to manage your project configuration files.

Running soar project will prompt you with a list of options for managing your project configuration files.

Upon configuring your project, example files using the convention config.[project].yml will be created in your projects directory of the installed SOAR package. They will also be copied to the workspace directory in your container.

These files should be stored with the source code for individual projects. They can be merged with your personal configuration using the config project in R.

Generating Config and Other Templates

The soar make commands allow you to generate config files and other templates.

This command will also copy necessary drivers and other dependencies to the appropriate locations.

Upon running soar make, you will be asked to enter the necessary information to generate the config file.

The program will return directions on how to incorporate the generated config files into your analysis notebooks and scripts.

Status

You can view all of your current settings and configurations by typing soar status.

Package Information

This package is currently under development.

Soar is written in Python.

Author: Erik Westlund