DeepBlue (1.18.11) Reference API

DeepBlue operations

Annotations - Inserting and listing annotations

add_annotation

Add a custom annotation of genomic regions. Annotations are a set genomic regions such as CpG Islands and repetitive elements.

add_annotation ( name, genome, description, data, format, extra_metadata, user_key )

Parameters:

name(string) — annotation name
genome(string) — the target genome
description(string) — description of the annotation
data(string) — the BED formatted data
format(string) — format of the provided data
extra_metadata(struct) — additional metadata
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the newly inserted annotation

['error', error_message] — Error. Verify the error message.

find_motif

Find genomic regions based on a given motif that appears in the genomic sequence.

find_motif ( motif, genome, chromosomes, start, end, overlap, user_key )

Parameters:

motif(string) — motif (PERL regular expression)
genome(string) — the target genome
chromosomes(string) — chromosome name(s)
start(int) — minimum start region
end(int) — maximum end region
overlap(boolean) — if the matching should do overlap search
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the annotation that contains the positions of the given motif

['error', error_message] — Error. Verify the error message.

list_annotations

List all annotations of genomic regions currently available in DeepBlue.

list_annotations ( genome, user_key )

Parameters:

genome(string) — the target genome
user_key(string) — users token key

Response:

['okay', result] — result consists of

annotations(array) — annotations names and IDs

['error', error_message] — Error. Verify the error message.

BioSources - Inserting and listing biosources

add_biosource

Add a BioSource to DeepBlue. A BioSource refers to a term describing the origin of a given sample, such as a tissue or cell line.

add_biosource ( name, description, extra_metadata, user_key )

Parameters:

name(string) — biosource name
description(string) — description of the biosource
extra_metadata(struct) — additional metadata
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the newly inserted biosource

['error', error_message] — Error. Verify the error message.

list_biosources

List BioSources included in DeepBlue. A BioSource refers to a term describing the origin of a given sample, such as a tissue or cell line. It is possible to filter the BioSources by their extra_metadata fields content. These fields vary depending on the original data source.

list_biosources ( extra_metadata, user_key )

Parameters:

extra_metadata(struct) — Metadata that must be matched
user_key(string) — users token key

Response:

['okay', result] — result consists of

biosources(array) — biosources names and IDS

['error', error_message] — Error. Verify the error message.

list_similar_biosources

List all BioSources that have a similar name compared to the provided name. A BioSource refers to a term describing the origin of a given sample, such as a tissue or cell line. The similarity is calculated using the Levenshtein method.

list_similar_biosources ( name, user_key )

Parameters:

name(string) — biosource name
user_key(string) — users token key

Response:

['okay', result] — result consists of

biosource(string) — biosource name

['error', error_message] — Error. Verify the error message.

BioSources relationship - Set the relationship between different biosources

create_experiments_set

Create a set of experiments to be shared among others users

create_experiments_set ( name, description, public, experiment_name, user_key )

Parameters:

name(string) — experiments set name
description(string) — experiments set description
public(boolean) — True is others users can access this list
experiment_name(string) — name(s) of selected experiment(s)
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the experiments set

['error', error_message] — Error. Verify the error message.

get_biosource_children

A BioSource refers to a term describing the origin of a given sample, such as a tissue or cell line. These form a hierarchy in which children of a BioSource term can be fetched with this command. Children terms are more specific terms that are defined in the imported ontologies.

get_biosource_children ( biosource, user_key )

Parameters:

biosource(string) — biosource name
user_key(string) — users token key

Response:

['okay', result] — result consists of

biosources(array) — related biosources

['error', error_message] — Error. Verify the error message.

get_biosource_parents

A BioSource refers to a term describing the origin of a given sample, such as a tissue or cell line. These form a hierarchy in which the parent of a BioSource term can be fetched with this command. Parent terms are more generic terms that are defined in the imported ontologies.

get_biosource_parents ( biosource, user_key )

Parameters:

biosource(string) — biosource name
user_key(string) — users token key

Response:

['okay', result] — result consists of

biosources(array) — parents biosources

['error', error_message] — Error. Verify the error message.

get_biosource_related

A BioSource refers to a term describing the origin of a given sample, such as a tissue or cell line. These form a hierarchy in which the children of a BioSource term and its synonyms can be fetched with this command. Children terms are more specific terms that are defined in the imported ontologies. Synonyms are different aliases for the same biosource.

get_biosource_related ( biosource, user_key )

Parameters:

biosource(string) — biosource name
user_key(string) — users token key

Response:

['okay', result] — result consists of

biosources(array) — related biosources

['error', error_message] — Error. Verify the error message.

get_biosource_synonyms

Obtain the synonyms of the specified biosource. Synonyms are different aliases for the same biosource. A BioSource refers to a term describing the origin of a given sample, such as a tissue or cell line.

get_biosource_synonyms ( biosource, user_key )

Parameters:

biosource(string) — name of the biosource
user_key(string) — users token key

Response:

['okay', result] — result consists of

synonyms(array) — synonyms of the biosource

['error', error_message] — Error. Verify the error message.

set_biosource_parent

Define a BioSource as parent of another BioSource. This command is used to build the BioSources hierarchy. A BioSource refers to a term describing the origin of a given sample, such as a tissue or cell line.

set_biosource_parent ( parent, child, user_key )

Parameters:

parent(string) — parent
child(string) — child
user_key(string) — users token key

Response:

['okay', result] — result consists of

['error', error_message] — Error. Verify the error message.

set_biosource_synonym

Define a synonym for a BioSource. BioSources can have multiple synonyms. This command for can be used multiply to add several synonyms. A BioSource refers to a term describing the origin of a given sample, such as a tissue or cell line.

set_biosource_synonym ( biosource, synonym_name, user_key )

Parameters:

biosource(string) — biosource name
synonym_name(string) — name of the synonym
user_key(string) — users token key

Response:

['okay', result] — result consists of

synonym_name(string) — inserted synonym_name

['error', error_message] — Error. Verify the error message.

Column Types - Inserting and listing different column types

create_column_type_calculated

Create a calculated column type in DeepBlue.A calculated column can use existing columns and transform or summarize them through mathematical operations or string operations using the programming language LUA. Examples: the following 'code' parameter can be used to calculate the square root of the column VALUE: 'return math.sqrt(value_of('VALUE'))'. Another example is dividing the value of the column 'VALUE' by the region length: 'return value_of('VALUE') / (value_of('END') - value_of('END'))'.

create_column_type_calculated ( name, description, code, user_key )

Parameters:

name(string) — column type name
description(string) — description of the column type
code(string) — Lua code that will be executed
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the newly created column type

['error', error_message] — Error. Verify the error message.

create_column_type_category

Create a categoric column type in DeepBlue from a set of items. As example, the STRAND column is a category column that contain the items: '+', '-', and '.' .

create_column_type_category ( name, description, items, user_key )

Parameters:

name(string) — column type name
description(string) — description of the column type
items(string) — items that are accepted for this category set
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the newly created column type

['error', error_message] — Error. Verify the error message.

create_column_type_range

Create a range column type in DeepBlue. For example, a METHYLATION_BETA_VALUE column where accepted values are from 0.0 to 1.0 .

create_column_type_range ( name, description, minimum, maximum, user_key )

Parameters:

name(string) — column type name
description(string) — description of the column type
minimum(double) — minimum value for this range (inclusive)
maximum(double) — maximum value for this range (inclusive)
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the newly created column type

['error', error_message] — Error. Verify the error message.

create_column_type_simple

Create a simple column type (string, integer, double) in DeepBlue.

create_column_type_simple ( name, description, type, user_key )

Parameters:

name(string) — column type name
description(string) — description of the column type
type(string) — type of the column type (string, integer, double)
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the newly created column type

['error', error_message] — Error. Verify the error message.

list_column_types

Lists the ColumnTypes included in DeepBlue.

list_column_types ( user_key )

Parameters:

user_key(string) — users token key

Response:

['okay', result] — result consists of

column_types(array) — column types names and IDS

['error', error_message] — Error. Verify the error message.

Data Modification - Operations that modify the data content

change_extra_metadata

Modify the extra metadata content of experiments, annotations, biosources, and samples. Use this command with an extra metadata key without value for removing this key. Extra metadata fields are optional non-standardized fields that are created during the import process. Only files uploaded by the user can me modified. The command 'clone_dataset' must be used if the user wants to modify a files that does not belong to him.

change_extra_metadata ( id, key, value, user_key )

Parameters:

id(string) — id of the data
key(string) — extra_metadata key
value(string) — extra_metadata key (empty for delete this key)
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the modified data

['error', error_message] — Error. Verify the error message.

clone_dataset

Clone a dataset optionally changing its metadata and extra_metadata values. This command must be used in data curation because users do not have permission to change the metadata values of the Annotations and Experiments that were not uploaded by them.

clone_dataset

( dataset_id, new_name, new_epigenetic_mark, new_sample, new_technique, new_project, description, format, extra_metadata, user_key )

Parameters:

dataset_id(string) — ID of the dataset (experiment or annotation ID)
new_name(string) — New dataset name
new_epigenetic_mark(string) — New epigenetic mark
new_sample(string) — New sample ID
new_technique(string) — New technique
new_project(string) — New project
description(string) — description of the experiment - empty to copy from the cloned dataset
format(string) — format of the provided data - empty to copy from the cloned dataset
extra_metadata(struct) — additional metadata
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the new dataset

['error', error_message] — Error. Verify the error message.

Epigenetic marks - Inserting and listing epigenetic marks

add_epigenetic_mark

Include an Epigenetic Mark such as, for instance, a specific type of histone modification, in DeepBlue.

add_epigenetic_mark ( name, description, extra_metadata, user_key )

Parameters:

name(string) — name of the epigenetic mark
description(string) — description of the epigenetic mark
extra_metadata(struct) — additional metadata
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the newly inserted epigenetic mark

['error', error_message] — Error. Verify the error message.

list_epigenetic_marks

List Epigenetic Marks included in DeepBlue. This includes histone marks, DNA methylation, DNA sensitivity, etc. It is possible to filter the Epigenetic Marks by their extra_metadata field content.

list_epigenetic_marks ( extra_metadata, user_key )

Parameters:

extra_metadata(struct) — Metadata that must be matched
user_key(string) — users token key

Response:

['okay', result] — result consists of

epigenetic_marks(array) — epigenetic mark names and IDS

['error', error_message] — Error. Verify the error message.

list_similar_epigenetic_marks

List all Epigenetic Marks that have a similar name compared to the provided name. The similarity is calculated using the Levenshtein method.

list_similar_epigenetic_marks ( name, user_key )

Parameters:

name(string) — epigenetic mark name
user_key(string) — users token key

Response:

['okay', result] — result consists of

epigenetic_marks(array) — similar epigenetic mark names

['error', error_message] — Error. Verify the error message.

Experiments - Inserting and listing experiments

add_experiment

Add an Experiment in DeepBlue. An Experiment describes the characteristics of a specific Epigenetic Mark with respect to a single sample. The technology used and project must be informed as well. Extra metadata can be specified in addition to the mandatory meta information.

add_experiment ( name, genome, epigenetic_mark, sample, technique, project, description, data, format, extra_metadata, user_key )

Parameters:

name(string) — experiment name
genome(string) — the target genome
epigenetic_mark(string) — epigenetic mark of the experiment
sample(string) — id of the used sample
technique(string) — technique used by this experiment
project(string) — the project name
description(string) — description of the experiment
data(string) — the BED formated data
format(string) — format of the provided data
extra_metadata(struct) — additional metadata
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the newly inserted experiment

['error', error_message] — Error. Verify the error message.

collection_experiments_count

Count the number of experiments that match the selection criteria in each term of the selected controlled_vocabulary. The selection can be achieved through specifying a list of BioSources, experimental Techniques, Epigenetic Marks, Samples or Projects.

collection_experiments_count ( controlled_vocabulary, genome, type, epigenetic_mark, biosource, sample, technique, project, user_key )

Parameters:

controlled_vocabulary(string) — controlled vocabulary name
genome(string) — the target genome
type(string) — type of the experiment: peaks or signal
epigenetic_mark(string) — name(s) of selected epigenetic mark(s)
biosource(string) — name(s) of selected biosource(s)
sample(string) — id(s) of selected sample(s)
technique(string) — name(s) of selected technique(s)
project(string) — name(s) of selected projects
user_key(string) — users token key

Response:

['okay', result] — result consists of

terms(array) — controlled_vocabulary terms with count

['error', error_message] — Error. Verify the error message.

faceting_experiments

Summarize the controlled_vocabulary fields, from experiments that match the selection criteria. It is similar to the 'collection_experiments_count' command, but this command return the summarization for all controlled_vocabulary terms.

faceting_experiments ( genome, type, epigenetic_mark, biosource, sample, technique, project, user_key )

Parameters:

genome(string) — the target genome
type(string) — type of the experiment: peaks or signal
epigenetic_mark(string) — name(s) of selected epigenetic mark(s)
biosource(string) — name(s) of selected biosource(s)
sample(string) — id(s) of selected sample(s)
technique(string) — name(s) of selected technique(s)
project(string) — name(s) of selected projects
user_key(string) — users token key

Response:

['okay', result] — result consists of

faceting(struct) — Map with the mandatory fields of the experiments metadata, where each contains a list of terms that appears.

['error', error_message] — Error. Verify the error message.

list_experiments

List the DeepBlue Experiments that matches the search criteria defined by this command parameters.

list_experiments ( genome, type, epigenetic_mark, biosource, sample, technique, project, user_key )

Parameters:

genome(string) — the target genome
type(string) — type of the experiment: peaks or signal
epigenetic_mark(string) — name(s) of selected epigenetic mark(s)
biosource(string) — name(s) of selected biosource(s)
sample(string) — id(s) of selected sample(s)
technique(string) — name(s) of selected technique(s)
project(string) — name(s) of selected projects
user_key(string) — users token key

Response:

['okay', result] — result consists of

experiments(array) — experiment names and IDS

['error', error_message] — Error. Verify the error message.

list_recent_experiments

List the latest Experiments included in DeepBlue that match criteria defined in the parameters. The returned experiments are sorted by insertion date.

list_recent_experiments ( days, genome, epigenetic_mark, sample, technique, project, user_key )

Parameters:

days(double) — maximum days ago the experiments were added
genome(string) — the target genome
epigenetic_mark(string) — name(s) of selected epigenetic mark(s)
sample(string) — id(s) of selected sample(s)
technique(string) — name(s) of selected technique(es)
project(string) — name(s) of selected projects
user_key(string) — users token key

Response:

['okay', result] — result consists of

experiments(array) — names of recent experiments

['error', error_message] — Error. Verify the error message.

list_similar_experiments

List all Experiments that have a similar name compared to the provided name. The similarity is calculated using the Levenshtein method.

list_similar_experiments ( name, genome, user_key )

Parameters:

name(string) — experiment name
genome(string) — the target genome
user_key(string) — users token key

Response:

['okay', result] — result consists of

experiments(array) — similar experiment names

['error', error_message] — Error. Verify the error message.

preview_experiment

List the DeepBlue Experiments that matches the search criteria defined by this command parameters.

preview_experiment ( experiment_name, user_key )

Parameters:

experiment_name(string) — name(s) of selected experiment(s)
user_key(string) — users token key

Response:

['okay', result] — result consists of

experiment(string) — experiment's regions

['error', error_message] — Error. Verify the error message.

Expressions - Expression data

add_expression

Include Expression data in DeepBlue.

add_expression ( expression_type, sample_id, replica, data, format, project, extra_metadata, user_key )

Parameters:

expression_type(string) — expression type (supported: 'gene')
sample_id(string) — sample ID
replica(int) — replica count (use 0 if it is the single replica)
data(string) — the data in the right format
format(string) — cufflinks or grape2
project(string) — the project name
extra_metadata(struct) — additional metadata
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the newly inserted expression data

['error', error_message] — Error. Verify the error message.

list_expressions

List the Expression currently available in DeepBlue. A expression is a set of data with an identifier and an expression value.

list_expressions ( expression_type, sample_id, replica, project, user_key )

Parameters:

expression_type(string) — expression type (supported: 'gene')
sample_id(string) — sample ID(s)
replica(int) — replica(s)
project(string) — project(s) name
user_key(string) — users token key

Response:

['okay', result] — result consists of

expressions(array) — expressions names and IDS

['error', error_message] — Error. Verify the error message.

select_expressions

Select expressions (by their name or ID) as genomic regions from the specified model.

select_expressions ( expression_type, sample_ids, replicas, identifiers, projects, gene_model, user_key )

Parameters:

expression_type(string) — expression type (supported: 'gene')
sample_ids(string) — id(s) of selected sample(s)
replicas(int) — replica(s)
identifiers(string) — identifier(s) (for genes: ensembl ID or ENSB name).
projects(string) — projects(s)
gene_model(string) — gene model name
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — query id

['error', error_message] — Error. Verify the error message.

General Information - Commands for all types of data

cancel_request

Stop, cancel, and remove request data. The request processed data is remove if its processing was finished.

cancel_request ( id, user_key )

Parameters:

id(string) — Request ID to be canceled, stopped or removed.
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — ID of the canceled request

['error', error_message] — Error. Verify the error message.

info

Information about a DeepBlue data identifier (ID). Any DeepBlue data ID can be queried with this command. For example, it is possible to obtain all available information about an Experiment using its ID, to obtain the actual Request processing status or the information about a Sample. A user can obtain information about him- or herself using the value 'me' in the parameter 'id'. Multiple IDs can be queried in the same operation.

info ( id, user_key )

Parameters:

id(string) — ID or an array of IDs
user_key(string) — users token key

Response:

['okay', result] — result consists of

information(array) — List of Maps, where each map contains the info of an object.

['error', error_message] — Error. Verify the error message.

is_biosource

Verify if the name is an existing and valid DeepBlue BioSource name. A BioSource refers to a term describing the origin of a given sample, such as a tissue or cell line.

is_biosource ( biosource, user_key )

Parameters:

biosource(string) — biosource name
user_key(string) — users token key

Response:

['okay', result] — result consists of

information(string) — A string containing the biosource name

['error', error_message] — Error. Verify the error message.

list_in_use

List all terms used by the Experiments mandatory metadata that have at least one Experiment or Annotation using them.

list_in_use ( controlled_vocabulary, user_key )

Parameters:

controlled_vocabulary(string) — controlled vocabulary name
user_key(string) — users token key

Response:

['okay', result] — result consists of

terms(array) — controlled_vocabulary terms with count

['error', error_message] — Error. Verify the error message.

name_to_id

Obtain the data ID(s) from the informed data name(s).

name_to_id ( name, collection, user_key )

Parameters:

name(string) — ID or an array of IDs
collection(string) — Collection where the data name is in
user_key(string) — users token key

Response:

['okay', result] — result consists of

information(array) — List of IDs.

['error', error_message] — Error. Verify the error message.

remove

Remove a DeepBlue data by using its ID.

remove ( id, user_key )

Parameters:

id(string) — Data ID to be removed.
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the removed data

['error', error_message] — Error. Verify the error message.

search

Search all data of all types for the given keyword. A minus (-) character in front of a keyword searches for data without the given keyword. The search can be restricted to the following data types are: Annotations, Biosources, Column_types, Epigenetic_marks, Experiments, Genomes, Gene_models, Gene_expressions, Genes, Gene_ontology, Projects, Samples, Techniques, Tilings.

search ( keyword, type, user_key )

Parameters:

keyword(string) — keyword to search by
type(string) — type of data to search for - Annotations, Biosources, Column_types, Epigenetic_marks, Experiments, Genomes, Gene_models, Gene_expressions, Genes, Gene_ontology, Projects, Samples, Techniques, Tilings
user_key(string) — users token key

Response:

['okay', result] — result consists of

results(array) — search results as [id, name, type]

['error', error_message] — Error. Verify the error message.

Genes - Gene models and genes identifiers

add_gene_model

Include a Gene Model in DeepBlue. The data must be in the GTF format. Important: this command will include only the lines where the column 'feature' is 'genes'.

add_gene_model ( gene_model, genome, description, data, format, extra_metadata, user_key )

Parameters:

gene_model(string) — the gene model
genome(string) — the target genome
description(string) — description of the gene model
data(string) — data in the GTF format
format(string) — data format - currently, only the GTF format is supported.
extra_metadata(struct) — additional metadata
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the newly inserted gene model

['error', error_message] — Error. Verify the error message.

add_gene_ontology_term

Add a Gene Ontology Term to DeepBlue. A Gene Ontology Term refers to a term use to describe the genes functions.

add_gene_ontology_term ( go_id, go_label, description, namespace, user_key )

Parameters:

go_id(string) — GO identifier
go_label(string) — GO label
description(string) — description of the Gene Ontology Term
namespace(string) — term namespace: cellular component, biological process or molecular function
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the newly inserted Gene Ontology Term

['error', error_message] — Error. Verify the error message.

annotate_gene

Annotate a Gene with a Gene Ontology Term.

annotate_gene ( gene_ensb_id, go_term_id, user_key )

Parameters:

gene_ensb_id(string) — Gene ENSB ID (ENSGXXXXXXXXXXX identifier
go_term_id(string) — GO Term ID
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the newly inserted Gene Ontology Term

['error', error_message] — Error. Verify the error message.

count_gene_ontology_terms

Count how many times a GO term appears.

count_gene_ontology_terms ( genes, go_terms, chromosome, start, end, gene_model, user_key )

Parameters:

genes(string) — Name(s) or ENSEMBL ID (ENSGXXXXXXXXXXX.X ) of the gene(s).
go_terms(string) — gene ontology terms - ID or label
chromosome(string) — chromosome name(s)
start(int) — minimum start region
end(int) — maximum end region
gene_model(string) — the gene model
user_key(string) — users token key

Response:

['okay', result] — result consists of

faceting(struct) — Map with the mandatory fields of the experiments metadata, where each contains a list of terms that appears.

['error', error_message] — Error. Verify the error message.

list_gene_models

List all the Gene Models currently available in DeepBlue. A gene model is a set of genes usually imported from GENCODE. For example Gencode v22.

list_gene_models ( user_key )

Parameters:

user_key(string) — users token key

Response:

['okay', result] — result consists of

gene_models(array) — gene models names and IDS

['error', error_message] — Error. Verify the error message.

list_genes

List the Genes currently available in DeepBlue.

list_genes ( genes, go_terms, chromosome, start, end, gene_model, user_key )

Parameters:

genes(string) — Name(s) or ENSEMBL ID (ENSGXXXXXXXXXXX.X ) of the gene(s).
go_terms(string) — gene ontology terms - ID or label
chromosome(string) — chromosome name(s)
start(int) — minimum start region
end(int) — maximum end region
gene_model(string) — the gene model
user_key(string) — users token key

Response:

['okay', result] — result consists of

genes(array) — genes names and its content

['error', error_message] — Error. Verify the error message.

select_genes

Select genes (by their name or ID) as genomic regions from the specified gene model.

select_genes ( genes, go_terms, gene_model, chromosome, start, end, user_key )

Parameters:

genes(string) — Name(s) or ENSEMBL ID (ENSGXXXXXXXXXXX.X ) of the gene(s).
go_terms(string) — gene ontology terms - ID or label
gene_model(string) — the gene model
chromosome(string) — chromosome name(s)
start(int) — minimum start region
end(int) — maximum end region
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — query id

['error', error_message] — Error. Verify the error message.

set_gene_ontology_term_parent

set_gene_ontology_term_parent ( parent_go_id, parent_go_id, user_key )

Parameters:

parent_go_id(string) — parent GO identifier
parent_go_id(string) — parent GO identifier
user_key(string) — users token key

Response:

['okay', result] — result consists of

['error', error_message] — Error. Verify the error message.

Genomes - Inserting and listing genomes

add_genome

Add a (reference) Genome assembly to DeepBlue.

add_genome ( name, description, data, user_key )

Parameters:

name(string) — genome name
description(string) — description of the genome
data(string) — genome data
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the newly inserted genome

['error', error_message] — Error. Verify the error message.

chromosomes

List the chromosomes of a given Genome.

chromosomes ( genome, user_key )

Parameters:

genome(string) — the target genome
user_key(string) — users token key

Response:

['okay', result] — result consists of

chromosomes(array) — A list containing all chromosomes, with theirs names and sizes

['error', error_message] — Error. Verify the error message.

list_genomes

List Genomes assemblies that are registered in DeepBlue.

list_genomes ( user_key )

Parameters:

user_key(string) — users token key

Response:

['okay', result] — result consists of

genomes(array) — genome names

['error', error_message] — Error. Verify the error message.

list_similar_genomes

Lists all Genomes that have a similar name compared to the provided name. The similarity is calculated using the Levenshtein method.

list_similar_genomes ( name, user_key )

Parameters:

name(string) — genome name
user_key(string) — users token key

Response:

['okay', result] — result consists of

genomes(array) — similar genome names

['error', error_message] — Error. Verify the error message.

upload_chromosome

Upload the DNA sequence of a chromosome.

upload_chromosome ( genome, chromosome, data, user_key )

Parameters:

genome(string) — the target genome
chromosome(string) — chromosome name
data(string) — chromosome sequence data
user_key(string) — users token key

Response:

['okay', result] — result consists of

['error', error_message] — Error. Verify the error message.

Genomic Regions Enrichment - Enrich the genome regions

enrich_regions_fast

Enrich the regions based on regions bitmap signature comparison.

enrich_regions_fast ( query_id, genome, epigenetic_mark, biosource, sample, technique, project, user_key )

Parameters:

query_id(string) — Query ID
genome(string) — the target genome
epigenetic_mark(string) — name(s) of selected epigenetic mark(s)
biosource(string) — name(s) of selected biosource(s)
sample(string) — id(s) of selected sample(s)
technique(string) — name(s) of selected technique(s)
project(string) — name(s) of selected projects
user_key(string) — users token key

Response:

['okay', result] — result consists of

request_id(string) — Request ID - Use it to retrieve the result with info() and get_request_data(). The result is a list containing the datasets that overlap with the query_id regions.

['error', error_message] — Error. Verify the error message.

enrich_regions_go_terms

Enrich the regions based on Gene Ontology terms.

enrich_regions_go_terms ( query_id, gene_model, user_key )

Parameters:

query_id(string) — Query ID
gene_model(string) — the gene model
user_key(string) — users token key

Response:

['okay', result] — result consists of

request_id(string) — Request ID - Use it to retrieve the result with info() and get_request_data(). The result is a list containing the GO terms that overlap with the query_id regions.

['error', error_message] — Error. Verify the error message.

enrich_regions_overlap

Enrich the regions based on regions overlap analysis.

enrich_regions_overlap ( query_id, background_query_id, datasets, genome, user_key )

Parameters:

query_id(string) — Query ID
background_query_id(string) — query_id containing the regions that will be used as the background data.
datasets(struct) — a map where each key is an identifier and the value is a list containing experiment names or query_ids (you can use both together).
genome(string) — the target genome
user_key(string) — users token key

Response:

['okay', result] — result consists of

request_id(string) — Request ID - Use it to retrieve the result with info() and get_request_data(). The result is a list containing the datasets that overlap with the query_id regions.

['error', error_message] — Error. Verify the error message.

Genomic Regions Operations - Operating on the data regions

aggregate

Summarize the data_id content using the regions specified in ranges_id as boundaries. Use the fields @AGG.MIN, @AGG.MAX, @AGG.SUM, @AGG.MEDIAN, @AGG.MEAN, @AGG.VAR, @AGG.SD, @AGG.COUNT in 'get_regions' command 'format' parameter to retrieve the computed values minimum, maximum, median, mean, variance, standard deviation and number of regions, respectively.

aggregate ( data_id, ranges_id, column, user_key )

Parameters:

data_id(string) — id of the query with the data
ranges_id(string) — id of the query with the regions range
column(string) — name of the column that will be used in the aggregation
user_key(string) — users token key

Response:

['okay', result] — result consists of

regions(string) — query id of this aggregation operation

['error', error_message] — Error. Verify the error message.

binning

Bin results according to counts.

binning ( query_data_id, column, bins, user_key )

Parameters:

query_data_id(string) — query data that will made by the binning.
column(string) — name of the column that will be used in the aggregation
bins(int) — number of of bins
user_key(string) — users token key

Response:

['okay', result] — result consists of

request_id(string) — Request ID - Use it to retrieve the result with info() and get_request_data()

['error', error_message] — Error. Verify the error message.

count_regions

Return the number of genomic regions present in the query.

count_regions ( query_id, user_key )

Parameters:

query_id(string) — Query ID
user_key(string) — users token key

Response:

['okay', result] — result consists of

request_id(string) — Request ID - Use it to retrieve the result with info() and get_request_data()

['error', error_message] — Error. Verify the error message.

coverage

Send a request to count the number of regions in the result of the given query.

coverage ( query_id, genome, user_key )

Parameters:

query_id(string) — Query ID
genome(string) — Genome where the coverage will be calculated to
user_key(string) — users token key

Response:

['okay', result] — result consists of

request_id(string) — Request ID - Use it to retrieve the result with info() and get_request_data()

['error', error_message] — Error. Verify the error message.

distinct_column_values

Obtain the distict values of the field.

distinct_column_values ( query_id, field, user_key )

Parameters:

query_id(string) — Query ID
field(string) — field that is filtered by
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of filtered query

['error', error_message] — Error. Verify the error message.

extend

Extend the genomic regions included in the query. It is possible to extend downstream, upstream or in both directions.

extend ( query_id, length, direction, use_strand, user_key )

Parameters:

query_id(string) — Query ID
length(int) — The new region length
direction(string) — The direction that the region will be extended: 'BACKWARD', 'FORWARD', 'BOTH'. (Empty value will be used for both direction.
use_strand(boolean) — Use the region column STRAND to define the region direction
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the new query

['error', error_message] — Error. Verify the error message.

filter_by_motif

Filter the genomic regions by a regular expression motif.

filter_by_motif ( query_id, motif, user_key )

Parameters:

query_id(string) — Query ID
motif(string) — motif (PERL regular expression)
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of filtered query

['error', error_message] — Error. Verify the error message.

filter_regions

Filter the genomic regions by their content.

filter_regions ( query_id, field, operation, value, type, user_key )

Parameters:

query_id(string) — Query ID
field(string) — field that is filtered by
operation(string) — operation used for filtering. For 'string' must be '==' or '!=' and for 'number' must be one of these: ==,!=,>,>=,<,<=
value(string) — value the operator is applied to
type(string) — type of the value: 'number' or 'string'
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of filtered query

['error', error_message] — Error. Verify the error message.

flank

Create a set of genomic regions that flank the query regions. The original regions are removed from the query. Use the merge command to combine flanking regions with the original query.

flank ( query_id, start, length, use_strand, user_key )

Parameters:

query_id(string) — Query ID
start(int) — Number of base pairs after the end of the region. Use a negative number to denote the number of base pairs before the start of the region.
length(int) — The new region length
use_strand(boolean) — Use the region column STRAND to define the region direction
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the new query

['error', error_message] — Error. Verify the error message.

get_experiments_by_query

List the experiments and annotations that have at least one genomic region in the final query result.

get_experiments_by_query ( query_id, user_key )

Parameters:

query_id(string) — Query ID
user_key(string) — users token key

Response:

['okay', result] — result consists of

experiments(array) — List containing experiments names and ids

['error', error_message] — Error. Verify the error message.

get_regions

Trigger the processing of the query's genomic regions. The output is a column based format with columns as defined in the 'output_format' parameter. Use the command 'info' for verifying the processing status. The 'get_request_data' command is used to download the regions using the programmatic interface. Alternatively, results can be download using the URL: http://deepblue.mpi-inf.mpg.de/download?r_id=&key=.

get_regions ( query_id, output_format, user_key )

Parameters:

query_id(string) — Query ID
output_format(string) — Output format
user_key(string) — users token key

Response:

['okay', result] — result consists of

request_id(string) — Request ID - Use it to retrieve the result with info() and get_request_data()

['error', error_message] — Error. Verify the error message.

input_regions

Upload a set of genomic regions that can be accessed through a query ID. An interesting use case for this command is to upload a set of custom regions for intersecting with genomic regions in DeepBlue to specifically select regions of interest.

input_regions ( genome, region_set, user_key )

Parameters:

genome(string) — the target genome
region_set(string) — Regions in CHROMOSOME START END format
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — query id

['error', error_message] — Error. Verify the error message.

intersection

Select genomic regions that intersect with at least one region of the second query. This command is a simplified version of the 'overlap' command.

intersection ( query_data_id, query_filter_id, user_key )

Parameters:

query_data_id(string) — query data that will be filtered.
query_filter_id(string) — query containing the regions that the regions of the query_data_id must overlap.
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the new query

['error', error_message] — Error. Verify the error message.

merge_queries

Merge regions from two queries in a new query.

merge_queries ( query_a_id, query_b_id, user_key )

Parameters:

query_a_id(string) — id of the first query
query_b_id(string) — id of the second query (or use an array to include multiple queries)
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — new query id

['error', error_message] — Error. Verify the error message.

overlap

Select genomic regions that overlap or not overlap with with the specified number of regions of the second query. Important: This command is still experimental and changes may occour.

overlap ( query_data_id, query_filter_id, overlap, amount, amount_type, user_key )

Parameters:

query_data_id(string) — query data that will be filtered.
query_filter_id(string) — query containing the regions that the regions of the query_data_id must overlap.
overlap(boolean) — True if must overlap, or false if must not overlap.
amount(int) — Amount of regions that must overlap. Use the parameter 'amount_type' ('bp' or '%') to specify the unit. For example, use the value '10' with the amount_type '%' to specify that 10% of the bases in both regions must overlap, or use '10' with the amount_type 'bp' to specify that at least 10 bases must or must not overlap.
amount_type(string) — Type of the amount: 'bp' for base pairs and '%' for percentage.
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the new query

['error', error_message] — Error. Verify the error message.

query_cache

Cache a query result in DeepBlue memory. This command is useful when the same query ID is used multiple times in different requests. The command is an advice for DeepBlue to cache the query result and there is no guarantee that this query data access will be faster.

query_cache ( query_id, cache, user_key )

Parameters:

query_id(string) — Query ID
cache(boolean) — set or unset this query caching
user_key(string) — users token key

Response:

['okay', result] — result consists of

information(string) — New query ID.

['error', error_message] — Error. Verify the error message.

query_experiment_type

Filter the query ID for regions associated with experiments of a given type. For example, it is possible to select only peaks using this command with the 'peaks' parameter.

query_experiment_type ( query_id, type, user_key )

Parameters:

query_id(string) — Query ID
type(string) — experiment type (peaks or signal)
user_key(string) — users token key

Response:

['okay', result] — result consists of

information(string) — New query ID.

['error', error_message] — Error. Verify the error message.

score_matrix

Build a matrix containing the aggregation result of the the experiments data by the aggregation boundaries.

score_matrix ( experiments_columns, aggregation_function, aggregation_regions_id, user_key )

Parameters:

experiments_columns(struct) — map with experiments names and columns to be processed. Example : {'wgEncodeBroadHistoneDnd41H3k27acSig.wig':'VALUE', 'wgEncodeBroadHistoneCd20ro01794H3k27acSig.wig':'VALUE'}
aggregation_function(string) — aggregation function name: min, max, sum, mean, var, sd, median, count, boolean
aggregation_regions_id(string) — query ID of the regions that will be used as the aggregation boundaries
user_key(string) — users token key

Response:

['okay', result] — result consists of

score_matrix(string) — the score matrix containing the summarized data

['error', error_message] — Error. Verify the error message.

select_annotations

Select regions from the Annotations that match the selection criteria.

select_annotations ( annotation_name, genome, chromosome, start, end, user_key )

Parameters:

annotation_name(string) — name(s) of selected annotation(s)
genome(string) — the target genome
chromosome(string) — chromosome name(s)
start(int) — minimum start region
end(int) — maximum end region
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — query id

['error', error_message] — Error. Verify the error message.

select_experiments

Selects regions from Experiments by the experiments names.

select_experiments ( experiment_name, chromosome, start, end, user_key )

Parameters:

experiment_name(string) — name(s) of selected experiment(s)
chromosome(string) — chromosome name(s)
start(int) — minimum start region
end(int) — maximum end region
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — query id

['error', error_message] — Error. Verify the error message.

select_regions

Selects Experiment regions that matches the criteria informed by the operation parameters.

select_regions ( experiment_name, genome, epigenetic_mark, sample_id, technique, project, chromosomes, start, end, user_key )

Parameters:

experiment_name(string) — name(s) of selected experiment(s)
genome(string) — the target genome
epigenetic_mark(string) — name(s) of selected epigenetic mark(s)
sample_id(string) — id(s) of selected sample(s)
technique(string) — name(s) of selected technique(es)
project(string) — name(s) of selected projects
chromosomes(string) — chromosome name(s)
start(int) — minimum start region
end(int) — maximum end region
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — query id

['error', error_message] — Error. Verify the error message.

tiling_regions

Generate tiling regions across the genome chromosomes. The idea is to "bin" genomic regions systematically in order to obtain discrete regions over which one can aggregate. Using the 'score_matrix' command, these bins (tiles) can be compared directly across experiments.

tiling_regions ( size, genome, chromosome, user_key )

Parameters:

size(int) — tiling size
genome(string) — the target genome
chromosome(string) — chromosome name(s)
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — query id

['error', error_message] — Error. Verify the error message.

Projects - Inserting and listing projects

add_project

Add a Project to DeepBlue. A Project is used to group Experiments and to define their origin.

add_project ( name, description, user_key )

Parameters:

name(string) — projectname
description(string) — description of the project
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the newly inserted project

['error', error_message] — Error. Verify the error message.

add_user_to_project

Add a user as Project member.

add_user_to_project ( user, project, set, user_key )

Parameters:

user(string) — User name or ID
project(string) — Project name or ID
set(boolean) — True to include the user or false to remove
user_key(string) — users token key

Response:

['okay', result] — result consists of

user_id(string) — id of the user

['error', error_message] — Error. Verify the error message.

list_projects

List Projects included in DeepBlue.

list_projects ( user_key )

Parameters:

user_key(string) — users token key

Response:

['okay', result] — result consists of

projects(array) — project names

['error', error_message] — Error. Verify the error message.

list_similar_projects

List Projects that have a similar name compared to the provided name. The similarity is calculated using the Levenshtein method.

list_similar_projects ( name, user_key )

Parameters:

name(string) — project name
user_key(string) — users token key

Response:

['okay', result] — result consists of

projects(array) — similar project names

['error', error_message] — Error. Verify the error message.

set_project_public

Define a project as public. This means that all DeepBlue users can then access its data. You must be the project owner to perform this operation.

set_project_public ( project, set, user_key )

Parameters:

project(string) — Project name or ID
set(boolean) — True to set the project as public of false for unset
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the project

['error', error_message] — Error. Verify the error message.

Requests - Requests status information and results

get_request_data

Download the requested data. The output can be (i) a string (get_regions, score_matrix, and count_regions), or (ii) a list of ID and names (get_experiments_by_query), or (iii) a struct (coverage).

get_request_data ( request_id, user_key )

Parameters:

request_id(string) — ID of the request
user_key(string) — users token key

Response:

['okay', result] — result consists of

data(string) — the request data

['error', error_message] — Error. Verify the error message.

list_requests

List the Requests made by the user. It is possible to obtain only the requests of a given state.

list_requests ( request_state, user_key )

Parameters:

request_state(string) — Name of the state to get requests for. The valid states are: new, running, done, and failed.
user_key(string) — users token key

Response:

['okay', result] — result consists of

data_state(array) — Request-IDs and their state

['error', error_message] — Error. Verify the error message.

reprocess

Reprocess the request. Useful when the request was cancelled or removed.

reprocess ( request_id, user_key )

Parameters:

request_id(string) — ID of the request
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — ID of the reprocessed request

['error', error_message] — Error. Verify the error message.

Samples - Inserting and listing samples

add_sample

Add a Sample to DeepBlue that is related to a BioSource.

add_sample ( biosource, extra_metadata, user_key )

Parameters:

biosource(string) — biosource name
extra_metadata(struct) — additional metadata
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the newly inserted sample

['error', error_message] — Error. Verify the error message.

add_sample_from_gsm

Add a Sample to DeepBlue that is related to a BioSource and can be linked to an existing GSM identifier (from a GEO repository.

add_sample_from_gsm ( biosource, gsm_id, user_key )

Parameters:

biosource(string) — biosource name
gsm_id(string) — GSM ID
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the newly inserted sample

['error', error_message] — Error. Verify the error message.

list_samples

List Samples included in DeepBlue. It is possible to filter by the BioSource and by extra_metadata fields content.

list_samples ( biosource, extra_metadata, user_key )

Parameters:

biosource(string) — name(s) of selected biosource(s)
extra_metadata(struct) — Metadata that must be matched
user_key(string) — users token key

Response:

['okay', result] — result consists of

samples(array) — samples id with their content

['error', error_message] — Error. Verify the error message.

Status - Checking DeepBlue status

commands

List all available DeepBlue commands.

commands ( )

Parameters:

Response:

['okay', result] — result consists of

commands(struct) — command descriptions

['error', error_message] — Error. Verify the error message.

echo

Greet the user with the DeepBlue version.

echo ( user_key )

Parameters:

user_key(string) — users token key

Response:

['okay', result] — result consists of

message(string) — echo message including version

['error', error_message] — Error. Verify the error message.

Techniques - Inserting and listing techniques

add_technique

Add an experimental Technique to DeepBlue.

add_technique ( name, description, extra_metadata, user_key )

Parameters:

name(string) — technique name
description(string) — description of technique
extra_metadata(struct) — additional metadata
user_key(string) — users token key

Response:

['okay', result] — result consists of

id(string) — id of the newly inserted technique

['error', error_message] — Error. Verify the error message.

list_similar_techniques

List Techniques that have a similar name compared to the provided name. The similarity is calculated using the Levenshtein method.

list_similar_techniques ( name, user_key )

Parameters:

name(string) — technique name
user_key(string) — users token key

Response:

['okay', result] — result consists of

techniques(array) — similar techniques

['error', error_message] — Error. Verify the error message.

list_techniques

List the Techniques included in DeepBlue.

list_techniques ( user_key )

Parameters:

user_key(string) — users token key

Response:

['okay', result] — result consists of

techniques(array) — techniques

['error', error_message] — Error. Verify the error message.

Utilities - Utilities for connecting operations

extract_ids

A utility command that returns a list of IDs extracted from a list of ID and names.

extract_ids ( list )

Parameters:

list(array) — list of lists of IDs and names

Response:

['okay', result] — result consists of

ids(array) — list containing the extracted IDs

['error', error_message] — Error. Verify the error message.

extract_names

A utility command that returns a list of names extracted from a list of ID and names.

extract_names ( list )

Parameters:

list(array) — list of lists of IDs and Names

Response:

['okay', result] — result consists of

names(array) — list containing the extracted names

['error', error_message] — Error. Verify the error message.