@salk-hpi/bloom-cli #

A Command-Line Interface (CLI) for the Bloom data management system.

oclif

Introduction #

Bloom CLI lets you interact with Bloom data programmatically from any computer.

You can do things like:

  • Add new species
  • Add new experiments
  • Upload new plant images for a specific experiment
  • Compute quantitative traits from images
  • Download trait data

Most data on Bloom is private, so you’ll need a Bloom account. To sign up for an account, visit the Bloom web app.

Some (but not all) of the functionality of the CLI is also available through the Bloom web app. If you’re not sure whether you want to install the CLI, try exploring the web app first.

Installation #

Bloom CLI works on any system that can run Node.js - including Windows, Mac, and Linux.

On Windows, we recommend using the Windows Subsystem for Linux (WSL), also known as the Ubuntu app. If you don’t have that installed, first do that. Then follow the remaining instructions below.

Prerequisites #

The only prerequisite for Bloom CLI is Node.js version >18.0. If you already have Node installed, you can skip ahead to Installing the Bloom CLI.

We recommend installing Node using the version management tool nvm. On Mac, Linux, or the Windows Ubuntu app, you can install nvm by running:

wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash

Close the terminal and open a new one to enable nvm. Then run:

nvm install node

You should now have Node installed. Check this by running node --version (version should be >18.0).

Installing the Bloom CLI #

Once you have Node on your machine, installation is as simple as running:

npm config set @salk-hpi:registry=https://gitlab.com/api/v4/projects/48311510/packages/npm/ && \
npm install -g @salk-hpi/bloom-cli

You can test whether the Bloom was successfully installed by running:

bloom help

If the installation commands fail, it might mean that your machine is missing Node and you’ll need to install it (see Preqrequisites)

Signing up #

To sign up for a Bloom account, visit the Bloom web app.

To interact with Bloom from the command line interface, you’ll need to log in by running:

bloom login

Usage #

Run the bloom command to get a list of topics and commands.

$ bloom
CLI for the Bloom data management system

VERSION
  @salk-hpi/bloom-cli/0.0.0 darwin-arm64 node-v18.12.1

USAGE
  $ bloom [COMMAND]

TOPICS
  cyl      Manage cylinder scans
  species  Manage species data
...

COMMANDS
  autocomplete  display autocomplete installation instructions
  commands      list all the commands
  help          Display help for bloom.
...

To list the commands within a topic, run bloom [TOPIC].

$ bloom cyl
Manage cylinder scans

USAGE
  $ bloom cyl COMMAND

COMMANDS
  cyl upload    upload cylinder scans
  cyl validate  validate cylinder scans
...

To run a command within a topic, run bloom [TOPIC] [COMMAND].

$ bloom cyl validate
Running command...

To list all commands from all topics, run bloom commands.

$ bloom commands
 Command        Summary
 ────────────── ──────────────────────────────────────────────
 autocomplete   display autocomplete installation instructions
 commands       list all the commands
 cyl upload     upload cylinder scans
 cyl preview    preview cylinder scans
...

You can also explore the available topics and commands by following the links below.

Cylinder Tutorial #

In this tutorial, we’ll go through a common use case: uploading cylinder scans to Bloom.

Step 1: Signing up (one time only) #

Sign up for a Bloom account on the Bloom web app if you haven’t already done so.

Step 2: Logging in (one time only) #

Log in from the command-line interface by running:

bloom login

You’ll be asked to enter the email address and password for the Bloom account you created in Step 1.

Step 3: Initializing a cylinder experiment (one time only) #

Let’s say you have a cylinder experiment located in a file structure that looks like this:

CYL_Diversity_Screen/
|-- Images/
|   |-- Raw_Images/
|   |   |-- W23/
|   |   |   |-- GermDay1Purple/
|   |   |   |   |-- Day0_4-18-2023FastScanner/
|   |   |   |   |   |-- MK7KSFYU47/
|   |   |   |   |   |   |-- 1.png
|   |   |   |   |   |   |-- ...
|-- Experimental_Design/
|   |-- Master_Data/
|   |   |-- Canola_Diversity_Screen_Master_Data.xlsx

To upload this data to Bloom, you start by initializing the experiment with the bloom cyl init command:

bloom cyl init CYL_Diversity_Screen/

You will be led through a series of prompts that ask you for these fields:

  • The species of the experiment
  • The name of the experiment
  • The spreadsheet containing the barcode and accession (line) name for each of your plants
  • The sheet in the spreadsheet that contains the plant barcodes & accession names
  • The column in the spreadsheet that contains the plant barcodes
  • The column in the spreadsheet that contains the accession names

After running the bloom cyl init command, you should have a extra file called “cyl-metadata.yml” in the experiment’s root directory:

CYL_Diversity_Screen/
|-- cyl-metadata.yml
|-- Images/
|   |-- ...
|-- Experimental_Design/
|   |-- ...

You will then need to edit cyl-metadata.yml and specify the metadata format for your experiment. In this example, you would change the line that starts with path_format_string: so that it looks like this:

path_format_string: Images/Raw_Images/W<wave_number>/GermDay<germ_day><germ_day_color>/Day<plant_age_days>_<date_scanned><device_name>/<plant_qr_code>/<frame_number>.png

Note: Do not just copy and paste the string above. This string depends on your particular file structure.

Step 4: Previewing cylinder data before uploading #

To check that the metadata will be extracted correctly from the file names, you can run:

bloom cyl preview CYL_Diversity_Screen/

You should see results that looks something like this:

 Num images      1152
 Num plants      4
 Plants          [ '3ZVPIFFYQK', 'MK7KSFYU47', 'WTLOFH46IS', 'ZIUEPX61J0' ]
 Accessions      [ 'Aspen', 'Buk Wuk 20', 'Westar', 'Wichita' ]
 Wave numbers    [ 23 ]
 Germ days       [ 1, 2 ]
 Germ day colors [ 'Orange', 'Purple' ]
 Plant ages      [ 0, 2, 7, 9 ]
 Scan dates      [ '2023-04-18', '2023-04-19', '2023-04-20', '2023-04-21', '2023-04-25', '2023-04-26', '2023-04-27', '2023-04-28' ]
 Device names    [ 'FastScanner', 'SlowScanner' ]

Note that you may get errors at this stage if you have not written the path_format_string correctly, or if your cylinder scan filename contain typos. You may have to go through several iterations of fixing both before preview gives reasonable results.

If you only want to preview some of your cylinder data, you can call the preview command with a subdirectory:

bloom cyl preview CYL_Diversity_Screen/Images/Raw_Images/W23/GermDay1Purple/Day0_4-18-2023FastScanner/

Step 5: Uploading cylinder data #

When you’re ready to upload your data to . Just run:

bloom cyl upload CYL_Diversity_Screen/

Similar to the preview command, if you only want to upload some of your cylinder data, you can call the upload command with a subdirectory:

bloom cyl upload CYL_Diversity_Screen/Images/Raw_Images/W23/GermDay1Purple/Day0_4-18-2023FastScanner/

Bloom is smart enough not to upload the same images twice. Therefore, you can safely kill the upload command at any time and run it again later. It will skip any images that have already been uploaded.

Command Topics #