Skip to content

Command line interface

Jump to bottom
Joe Futrelle edited this page Aug 10, 2015 · 28 revisions

Overview

The command-line interface (CLI) provides an interactive means of loading data and metadata into the database, managing data and metadata, running queries, and exporting query results to files.

Quickstart

For details on installation, see Installation.

When you start for the first time, the CLI will create the necessary database structures and tables to hold your data. These will be used to hold the contents of the database so that you can run the CLI again and you won't have to re-load your data each time.

Upon starting, the CLI will give a short message, and then you will be at a prompt that looks like this. This prompt indicates that the CLI is ready for a command.

domdb>

Commands

add

Add an experiment to the database. Three parameters must be provided:

  1. The (short) name you want to give the experiment. No spaces are allowed. Do not use quotation marks or other punctuation.
  2. The pathname of a CSV file containing metabolite data for an experiment
  3. The pathname of a CSV file containing experiment metadata

For example:

domdb> add tps4 data/Tps4_pos_2014.05.23.csv metadata/Tps4_metadata.csv
loading experiment tps4 from:
data file data/Tps4_pos_2014.05.23.csv
metadata file metadata/Tps4_metadata.csv
loading tps4 metadata from metadata/Tps4_metadata.csv
17 total samples loaded, 0 ignored
loading tps4 metabolite data from data/Tps4_pos_2014.05.23.csv
loaded 1000 metabolites so far
loaded 2000 metabolites so far
loaded 3000 metabolites so far
loaded 4000 metabolites so far
loaded 5000 metabolites so far
loaded 6000 metabolites so far
loaded 6047 total metabolites
12700 metabolites in database

Attempting to add an experiment more than once will result in an error.

Adding an experiment is "persistent", which means that every time you start the CLI, the data that you added in earlier sessions (and did not subsequently remove) will still be accessible and does not need to be re-added.

If you interrupt an add operation (e.g., by hitting Ctrl-C) before it completes, the experiment will only be partially loaded into the database. In that case, enter the CLI again and remove the experiment, as described below, before attempting to re-add it.

list

List all experiments in the database. Shows the number of samples and metabolites in each experiment. For example:

domdb> list
+------+---------+-------------+
| name | samples | metabolites |
+------+---------+-------------+
| tps4 | 36      | 5484        |
| tps6 | 28      | 6988        |
+------+---------+-------------+

samples

List the samples from an experiment, and their attributes

One parameter is required; the name of the experiment.

For example:

domdb> samples tps4
+-------------------+---------+--------+------------+------+------------+
| name              | control | ignore | sampleType | time | treatment  |
+-------------------+---------+--------+------------+------+------------+
| Mtab_FT_012611_07 | 0       | 0      | PPL        | t2   | withTps    |
| Mtab_FT_012611_08 | 1       | 0      | PPL        | t2   | withoutTps |
| Mtab_FT_012611_09 | 0       | 0      | PPL        | t2   | withTps    |
| Mtab_FT_012611_10 | 0       | 0      | mtab       | t2   | withTps    |
...
| Mtab_FT_020311_21 | 0       | 0      | PPL        | t6   | withTps    |
| Mtab_FT_020311_23 | 0       | 0      | mtab       | t6   | withTps    |
| Mtab_FT_020311_25 | 1       | 0      | mtab       | t6   | withoutTps |
| Mtab_FT_020311_27 | 0       | 0      | mtab       | t6   | withTps    |
+-------------------+---------+--------+------------+------+------------+

remove

Remove an experiment from the database

One parameter is required; the short name that you gave the experiment when you added it. After successfully removing the experiment, the command will list the remaining experiments:

domdb> remove tps4
Removing all tps4 data ...
+------+---------+-------------+
| name | samples | metabolites |
+------+---------+-------------+
| tps6 | 28      | 6988        |
+------+---------+-------------+

dir

Show all experiment data in a directory. The single parameter is the name of the directory.

domdb> dir ./LCdata/neg
found files for 3 experiments in ./LCdata/neg
+----------+----------------------------------------------+---------------------------+
| name     | data                                         | metadata                  |
+----------+----------------------------------------------+---------------------------+
| tps4     | Tps4_neg_withAddedDetails.2015.02.05.csv     | Tps4_neg_metadata.csv     |
| rpom3ext | Rpom3ext_neg_withAddedDetails.2015.02.16.csv | Rpom3ext_neg_metadata.csv |
| tps6     | Tps6_neg_withAddedDetails.2015.02.05.csv     | Tps6_neg_metadata.csv     |
+----------+----------------------------------------------+---------------------------+

add_dir

Add all experiment data found in a given directory. The single parameter is the name of the directory.

domdb> add_dir ./LCdata/neg/
found files for 3 experiments in ./LCdata/neg/
loading experiment tps4 from:
- data file ./LCdata/neg/Tps4_neg_withAddedDetails.2015.02.05.csv
- metadata file ./LCdata/neg/Tps4_neg_metadata.csv
loading tps4 metadata from ./LCdata/neg/Tps4_neg_metadata.csv
36 total samples loaded, 0 ignored
loading tps4 metabolite data from ./LCdata/neg/Tps4_neg_withAddedDetails.2015.02.05.csv
loaded 1000 metabolites so far
loaded 2000 metabolites so far
loaded 3000 metabolites so far
...
loaded 5484 total metabolites
5484 metabolites in database
loading experiment rpom3ext from:
- data file ./LCdata/neg/Rpom3ext_neg_withAddedDetails.2015.02.16.csv
- metadata file ./LCdata/neg/Rpom3ext_neg_metadata.csv
loading rpom3ext metadata from ./LCdata/neg/Rpom3ext_neg_metadata.csv
30 total samples loaded, 15 ignored
loading rpom3ext metabolite data from ./LCdata/neg/Rpom3ext_neg_withAddedDetails.2015.02.16.csv
loaded 1000 metabolites so far
loaded 2000 metabolites so far
loaded 3000 metabolites so far
...
loaded 12000 metabolites so far
loaded 13000 metabolites so far
loaded 13543 total metabolites
19027 metabolites in database
loading experiment tps6 from:
- data file ./LCdata/neg/Tps6_neg_withAddedDetails.2015.02.05.csv
- metadata file ./LCdata/neg/Tps6_neg_metadata.csv
loading tps6 metadata from ./LCdata/neg/Tps6_neg_metadata.csv
28 total samples loaded, 0 ignored
loading tps6 metabolite data from ./LCdata/neg/Tps6_neg_withAddedDetails.2015.02.05.csv
loaded 1000 metabolites so far
loaded 2000 metabolites so far
...
loaded 6000 metabolites so far
loaded 6988 total metabolites
26015 metabolites in database

search

Search for all metabolites matching a given m/z and retention time. The three parameters are, in order

  1. m/z ratio
  2. retention time
  3. output filename (optional)
domdb> search 974.8119 80 search1.csv
domdb>

set

View and change user-configurable parameters. Currently-available parameters are:

  1. attrs - sample attributes to use for control exclusion
  2. exclude_controls - whether or not to exclude controls
  3. int_over_controls - include in results only when metabolite intensity is this many times greater than its intensity in controls
  4. ppm_diff - match window for m/z ratio in parts per million
  5. rt_diff - match window for retention time in seconds
  6. with_ms2 - whether to limit results to features with ms2 available

With no parameters, set shows the current values of all parameters (defaults are shown below):

domdb> set
+-------------------+-------+
| var               | value |
+-------------------+-------+
| attrs             |       |
| exclude_controls  | True  |
| int_over_controls | None  |
| ppm_diff          | 0.5   |
| rt_diff           | 30    |
| with_ms2          | False |
+-------------------+-------+

With two parameters, set allows you to set a parameter to a new value:

domdb> set rt_diff 40
+-------------------+-------+
| var               | value |
+-------------------+-------+
| attrs             |       |
| exclude_controls  | True  |
| int_over_controls | None  |
| ppm_diff          | 0.5   |
| rt_diff           | 40    |
| with_ms2          | False |
+-------------------+-------+

When setting the attrs parameter, you can set multiple attributes. They should be separated by a comma with no spaces, like this:

domdb> set attrs media,time
+-------------------+------------+
| var               | value      |
+-------------------+------------+
| attrs             | media,time |
| exclude_controls  | True       |
| int_over_controls | 10.0       |
| ppm_diff          | 0.5        |
| rt_diff           | 30         |
| with_ms2          | False      |
+-------------------+------------+

Parameters affect the behavior of any relevant, subsequent command. They are retained when you exit the CLI and will have the same values when you re-enter the CLI. To reset them to default values, use the reset command; see below.

reset

Reset all query parameters to default values.

domdb> reset
+-------------------+-------+
| var               | value |
+-------------------+-------+
| attrs             |       |
| exclude_controls  | True  |
| int_over_controls | None  |
| ppm_diff          | 0.5   |
| rt_diff           | 30    |
| with_ms2          | False |
+-------------------+-------+

match

Search for matches from all metabolites from a given experiment. The two parameters are:

  1. the short name of the experiment whose metabolites you want to match against the rest of the database, and
  2. the name of a CSV file to write the output to (the file should not exist--it will be created. if it does exist it will be overwritten)

Note that this command may take a very long time to complete, especially if there are many experiments in the database.

For example:

domdb> match tps4 t4_matches.csv
domdb>

exit

Exit the CLI.

Usage notes

If you make a mistake typing a command, sometimes the CLI will crash. This will not negatively affect your data.

Clone this wiki locally