Updated for version: 1.3.59
Command line (CLI) bindings for Basepair's API. The CLI bindings are just a wrapper around the Python bindings, which are more fully featured. So if there is something you cannot do via the command line, then check out the Python API. An outline of the contents on this page:
- Setup
- Installation
- Setup your configuation
- Examples
- Listing available data
- Creating or deleting a sample
- Create an analysis
- Download results
Setup
1.0 Requirements
Requires Python version 3. We no longer support Python 2.
1.1 Installation:
You need to first install the basepair Python package. If you don't have pip, you can get it here.
pip install basepair
Once you have it installed you should have available to you at the command line the "basepair" tool. Try running the following in your terminal:
basepair -h
1.2 Configuration:
Step 1
You need to obtain your configuration file to connect to Basepair's API. To obtain the file:
- Go to your Basepair dashboard: https://app.basepairtech.com
- Click on your profile name in the top right corner.
- Click on "Profile".
- Click on "Download API config file" in the upper right corner.
When you do get your configuration file it should look like the following:
{
"api": {
"host": "https://app.basepairtech.com/",
"prefix": "api/v1/",
"username": "user@basepairtech.com",
"api_key": ""
},
"aws": {
"s3": {
"bucket": "basepair"
},
"aws_id": "",
"aws_secret": ""
}
}The "api_key", "aws_id", and "aws_secret" are codes unique to your account and allow you to access Basepair and your data.
Step 2
Then to make this file available to your API calls you can do one of the following:
Option 1: Define an environment variable
export BP_CONFIG_FILE=/path/to/basepair.config.json
Option 2: Give it as a parameter when calling basepair:
basepair --config /path/to/basepair.config.json
Examples
1. Listing available data
You can list various types of data available to you. By default the "basepair list" command prints data in a human-readable table format, which does not all data associated with each item, only the critical data. If you want to see all data associated with each item then include the "--json" flag.
1.1 List genomes
The following will print the genomes available:
basepair list genomes -c basepair.config.json
Which will output the following:
id name date_created ---- ----------------------- -------------------------- 1 hg19 2018-04-18T14:58:15.865993 2 mm10 2018-04-18T15:05:39.770488 3 mm9 2018-04-18T15:10:33.438603 4 danRer10 2018-04-18T15:15:11.281866 5 tair10 2018-04-18T15:17:19.582104 6 dm6 2018-04-18T15:23:27.298556 7 danRer7 2018-04-18T15:28:12.977544 8 sacCer3 2018-04-18T15:30:50.993198 9 SL2.40 2018-04-18T15:31:50.603006 10 Xla.v91 2018-04-18T15:36:55.491452 11 xenTro7 2018-04-18T15:43:42.386466 12 taeGut2 2018-04-18T15:44:56.550366 13 Streptococcus_sanguinis 2018-04-18T15:45:06.695995 14 CENPK113-7D-RP 2018-04-18T15:45:26.305311 15 rn6 2018-04-18T15:46:13.155202 16 susScr11 2018-04-18T15:48:53.443899 17 ce11 2018-04-18T15:49:32.644737 18 Manis_javanica 2018-04-18T16:09:05.805615 19 Ictalurus_punctatus 2018-04-18T16:16:12.306990 20 mouse_GRCm38_M18 2018-10-04T15:40:16.284047 21 Citrus_clementina.v1 2018-10-04T15:46:23.320161 22 Nematostella_vectensis 2018-10-26T18:06:36.340901 23 Gallus_gallus 2018-10-30T14:02:58.811138
1.2 List your analyses
You can list out all the analyses that you have done. This can be useful for getting the analysis' ids (for download), total file size, and more.
basepair list analyses \
-c basepair.config.json 1.3 List files for an analysis
To see what files are in a specific analysis you can run the code below. This can be useful for when you want to download an analysis but you only want certain files, which you can do by providing specific tags to filter the files by.
basepair list analysis \
-c config.json \
-u 16146Which will output something like this:
id: 16146 name: DNA-Seq QC, Alignment (BWA) on Modified Genome 1 date_created: 2017-11-30T15:59:35.436706 completed_on: 2017-12-01T04:01:16.461192 sample ids: 12318 Files id filesize (Gigabytes) source name tags ------ ---------------------- ----------------- ------------------------------------------------- ------------------------------------------- 218373 0.0000 FastQC Modified_Genome_1.pe.per-base-quality.png ['fastqc', 'per_base', 'figure', 'pe'] 218369 0.0000 FastQC Modified_Genome_1.overrepresented.json ['fastqc', 'overrepresented', 'json'] 218549 0.0000 Coverage Modified_Genome_1.hg19.dedup.coverage-plot.png ['coverage', 'plot'] 218548 0.0001 Coverage Modified_Genome_1.hg19.dedup.coverage-summary.xls ['coverage', 'report'] 218547 0.0082 Remove duplicates Modified_Genome_1.hg19.dedup.bam.bai ['bai', 'dedup'] 218546 43.6390 Remove duplicates Modified_Genome_1.hg19.dedup.bam ['bam', 'dedup'] 218545 0.0000 Summary Modified_Genome_1.hg19.alignment-summary.png ['alignment_summary', 'figure'] 218527 0.0000 BWA Modified_Genome_1.hg19.alignment-summary.json ['alignment_summary', 'json'] 218529 0.0000 BWA Modified_Genome_1.hg19.alignment-summary.txt ['alignment_summary', 'text'] 218530 0.0082 BWA Modified_Genome_1.hg19.bam.bai ['bai'] 218528 56.5115 BWA Modified_Genome_1.hg19.bam ['bam'] 218371 0.0000 FastQC Modified_Genome_1.pe.overrepresented.json ['fastqc', 'overrepresented', 'json', 'pe'] 218372 0.0001 FastQC Modified_Genome_1_fastqc.zip ['fastqc', 'zip'] 218370 0.0001 FastQC Modified_Genome_1.pe_fastqc.zip ['fastqc', 'zip', 'pe'] 218368 0.0000 FastQC Modified_Genome_1.per-base-quality.png ['fastqc', 'per_base', 'figure']
1.4 Other things to list
A few other things you can do include printing out workflows available and your samples:
basepair list workflow -c basepair.config.json basepair list samples -c basepair.config.json
2. Creating or deleting a sample
The following creates a sample named "test" that consists of a paired-end RNA-seq dataset from human (hg19).
basepair create sample \
-c basepair.config.json \
--name Sample1 \
--genome hg19 \
--datatype rna-seq \
--file1 reads_1.fq \
--file2 reads_2.fqRunning the above command will upload your samples and will print out ids for your sample and files. Here is the output from the above command:
created: sample with id 19377 created: upload with id 33355 created: upload with id 33356
You can also delete a sample:
basepair delete \
-c basepair.config.json \
-t sample \
-s 193773. Create an analysis
**WARNING: This section and code to do this are still under construction.***
You can also create and submit an analysis. At a minimum you need to specify the workflow id and sample id(s). The example below creates read mapping and expression quantification (STAR) for the sample we just submitted:
basepair create analysis \
-c basepair.config.json \
--w 4 \
--sample {{sample_id}}Which will output something like this:
created: analysis 3213 with sample 19377
You can run an analysis with custom parameters like this:
basepair create analysis
--w 5
--sample {{sample_id}}
--params annotate:upstream:5000 annotate:downstream:5000In the above command, each parameter is of the format <module>:<variable>:<value>
4. Download results
4.1 Download all analysis files
If you want to download all files for the analysis with id 28683 you can run the following:
basepair download analysis \
-c basepair.config.json \
-u {{analysis_id}} \
-o ./output4.2 Download certain analysis files
You can also filter the files you want to download using the --tags and --tagkind options. To see what tags are associated with each file, run the "bp list -t analysis -u (analysis_id) " command (an example is at the beginning of this page).
For example, if you want to exclude bam files:
basepair download analysis \
-c basepair.config.json \
--tags bam \
--tagkind diff \
-u {{analysis_id}} \
-o ./outputIf you want only files that exactly match two tags:
basepair download analysis \
-c basepair.config.json \
--tags tag1 tag2 \
--tagkind exact \
-u {{analysis_id}} \
-o ./outputIf you want any files that have a particular tag:
basepair download analysis \
-c basepair.config.json \
--tags tag1 \
--tagkind subset \
-u {{analysis_id}} \
-o ./outputIf you want only files that exactly match one of two sets of tags:
basepair download analysis \
-c basepair.config.json \
--tags tag1 tag2 \
--tags tag3 tag4 \
--tagkind exact \
-u {{analysis_id}} \
-o ./output
4.2 Download a sample's raw files
If you want to download the FASTQ files for your sample:
basepair download sample \
-c basepair.config.json \
-u {{sample_id}}