## sequence_db.search() — search for similar sequences

`search(aln, seq_database_file, search_group_list, search_randomizations=0, search_top_list=20, off_diagonal=100, overhang=0, gap_penalties_1d=(-900.0, -50.0), signif_cutoff=(4.0, 5.0), rr_file='$(LIB)/as1.sim.mat', matrix_offset=0.0, fast_search_cutoff=1.0, data_file=False, search_sort='LONGER', output='LONG', alignment_features='INDICES CONSERVATION', local_alignment=False, fast_search=False, window_size=1024, io=None, **vars)`

> This command searches a sequence database for proteins that are similar to a given target sequence.

> The target sequence should be the only sequence in the provided alignment, aln.

> The database of sequences to be scanned against must be read previously by the sequence_db.read() command.

> The command uses the dynamic programming method for the best sequence alignment, given the gap creation and extension penalties specified by gap_penalties_1d and residue type scores read from file rr_file. gap_penalties_1d[0] is a gap creation penalty and gap_penalties_1d[1] is a gap extension penalty.

> The search_top_list top hits are written to the `log` file at the end. The hits are sorted according to the fractional sequence identity score obtained by dividing the number of identical residue pairs by the length of the longer sequence (search_sort = `'LONGER'`) or the shorter sequence (search_sort = `'SHORTER'`).

> The final list of hits contains three different significance values:

1. `SIGNI`. Z-score from sequence randomizations. This is the most accurate significance score, but the slowest one to calculate. For each pairwise comparison, the two sequences are shuffled a specified number of times (search_randomizations) to obtain the mean and standard deviation of “random” scores from which the Z-score for an alignment score of a given pair of sequences is calculated.

2. `SIGNI2`. Z-score for sequence identity from the database scan. After comparison of the target sequence with all sequences in the database is done, the comparisons are sorted by the length of the database sequence. The pairwise sequence identities of the 20 sequences closest in length to the target sequence are used to calculate the average and standard deviation of the percentage sequence identities for subsequent calculation of the Z-score for the percentage sequence identity of a given pairwise alignment.

3. `SIGNI3`. Z-score for alignment score from the database scan. The procedure is the same as for `SIGNI2`, except that the alignment scores are used instead of the pairwise sequence identities.

> The calculation of the Z-scores assumes that the random scores are distributed according to the Gaussian distribution, instead of the extreme value distribution [Karlin & Altschul, 1990], which is more correct.

> search_randomizations specifies how many alignments of the shuffled sequences are done to calculate the significance score for the overall sequence similarity. If 0, the significance is not calculated. If more than 5 randomizations are done, the significance score, not sequence identity, is used for sorting the hit list.

> When fast_search is `True` only those sequences that have a database-scan alignment score significance (`SIGNI3` in output) above fast_search_cutoff are used for the “full” randomization-based significance calculation. Since the mean and the standard deviation of the distribution obtained by randomizing the two compared sequences are much more appropriate than the corresponding quantities for the target/database comparisons, fast_search should be `True` only when you are in a hurry and the database is large.

> If data_file is `True` the final results (list of PDB codes with significances, etc.) are also written to a separate file `'seqsearch.dat'`.

> If output is `'LONG'`, the best alignment for each sequence in the database and its various scores are also written to the `log` file. If output is `'VERY_LONG'`, individual scores obtained for randomized sequences are also written to the `log` file (this is almost never needed).

> If the selected significance score is larger than signif_cutoff[0] and not more than signif_cutoff[1] units worse than the best hit, all the members of the same group, as defined in search_group_list, are added to the alignment (the original query sequence is removed). These sequences are taken from seq_database_file, which is often (but not always) the same file previously provided to sequence_db.read(), and must be in PIR format. Subsequent alignment.malign(), environ.dendrogram() and alignment.write() can then be used to write out all related PDB chains aligned to the target sequence.

> See sequence_db.read() for a discussion of the window_size parameter.

Example: examples/commands/sequence_search.py

      # Example for: sequence_db.search()

      # This will search the MODELLER database of representative protein chains
      # for chains similar to the specified sequence.

      from modeller import *

      log.verbose()
      env = environ()

      # Read in the sequences of all PDB structures
      try:
          sdb = sequence_db(env, seq_database_file='pdball.pir',
                            seq_database_format='PIR',
                            chains_list='very-short-for-test.cod')
      except IOError:
          print("""
      Could not read sequence database file. This file is not included by default
      in the Modeller distribution, but you can download it from the Modeller
      downloads page (http://salilab.org/modeller/supplemental.html).

      Note: it is recommended to use profile.build() rather than sequence_db.search().
      See step 1 of the Modeller basic tutorial at
      http://salilab.org/modeller/tutorial/basic.html
      """)
          raise

      # Read in the query sequence in alignment format
      aln = alignment(env, file='toxin.ali', align_codes='2nbt')

      sdb.search(aln, search_randomizations=20, # should use 100 in real life
                 seq_database_file='pdball.pir',
                 search_group_list='pdb_95.grp',
                 off_diagonal=9999, gap_penalties_1d=(-800, -400),
                 signif_cutoff=(1.5, 5.0))

      aln.malign()
      aln.write(file='toxin-search.pap', alignment_format='PAP')