Changes between KEGG API v2.3 and v3.0

We have made a number of changes to the methods and data types used in the KEGG API. These changes may cause much troubles for the existing users but are needed to make our service kept clean and maintained stably. Most importantly, changes had to be done before the APIs are used broadly.

We apologize to all the current users of our service for the inconvenience. This will be last time that the KEGG API methods lose its backward compatibility, hopefully.

Major points are:

'start' and 'max_results' arguments are introduced in many methods to repress amount of returned results at once.
methods for DBGET system are totally introduced to enable complicated search (users may wish to wrap them for compatibility and usability in separate methods -- these will be achieved in BioRuby etc.)
methods for pathways are re-organized for the complementation
names of the variables and data types are revisited (Java users will be affected heavily by this change, sorry for that)

In this note, changes are summarized in "OLD --> NEW" convention.

Variable names

keggorg --> org
db_name --> db

Data types

SSDBResult --> SSDBRelation

kid1 --> genes_id1 (string)
kid2 --> genes_id2 (string)
sw_score (int)
--> bit_score (float)
ident --> percent_identity (float)
overlap (int)
s1_start --> start_position1 (int)
s1_end --> end_position1 (int)
s2_start --> start_position2 (int)
s2_end --> end_position2 (int)
b1 --> best_flag_2to1 (boolean)
b2 --> best_flag_1to2 (boolean)
definition1 (string)
definition2 (string)
length1 (int)
length2 (int)

SSDBResultArray --> ArrayOfSSDBRelation

MOTIFResult --> MotifResult

mid --> motif_id (string)
definition (string)
kid --> genes_id (string)
seq_f --> start_position (int)
seq_t --> end_position (int)
score (float)
Evalue (v2.2) --> evalue (double)

MOTIFResultArray --> ArrayOfMotifResult

GENESResult --> Definition

kid --> entry_id (string)
keggdef --> definition (string)

GENESResultArray --> ArrayOfDefinition

LinkDBResult

--> entry_id1 (string)
entry --> entry_id2 (string)
link_type --> type (string)
links --> path (string)

LinkDBResultArray --> ArrayOfLinkDBRelation

Methods

KEGG

list_databases

Returned value:

string --> ArrayOfDefinition

list_organisms

Returned value:

ArrayOfstring --> ArrayOfDefinition

list_pathways --> list_pathways(org)

Arguments:

'org' name can be specified to obtain organism specific pathways.
Contents returned in v2.3 can be obtained if 'map' is given as an argument.

Returned value:

ArrayOfstring --> ArrayOfDefinition

dbinfo(db_name)

Removed. Use binfo method in DBGET section, instead.

DBGET

get_entries(entry_id_list) --> bget(string)

Arguments:

Changed to accept all bget command line options as well as entry_id.
This method is a replacement of get_entries, get_ntseqs and
get_aaseqs methods.

btit(entry_id_list) --> btit(string)

Arguments:

Changed to accept all btit command line options as well as entry_id.

bfind(target_db, keyword) --> bfind(string)

Arguments:

Changed to accept all bfind command line options as a string.

dbinfo(db_name) --> binfo(string)

Arguments:

Changed to accept all binfo command line options as a string.

LinkDB

get_linkdb_by_entry(genes_id, target_db) --> get_linkdb_by_entry(entry_id, db, start, max_results)

Arguments:

start, max_results are introduced.

SSDB

get_all_neighbors_by_gene(genes_id, threshold, keggorg_list) --> get_neighbors_by_gene(genes_id, org, start, max_results)

method name is changed.

Arguments:

threshold is removed and keggorg_list is changed to org so that
user need to call this method per organism.
start and max_results are introduced.

Returned value:

SSDBResultArray --> ArrayOfSSDBRelation

get_best_best_neighbors_by_gene(genes_id, threshold, keggorg_list) --> get_best_best_neighbors_by_gene(genes_id, start, max_results)

Arguments:

threshold and keggorg_list are removed.
start and max_results are introduced.

Returned value:

SSDBResultArray --> ArrayOfSSDBRelation

get_best_neighbors_by_gene(genes_id, threshold, keggorg_list) --> get_best_neighbors_by_gene(genes_id, start, max_results)

Arguments:

threshold and keggorg_list are removed.
start and max_results are introduced.

Returned value:

SSDBResultArray --> ArrayOfSSDBRelation

get_reverse_best_neighbors_by_gene(genes_id, threshold, keggorg_list) --> get_reverse_best_neighbors_by_gene(genes_id, start, max_results)

Arguments:

threshold and keggorg_list are removed.
start and max_results are introduced.

Returned value:

SSDBResultArray --> ArrayOfSSDBRelation

get_paralogs_by_gene(genes_id, threshold) --> get_paralogs_by_gene(genes_id, start, max_results)

Arguments:

threshold is removed.
start and max_results are introduced.

Returned value:

SSDBResultArray --> ArrayOfSSDBRelation

get_score_between_genes(genes_id1, genes_id2) --> get_similarity_between_genes(genes_id1, genes_id2)

method name is changed.

Returned value:

SSDBResult --> SSDBRelation

get_best_best_homologs_by_gene

removed. use get_best_best_neighbors_by_gene instead.

get_best_homologs_by_gene

removed. use get_best_neighbors_by_gene instead.

get_definition_by_gene

removed. use btit instead.

Motif

get_common_motifs_by_genes(target_db_list, genes_id_list, threshold) --> get_motifs_by_gene(genes_id, db)

Changed to accept only one gene at once. Motif database is specified as 'tfam' for TIGRFAM, 'pfam' for Pfam, 'pspt' for PROSITE pattern, 'pspr' for PROSITE profile and 'all' for these four databases.

Arguments:

threshold is removed.
genes_id_list is changed to genes_id.
target_db_list is changed to db.

Returned value:

MOTIFResultArray --> ArrayOfMotifResult

get_genes_by_motifs(motif_id_list) --> get_genes_by_motifs(motif_id_list, start, max_results)

Arguments:

start, max_results are introduced.

Returned value:

GENESResultArray --> ArrayOfDefinition

KO, OC, PC

get_oc_members_by_gene(genes_id) --> get_oc_members_by_gene(genes_id, start, max_results)

Arguments:

start, max_results are introduced.

get_pc_members_by_gene(genes_id) --> get_pc_members_by_gene(genes_id, start, max_results)

Arguments:

start, max_results are introduced.

PATHWAY

removed. use combination of get_pathways_by_* and mark_pathway_by_objects methods.

mark_pathway_by_genes
mark_pathway_by_enzymes
mark_pathway_by_compounds

removed and integrated to mark_pathway_by_objects method.

mark_pathway_by_objects(pathway_id, object_id_list)

newly added. object_id_list can include genes_id, enzyme_id, and compound_id.

color_pathway_by_genes
color_pathway_by_enzymes
color_pathway_by_compounds

removed. use color_pathway_by_objects instead.

color_pathway_by_objects(pathway_id, object_id_list, fg_color_list, bg_color_list)

newly added. fg_color_list corresponds to the text and border of the object and bg_color_list corresponds to the inside background colors. order and size of the object_id_list, fg_color_list and bg_color_list must be matched.

objects by pathway

get_reactions_by_pathways(pathway_id_list) --> get_reactions_by_pathway(pathway_id)

method name is changed. symmetrize with get_genes/enzymes/compounds_by_pathway methods.

Arguments:

pathway_id_list --> pathway_id

Mutual transformation of objects

gene-enzyme relations

get_genes_by_enzymes(enzyme_id_list, keggorg_list) --> get_genes_by_enzyme(enzyme_id, org)

method name is changed. symmetrize with new get_enzymes_by_gene method.

Arguments:

enzyme_id_list --> enzyme_id
keggorg_list --> org

get_enzymes_by_gene(genes_id)

will be added.

enzyme-compound-reaction relations

get_enzymes_by_reactions(reaction_id_list) --> get_enzymes_by_reaction(reaction_id)

method name is changed. symmetrize with new methods below.

Arguments:

reaction_id_list --> reaction_id

get_enzymes_by_compound(compound_id)
get_compounds_by_enzyme(enzyme_id)
get_compounds_by_reaction(reaction_id)
get_reaction_by_enzyme(enzyme_id)
get_reaction_by_compound(compound_id)

will be added.

GENES

get_aaseqs

removed. use bget method as bget("-f -n a eco:b0002 eco:b0003") instead.

get_ntseqs

removed. use bget method as bget("-f -n n eco:b0002 eco:b0003") instead.

get_all_genes_by_organism(keggorg) --> get_genes_by_organism(org, start, max_results)

method name is changed.

Arguments:

start, max_results are introduced.

GENOME

get_num_genes_by_organism(keggorg) --> get_number_of_genes_by_organism(org)

method name is changed.