ramp v1.0.0


Running Ramp on Google Colab


If you do not have access to a machine with the minimum specifications outlined in the “Setting Up Ramp” section, don’t worry! We tested this same model on Google’s Colab cloud platform and have shared the process to deploy ramp on Colab below. While the ramp codebase can be deployed on the free tier of Colab, it is worth noting that the free tier can be frustrating and it may be worth signing up for the $10/month tier to avoid process timeouts and deprioritization. 

Step 1: Download the ramp codebase onto your local computer

It doesn’t matter where it is downloaded. You will only need to do this in order to upload the colab/jupyterlab_on_colab.ipynb file to Google Colab in the next step.

Step 2: Start a Jupyter Lab instance on Colab

Go to the Google Colab website.


Make sure that you are logged into Colab as the same user whose Google Drive you will be mounting for permnanent storage of your training data! You will get a mysterious error if you try to mount the Google Drive from a different 'Google persona' than the one you used to log in to Colab.

On the menu at the upper left, select ‘File > Upload Notebook’, and upload the ‘jupyterlab_on_colab.ipynb‘ notebook file from the ‘colab‘ directory of the ramp codebase.

Execute the commands in that notebook within Colab to start your jupyter lab session, and then move on to step #3

Step 3. Create the “RAMP_HOME” Directory

Assuming you now have a running Jupyter Lab session going, your personal Google Drive will be in the directory list in the window at left. Navigate to /drive/MyDrive; that is your Google Drive home directory.

Once you’re in this directory, click on the ‘Create New Folder’ icon at the top of the file menu, and name your new folder “RAMP_HOME”. You will only need to do this once, as anything written here will remain on your Personal Google Drive until you remove it.

Step 4. Create ramp-data directory 

Navigate to RAMP_HOME, and create another new folder named “ramp-data”.

Step 5. Open a terminal 

In the main panel of Jupyter Lab, there are a number of applications you can select. Click on the Terminal application to open a terminal into the remote host. This terminal is running Linux, and will usually place you inside a directory named ‘/content’. You’ll want to navigate to your RAMP_HOME directory.

To do this, type ‘ls’ at the command line. This will list all the subdirectories of ‘/content’, one of which will be ‘drive’. Type:

cd drive/MyDrive


to get back to your main Personal Drive directory, and then type

					cd RAMP_HOME


to be placed in the RAMP_HOME directory. From here, you can download and install the ramp codebase.

Step 6. Clone the ramp github repository.

The next step is to authenticate yourself to github, so it will allow you to download the ramp code. Unfortunately, authenticating yourself to github is no longer as easy as entering your name and password, but it’s not too much harder. In order to authenticate, you’ll first need to generate a “Personal Access Token” from your account on the github webside. Instructions for doing this can be found Here

Note that if you don’t already have a github account, you’ll need to create one before creating a personal access token!

Once you have a personal access token, run the following commands from the terminal inside JupyterLab:

					git config --global user.name "your_github_username"
git config --global user.email "your_email"
git clone https://github.com/devglobalpartners/ramp-code.git


You’ll be prompted for your username and password. For your password, enter that Personal Access Token that you saved. (Note that you can copy-paste this from your saved location into the browser).

The ramp code will then be downloaded to your RAMP_HOME directory.

Step 7. Install the required packages & binaries to run the ramp code

The required packages are specified in a Makefile in the colab directory within the ramp codebase. Type the following at the Jupyter Lab command line:

					cd ramp-code/colab
make install

This process will take quite a while to complete, as the ramp and solaris modules have many dependencies.

Step 8. Install the ramp code.

After ‘make install’ finishes, you will still be in the ‘ramp-code/colab’ directory. Typing `cd ..` will step you up one level in the directory structure, so you’ll be in the ‘ramp-code’ directory. Type the following at the command line:

					cd ..
pip install -e .

to install the ramp modules. This command will finish quickly.

To test whether your installation worked, start a python session as follows:

>> import ramp


If *import ramp* runs successfully, you have installed the ramp modules.

Step 9. Run Training

In Jupyterlab, open and run the Colab model training notebook: `train_ramp_model_on_colab.ipynb`.

Running Scripts in Colab

Once your Colab environment is set up, all of the scripts in the Ramp codebase can be run from the JupyterLab terminal. 

Prior to running these scripts, it is critical to ensure that your RAMP_HOME environmental variable is set. To set the variable, run the command below. Note that the path entered as the value for RAMP_HOME should be identical to the filepath to the RAMP_HOME directory that you set up in the previous steps. 

					export RAMP_HOME=/content/drive/MyDrive/RAMP_HOME

To check that the variable was set properly run:

					echo $RAMP_HOME

This should print out the path that you entered.


Now you can run the ramp scripts in your environment by simply typing python, and then the path to the script and entering its required arguments


Before running a script, you should check what arguments are required to run it. This can be done by calling the script and then passing the argument "-h" after it. For example "python /content/drive/MyDrive/RAMP_HOME/ramp-staging/scripts/polygonize_multimasks.py -h". This will print out a description of the script, and all the arguments that can be provided.

Below you can see an example of calling a python script with the -h argument in line 1, and the output in the lines below it. 

					python /content/drive/MyDrive/RAMP_HOME/ramp-code/scripts/polygonize_multimasks.py -h

usage: polygonize_multimasks.py [-h] -in INPUT_DIR -out OUTPUT_DIR

    Create matching geojson polygon outputs from a directory of multichannel masks.
    Example: polygonize_multimasks.py -in multimask_dir -out polygons_dir.

optional arguments:
  -h, --help            show this help message and exit
  -in INPUT_DIR, --input_dir INPUT_DIR
                        Path to directory containing input multichannel masks.
  -out OUTPUT_DIR, --output_dir OUTPUT_DIR
                        Path to output directory containing polygonized data

Now we know that we need to pass an -in argument and an -out argument, the path to the multimasks, and our desired output folders respectively.

Below is our final command that will run the script with the required arguments populated:


					python /content/drive/MyDrive/RAMP_HOME/ramp-code/scripts/polygonize_multimasks.py -in /content/drive/MyDrive/RAMP_HOME/ramp-data/TRAIN/tiny_aoi/multimasks -out /content/drive/MyDrive/RAMP_HOME/ramp-data/TRAIN/tiny_aoi/polygons