DeepBlue (1.13.7) Reference API

DeepBlue operations

Annotations

BioSources

BioSources relationship

Column Types

Data Modification

Epigenetic marks

Experiments

Expressions

General Information

Genes

Genomes

Genomic Regions Enrichment

Genomic Regions Operations

Projects

Requests

Samples

Status

Techniques

Utilities

Annotations - Inserting and listing annotations

add_annotation

Add a custom annotation of genomic regions such as, for instance, promoters, transcription factor binding sites, or genes to DeepBlue. Annotations are a set genomic regions such as, for instance, promoters, transcription factor binding sites, or genes to DeepBlue.
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.
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 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

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.
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

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_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_region_overlap

Enrich the regions based on regions overlap analysis.
enrich_region_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.

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.
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_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
  • 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.
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.