ramp v1.0.0
DOCUMENTATION
ToC
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.
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.
Go to the Google Colab website.
IMPORTANT NOTE
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
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.
Navigate to RAMP_HOME, and create another new folder named “ramp-data”.
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.
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.
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.
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:
python
>> import ramp
If *import ramp* runs successfully, you have installed the ramp modules.
In Jupyterlab, open and run the Colab model training notebook: `train_ramp_model_on_colab.ipynb`.
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
IMPORTANT NOTE
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
Spanning Africa, India, and the United States, DevGlobal Partners supports the world’s leading non-profits, companies, philanthropies, multilateral agencies, and government agencies on their innovation and sustainability initiatives
As a constantly growing team, we are always looking for new and diverse talent to expand and strengthen our capabilities.
If you are interested in learning about more ways to contribute please visit our “Careers” page using the button below.
info@dev.global
(425) 448-2658
123 2nd Ave S suite 230 #18
Edmonds, WA 98020