Skip to content

Getting Started

Jump to bottom
Sam Minot edited this page Jul 15, 2022 · 15 revisions

Quick Start

To get up and running with gig-map, the basic tasks required are:

Install Nextflow

The gig-map software uses Nextflow to coordinate all of its constituent tasks. This provides powerful support for parallelization, installing software dependencies, and even support for high-performance computing clusters or cloud computing. Follow the instructions on the Nextflow website to install Nextflow on whatever computer you would like to use to run gig-map.

One common issue encountered by users is the error nextflow: command not found even after following the instructions for installing Nextflow. This is usually due to the fact that the Nextflow executable file needs to be placed in a location which the computer checks for installed software, called the "path". When following the instructions for downloading the Nextflow executable file, make sure to copy the downloaded file (named nextflow) to a folder in your PATH. You can check to see what folders are valid options by running the command echo $PATH. Often the folder /usr/local/bin is in that list, and you can copy the downloaded executable to that folder with cp nextflow /usr/local/bin/. Finally, make sure that the file is set to executable mode with chmod a+x /usr/local/bin/nextflow.

Install jq

One of the utilities which gig-map takes advantage of is jq, a small script for manipulating JSON files. If you encounter the error jq: command not found, please follow the instructions here for downloading it and installing on your system. You may need to follow the similar guidance as shown above for placing the executable in your PATH.

Install Docker

All of the software dependencies for gig-map are distributed to users via reproducible software containers (i.e. Docker images). If gig-map is being run on a standalone computer such as a personal computer or a dedicated lab server, the simplest way to support this behavior is to install Docker Desktop and configure Nextflow to use Docker as described in the Advanced Notes. However, this approach is not practical for shared computing clusters, and is not required for cloud computing platforms.

For shared computing clusters which typically do not allow the use of Docker, the most appropriate solution may be instead to use Singularity. For more details, see our brief guide for using Singularity with the BASH Workbench.

Install the BASH Workbench

The BASH Workbench is used to help you set up each of the gig-map tools with each of the appropriate options needed for execution. At its core, the BASH Workbench is a simple Python utility which creates BASH scripts based on templates and helps you run them. The gig-map templates are all configured in the ._wb/ folder in a format which can be used by the BASH Workbench.

To install the BASH Workbench, follow the instructions here.

One of the benefits of using the BASH Workbench is that it helps provide guidance when setting up the parameters for a particular analysis, making it harder to mistype file paths, add variables of the wrong type, or ask for an option which isn't available.

enter-params

Load the Repository

To install the gig-map repository of tools in your environment simply:

  • open the BASH Workbench (with the wb command)
  • select "Manage Repositories"
  • select "Download New Repository"
  • enter FredHutch/gig-map as the repository name
  • confirm the download

And this repository will be added to your environment.

download_repository

To update the version of gig-map being used on your system, you can select the option:

-> Manage Repositories
   -> Manage repository gig-map
      -> Update to latest version

Get Started

When running each of the gig-map tools, the easiest way to stay organized is to keep each unit of analysis in its own folder. Because the BASH Workbench will save a copy of the code that was run at each step, you can then go back and see exactly what was done to produce the outputs in each directory.

Once you're ready to make your own maps, navigate to a folder which you want to use for the outputs of one of the tools, launch the wb, select Run Tool, and select the gig-map tool that you want to run.

Advanced Notes

For more details on the inner workings of the gig-map Nextflow workflows, see our advanced notes.

Clone this wiki locally