File       : PianaSelectSQL.py
 Author     : R. Aragues & D. Jaeggi
 Creation   : 2003
 Contents   : subclasses for generating select sql statements
 Called from: PianaDBaccess
 
=======================================================================================================
 
This class is used in the same way as PianaInsertSQL
 
Each of the subclasses creates an sql query string that can be used to select information from Piana
 
This is done this way to generalize as much as possible the interaction of users with the database pianaDB.
 
A user that needs to select information into pianaDB will not create the SQL statement himself, but will
use one of these classes, together with method select_db_content() of class PianaDB
 
class PianaDBaccess integrates into a single and clear interface all the access to piana databases

Modules
		PianaGlobals sys utilities

Classes
		PianaSelectSQL LockTables SelectAllDBAliClusterRelationship SelectAllProteinPiana SelectAllProteinProteinInteractions SelectCommonCharacteristicProteins SelectCommonCodeProteins SelectDBAliClusterRelationship SelectFitnessConditions SelectFitnessReaction SelectFitnessScore SelectFitnessScoreReactionConditions SelectGoTermIdUsingTermType SelectInteractionMethod SelectInteractionPartner SelectInteractionPiana SelectInteractionSourceDB SelectListInteractionPiana SelectNewProteinPiana SelectPairMethodDBAliClusterRelationship SelectPartners SelectPartnersProteinSharingCog SelectProteinAttributeRelationship SelectProteinCathRelationship SelectProteinCode SelectProteinKingdom SelectProteinPiana SelectProteinPianaCorrespondence SelectProteinPianaTax SelectProteinResiduesCathRelationship SelectProteinScopCfRelationship SelectProteinScopFaRelationship SelectProteinScopRelationship SelectProteinScopSfRelationship SelectProteinSimilarity SelectProteinTableColumn SelectSimilarProteins SelectSpeciesNCBIfromSpeciesName SelectSpeciesNamefromSpeciesNCBI SelectSwissAccession SelectXFromGoTermId Select_go_term2term_distance UnlockTables   class LockTables(PianaSelectSQL)     Generates the SQL statement that locks tables indicated in argument   Method used to return the SQL query that locks access to mysql tables. Insertions are faster if tables are previously locked.   table_list is a list of table names     Static methods defined here: get_sqlquery(table_list)   class PianaSelectSQL     General class for Piana SQL SELECT queries. All SQL queries reading piana should be extensions of this class     Static methods defined here: get_sqlquery() Override this with the sql query that returns the value being researched   class SelectAllDBAliClusterRelationship(PianaSelectSQL)     Generates the sql statement to select information about dbali cluster information     Static methods defined here: get_sqlquery(clustering_method_value)   class SelectAllProteinPiana(PianaSelectSQL)     Generates the SQL statement that obtains all proteinPiana in database     Static methods defined here: get_sqlquery()   class SelectAllProteinProteinInteractions(PianaSelectSQL)     Generates the SQL statement that obtains all triplets (proteinPianaA, proteinPianaB, interactionPiana) for list_source_dbs and list_source_methods     Static methods defined here: get_sqlquery(list_source_dbs='all', inverse_dbs='no', list_source_methods='all', inverse_methods='no')   class SelectCommonCharacteristicProteins(PianaSelectSQL)     Generates the SQL statement that obtains those proteins with characteristics described to get_sqlquery   This class is used for example to get all proteins that belong to a certain species, by passing the approapiate arguments as shown:  get_sqlquery(proteinCode_table= PianaGlobals.proteinSpecies_table,                         proteinCodeID_col= PianaGlobals.speciesNCBI_col,                         proteinCodeID_value = taxonomy_value)             will retrieve all those proteinPiana of table proteinSpecies_table where column speciesNCBI_col is taxonomy_value     Static methods defined here: get_sqlquery(proteinCode_table=None, proteinCodeID_col=None, proteinCodeID_value=None)   class SelectCommonCodeProteins(PianaSelectSQL)     Generates the SQL statement that obtains those proteins that share a code with a given protein   The list will not contain the protein passed as reference     Static methods defined here: get_sqlquery(proteinCode_table, proteinCodeID_col, proteinPiana_value)   class SelectDBAliClusterRelationship(PianaSelectSQL)     Generates the sql statement to select information about dbali cluster information     Static methods defined here: get_sqlquery(proteinPiana_value, clustering_method_value, source_db_value)   class SelectFitnessConditions(PianaSelectSQL)     Generates the SQL statement that obtains the    After getting the new proteinPiana identifier, the method calling this class must make sure that the counter in increased by 1     Static methods defined here: get_sqlquery(proteinPiana_value)   class SelectFitnessReaction(PianaSelectSQL)     Generates the SQL statement that obtains the    After getting the new proteinPiana identifier, the method calling this class must make sure that the counter in increased by 1     Static methods defined here: get_sqlquery(proteinPiana_value)   class SelectFitnessScore(PianaSelectSQL)     Generates the SQL statement that obtains the    After getting the new proteinPiana identifier, the method calling this class must make sure that the counter in increased by 1     Static methods defined here: get_sqlquery(proteinPiana_value)   class SelectFitnessScoreReactionConditions(PianaSelectSQL)     Generates the SQL statement that obtains the    After getting the new proteinPiana identifier, the method calling this class must make sure that the counter in increased by 1     Static methods defined here: get_sqlquery(proteinPiana_value)   class SelectGoTermIdUsingTermType(PianaSelectSQL)     Generates the sql statement to select go term id associated to a proteinPiana specifing the term type value because one proteinPiana could be associated to more than one Go term id depending the term type:         - "molecular_function"       - "biological_process"       - "cellular_component"     Static methods defined here: get_sqlquery(proteinPiana, term_type)   class SelectInteractionMethod(PianaSelectSQL)     Generates the SQL statement that obtains a list  of methodID of an interactionPiana   if sourceDB_value == None, then it returns the SQL statement that obtains all methodIDs for interactionPiana if sourceDB_value is a database, then it returns the SQL statement that obtains all methodIDs for interactionPiana for a particular sourceDB   Attention: list_source_dbs and inverse_dbs not being used!!!     Static methods defined here: get_sqlquery(interactionPiana_value=None, sourceDBID_value=None, list_source_dbs='all', inverse_dbs='no') # TO DO!!! Remove sourceDBID and get methods for all dbs in list_source_dbs (taking into account inverse_dbs)   class SelectInteractionPartner(PianaSelectSQL)     Generates the SQL statement that obtains the interaction partner of a protein for a given interactionID     Static methods defined here: get_sqlquery(proteinPiana_value, interactionPiana_value, partner_side)   class SelectInteractionPiana(PianaSelectSQL)     Generates the SQL statement that obtains interaction internal id interactionPiana for the interaction between two specific proteins   Before looking for the interaction, it makes sure that the order proteinPianaA < proteinPianaB is respected. If it is not the case, it changes the query (not the objects passed, they remain unchanged) to execute it in the right order     Static methods defined here: get_sqlquery(proteinPianaA_value, proteinPianaB_value, list_source_dbs='all', inverse_dbs='no', list_source_methods='all', inverse_methods='no')   class SelectInteractionSourceDB(PianaSelectSQL)     Generates the SQL statement that obtains entries from table interactionSourceDB   if interactionPiana_value not None --> get the list of sourceDBID for this interactionPiana   if sourceDBID_value not None --> get the list of interactionPiana for this sourceDBID   Only one of the arguments can be "not None"     Static methods defined here: get_sqlquery(interactionPiana_value=None, sourceDBID_value=None)   class SelectListInteractionPiana(PianaSelectSQL)     Generates the SQL statement that obtains interaction internal  ids where a given protein is involved     Static methods defined here: get_sqlquery(proteinPiana_value, list_source_dbs='all', inverse_dbs='no', list_source_methods='all', inverse_methods='no')   class SelectNewProteinPiana(PianaSelectSQL)     Generates the SQL statement that obtains a new proteinPiana identifier from proteinPianaCounter table   After getting the new proteinPiana identifier, the method calling this class must make sure that the counter in increased by 1     Static methods defined here: get_sqlquery()   class SelectPairMethodDBAliClusterRelationship(PianaSelectSQL)     Generates the sql statement to select information about dbali cluster information     Static methods defined here: get_sqlquery(proteinPiana_value)   class SelectPartners(PianaSelectSQL)     Generates the SQL statement that obtains interaction partners of a given protein         Used to return the SQL query that retrieves the interaction partners of a protein (only those on side A or B)          This class is not to be used externally: the side (A or B)     where the protein is placed should be trasparent to the     external user. Piana makes this trasparent to the user by     creating a method (get_all_partners) under PianaDBaccess that     performs two queries to obtain all partners.  PianaDBaccess.get_all_partners     will call twice select_db_content with SelectPartners            partner_side is either "A" or "B", indicating if the partner will be searched on side A or B.     this is done this way because there is no single sqlquery that will return a complete list     of partners of a given protein, given the fact that those partners can be on side A or B       this is an artifact of the database design: an interaction is formed by a sideA and a sideB.     Static methods defined here: get_sqlquery(proteinPiana_value, partner_side, list_source_dbs='all', inverse_dbs='no', list_source_methods='all', inverse_methods='no')   class SelectPartnersProteinSharingCog(PianaSelectSQL)     Generates the SQL statement that obtains interaction partners for proteins that share cog with a certain proteinPiana       This class is not to be used externally: the side (A or B)     where the protein is placed should be trasparent to the     external user. Piana makes this trasparent to the user by     creating a method (get_partners_of_proteins_sharing_cog) under PianaDBaccess that     performs two queries to obtain all partners.  PianaDBaccess.get_partners_of_proteins_sharing_cog     will call twice select_db_content with SelectPartnersProteinSharingCog            partner_side is either "A" or "B", indicating if the partner will be searched on side A or B.     this is done this way because there is no single sqlquery that will return a complete list     of partners of a given protein, given the fact that those partners can be on side A or B       this is an artifact of the database design: an interaction is formed by a sideA and a sideB.     Static methods defined here: get_sqlquery(proteinPiana_value, partner_side, list_source_dbs='all', inverse_dbs='no', list_source_methods='all', inverse_methods='no')   class SelectProteinAttributeRelationship(PianaSelectSQL)     Generates the sql statement to select information about protein attributes relationship tables   the tables must follow the structure:   (currently for tables:   proteinCog_table  proteinEC_table  proteinSpecies_table  proteinDescription_table  proteinKeyword_table  proteinFunction_table  proteinSubcellularLocation_table )     Static methods defined here: get_sqlquery(attribute_relationship_table, attribute_relationship_col, proteinPiana_value)   class SelectProteinCathRelationship(PianaSelectSQL)     Generates the sql statement to select information about cath information     Static methods defined here: get_sqlquery(proteinPiana_value)   class SelectProteinCode(PianaSelectSQL)     Generates the SQL statement that obtains protein codes from protein tables   This is a generalization that can be used for any protein table that has at least these two fields:      proteinPiana    proteinCodeX   Currently, this class can be used for tables: swissProt,  proteinName, geneName, ec, emblAcc, gi, pirEntry, pirAcc, interpro   if you need to select swissAccession primary number you cannot use this class... use instead SelectSwissAccession (because of isPrimary)     Static methods defined here: get_sqlquery(proteinCode_table, proteinCode_col, proteinPiana_value, source_db_info='no')   class SelectProteinKingdom(PianaSelectSQL)     Generates the sql statement to select the kingdom value for a given proteinPiana     Static methods defined here: get_sqlquery(proteinPiana_value=None)   class SelectProteinPiana(PianaSelectSQL)     Generates the SQL statement that obtains proteinPiana from any other protein identifier (swissprot, ...)   Method get_sqlquery used to return the SQL query that retrieves the proteinPianas equivalent to "protein_code" of type "code_type"   Valid "code_type" value are those in PianaGlobals.xxxx_col that are in a table where there is as well a proteinPiana_col   if protein_code being passed is a pdb code, the format of the code must be pdb_code.chain_id  If the chain_id is None, write pdb_code. (leaving the dot)       "source_db_info" determines if information about the sourceDB that inserted the proteinPiana is returned or not        - "no" will simply return a list of proteinPianas        - "yes" will return a list of tuples (proteinPiana, sourceDBID)     Static methods defined here: get_sqlquery(protein_code=None, code_type=None, source_db_info='no')   class SelectProteinPianaCorrespondence(PianaSelectSQL)     Generates the SQL statement that obtains the proteinPiana associated to a proteinMD5 in table proteinCorrespondence   This class is use to keep consistency of proteinPiana <--> proteinSequence between different versions of piana databases     Static methods defined here: get_sqlquery(proteinMD5_value, tax_id_value)   class SelectProteinPianaTax(PianaSelectSQL)     Generates the SQL statement that obtains proteinPiana (of a specific taxonomy) from any other protein identifier (swissprot, ...)   Method get_sqlquery is used to return the SQL query that retrieves the proteinPianas (of a specific taxonomy) equivalent to "protein_code" of type "code_type"   Valid "code_type" value are those in PianaGlobals.xxxx_col that are in a table where there is as well a proteinPiana_col   Valid taxonomy_value values are those in NCBI taxonomy database   "source_db_info" determines if information about the sourceDB that inserted the proteinPiana is returned or not        - "no" will simply return a list of proteinPianas        - "yes" will return a list of tuples (proteinPiana, sourceDBID)     Static methods defined here: get_sqlquery(protein_code=None, code_type=None, taxonomy_value=None, source_db_info='no')   class SelectProteinResiduesCathRelationship(PianaSelectSQL)     Generates the sql statement to select information about cath information     Static methods defined here: get_sqlquery(proteinPiana_value)   class SelectProteinScopCfRelationship(PianaSelectSQL)     Generates the sql statement to select information about scop fold information     Static methods defined here: get_sqlquery(proteinPiana_value)   class SelectProteinScopFaRelationship(PianaSelectSQL)     Generates the sql statement to select information about scop family information     Static methods defined here: get_sqlquery(proteinPiana_value)   class SelectProteinScopRelationship(PianaSelectSQL)     Generates the sql statement to select information about scop information     Static methods defined here: get_sqlquery(proteinPiana_value)   class SelectProteinScopSfRelationship(PianaSelectSQL)     Generates the sql statement to select information about scop superfamily information     Static methods defined here: get_sqlquery(proteinPiana_value)   class SelectProteinSimilarity(PianaSelectSQL)     Generates the SQL statement that obtains a pair of similar proteins, if they exist   Selects two elements, must be taken into account when making the call to PianaDB     Static methods defined here: get_sqlquery(proteinPianaA_value, proteinPianaB_value)   class SelectProteinTableColumn(PianaSelectSQL)     Generates the SQL statement that obtains a column value of table protein, given a proteinPiana identifier   This is a generalization that can be used for any column of table protein     Static methods defined here: get_sqlquery(proteinTable_column_value, proteinPiana_value)   class SelectSimilarProteins(PianaSelectSQL)     Generates the SQL statement that obtains a list of proteins that are similar to a proteinPiana   "mode" can be:      - "higher" : searches in the column proteinPianaB    - "lower"  : searches in the column proteinPianaA   To get all similar proteins you need to do two queries, one with mode higher and another with mode lower. PianaDBaccess.get_similar_proteins_dic does it...     Static methods defined here: get_sqlquery(proteinPiana_value, mode=None)   class SelectSpeciesNCBIfromSpeciesName(PianaSelectSQL)     Generates the sql statement to select the speciesNCBI value for a given speciesName speciesName_value     Static methods defined here: get_sqlquery(speciesName_value=None)   class SelectSpeciesNamefromSpeciesNCBI(PianaSelectSQL)     Generates the sql statement to select the speciesName value for a given speciesNCBI_value     Static methods defined here: get_sqlquery(speciesNCBI_value=None)   class SelectSwissAccession(PianaSelectSQL)     Generates the SQL statement that obtains swiss accession numbers corresponding to proteinPiana   get_sqlquery method used to return the SQL query that retrieves the swiss accession number corresponding to proteinPiana       if return_primary == 1, then returns only primary swiss accessions     if return_primary == 0, then returns all swiss accession numbers     Static methods defined here: get_sqlquery(proteinPiana_value, return_primary=1, source_db_info='no')   class SelectXFromGoTermId(PianaSelectSQL)     Generates the sql statement to select something (proteinPiana_col or go_acc_col) from one of the two go tables (proteinGo_table or go_table) from a given GO term_id     Static methods defined here: get_sqlquery(x_col, term_id_value)   class Select_go_term2term_distance(PianaSelectSQL)     Generates the sql statement to select the distance between two go term ids     Static methods defined here: get_sqlquery(term1_id, term2_id)   class UnlockTables(PianaSelectSQL)     Generates the SQL statement that unlocks tables previously locked   Method used to return the SQL query that locks access to mysql tables. Insertions are faster if tables are previously locked.   table_list is a list of table names     Static methods defined here: get_sqlquery()

Functions
		build_sql_db_restriction(list_source_dbs=None, inverse_dbs='no') function used to build a restriction from a list of databases   this restriction will limit the sql query to retrieve only those interactionPiana that belong to specific databases build_sql_method_restriction(list_source_methods=None, inverse_methods='no') function used to build a restriction from a list of methods   this restriction will limit the sql query to retrieve only those interactionPiana that where found by specific methods

Data
		verbose = 0