Exporting Data to Files¶
You can use the immunedb_export command to export your data in a variety of
formats.
Exporting Samples¶
To export samples statistics run the command:
$ immunedb_export PATH_TO_CONFIG samples
After completion, a TSV file samples.tsv will be written with the following
headers, one line per sample:
| Field | Description |
|---|---|
id |
Unique numeric sample identifier |
name |
Name given to the sample |
subject |
Subject from which the sample originated |
input_sequences |
Reads input into ImmuneDB |
identified |
Reads successfully annotated |
in_frame |
Reads in-frame |
stops |
Reads with stop codons |
functional |
Functional reads (in-frame and no stop codons) |
avg_clone_cdr3_num_nts |
Average clonal CDR3 length in nucleotides |
avg_clone_v_identity |
Average clonal V-region identity |
clones |
Total number of clones |
Exporting Clones¶
In it’s most basic form, the command to export clones is:
$ immunedb_export PATH_TO_CONFIG clones
This will generate one file per sample each with one line per clone having the
fields below. Note that intances, copies, avg_v_identity, and
top_copy_seq are for the clone in the context of that sample. That is,
those fields may vary for the same clone in different samples.
| Field | Description |
|---|---|
clone_id |
Database-wide unique clone identifier. This number can be used to track clones across samples. |
subject |
Subject in which the clone was found |
v_gene |
V-gene of the clone |
j_gene |
J-gene of the clone |
functional |
If the clone is in-frame and contains no stop
in the consensus (T or F) |
insertions |
Insertions in the clone (deprecated) |
deletions |
Deletions in the clone (deprecated) |
cdr3_nt |
CDR3 nucleotide sequence |
cdr3_num_nts |
CDR3 nucleotide sequence length |
cdr3_aa |
CDR3 amino-acid sequence |
uniques |
Unique sequences in the clone overall |
instances |
Sequences instances in the clone in the associated sample |
copies |
Copies in the clone in the associated sample |
germline |
Clonal germline sequence |
parent_id |
Parent ID (deprecated) |
avg_v_identity |
Average V-gene identity to germline |
top_copy_seq |
Nucleotide sequence of top-copy sequence |
The --pool-on parameter can be used to change how data is aggregated. By
default it takes the value sample (as described above) but it also accepts,
subject, or any custom metadata field(s).
For the purposes of illustration, assume we have samples with the associated metadata below.
| sample | subject | tissue | subset |
|---|---|---|---|
| sample1 | S1 | blood | naive |
| sample2 | S1 | spleen | naive |
| sample3 | S1 | spleen | mature |
| sample4 | S3 | blood | native |
Passing --pool-on subject will generate one file per subject with the clone
information aggregated across all samples in that subject. Alternatively,
passing --pool-on tissue will generate one file per subject/tissue
combination. You can pass multiple metadata fields to the --pool-on
parameter as well. For example --pool-on tissue subset will generate one
file per subject/tissue/subset combination.
Two other common parameters are --sample-ids which restricts which samples
to include in the export and --format which accepts immunedb (the
default) or vdjtools for interoperability with the VDJtools suite.
Exporting Sequences¶
Sequences can be exported in Change-O and AIRR formats.
The basic command is:
$ immunedb_export PATH_TO_CONFIG sequences
This will generate one file per sample in Change-O format. To use AIRR format,
specify --format airr. You can filter out sequences that were not
assigned to a clone with the --clones-only flag.
Exporting Selection Pressure¶
If selection pressure was calculated with the immunedb_clone_pressure
command, the results can be exported in TSV format, one row per clone/sample
combination. Additionally, unless the --filter samples is passed, there
will be one additional row per clone with a All Samples value for the
sample which indicates the overall selection pressure on the clone.
For more information on interpreting the values see Uduman, et al, 2011 and Yaari, et al. 2012.
| Field | Value |
|---|---|
clone_id |
Clone ID |
subject |
Subject to which the clone belongs |
sample |
Sample within which the selection pressure was
calculated. If All Samples the overall selection
pressure for the clone. |
threshold |
The threshold at which the selection pressure was calculated |
expected_REGION_TYPE |
The expected number of TYPE (r or s)
mutations in REGION (cdr or fwr) |
observed_REGION_TYPE |
The observed number of TYPE (r or s)
mutations in REGION (cdr or fwr) |
sigma_REGION |
The selection pressure in REGION |
sigma_REGION_cilower |
The lower bound of the confidence interval of
selection in REGION |
sigma_REGION_ciupper |
The upper bound of the confidence interval of
selection in REGION |
sigma_p_REGION |
The P-value of the selection in REGION |
Exporting MySQL Data¶
The final method of exporting data is to dump the entire MySQL database to a file. This is meant to be a backup method rather than for downstream-analysis.
To backup run:
$ immunedb_admin backup PATH_TO_CONFIG BACKUP_PATH
To restore a backup run:
$ immunedb_admin restore PATH_TO_CONFIG BACKUP_PATH