Bio::Easel::MSA(3)

NAME
Bio::Easel - The great new Bio::Easel!

VERSION
Version 0.01

SYNOPSIS
Multiple sequence alignment handling through inline C with Easel.

Perhaps a little code snippet.

    use Bio::Easel::MSA;

    my $foo = Bio::Easel::MSA->new({"fileLocation" => $alnfile});
    ...

EXPORT
No functions currently exported.

SUBROUTINES/METHODS

  new
  Title    : new
  Incept   : EPN, Thu Jan 24 09:28:54 2013
  Usage    : Bio::Easel::MSA->new
  Function : Generates a new Bio::Easel::MSA object.
           : Either <fileLocation> or <esl_msa> must be passed in.
  Args     : <fileLocation>: optional: file location of alignment
           : <esl_msa>:      optional: ptr to an Easel ESL_MSA object
           : <reqdFormat>:   optional: string defining requested/required format
           :                 valid format strings are:
           :                 "unknown", "Stockholm", "Pfam", "UCSC A2M", "PSI-BLAST",
           :                 "SELEX", "aligned FASTA", "Clustal", "Clustal-like",
           :                 "PHLYIP (interleaved)", or "PHYLIP (sequential)"
           : <forceText>:    '1' to read the alignment in text mode
           : <isRna>:        '1' to force RNA alphabet
           : <isDna>:        '1' to force DNA alphabet
           : <isAmino>:      '1' to force protein alphabet
           :
  Returns  : Bio::Easel::MSA object

  msa
  Title    : msa
  Incept   : EPN, Tue Jan 29 09:06:30 2013
  Usage    : $msaObject->msa()
  Function : Accessor for msa: sets (if nec) and returns MSA.
  Args     : none
  Returns  : msa

  path
  Title    : path
  Incept   : EPN, Tue Jan 30 15:42:30 2013
  Usage    : $msaObject->path()
  Function : Accessor for path, read only.
  Args     : none
  Returns  : string containing path to the SEED or undef.

  format
  Title    : format
  Incept   : rdf, Fri Jul 19 14:05:01 2013
  Usage    : $msaObject->format()
  Function : Gets the format of the MSA
  Args     : none
  Returns  : String of the format.

  is_digitized
  Title    : is_digitized
  Incept   : EPN, Wed Mar  5 09:14:34 2014
  Usage    : $msaObject->is_digitized()
  Function : Returns '1' is MSA is digitized, else returns '0'
  Args     : none
  Returns  : '1' if MSA is digitized, else returns '0'.

  read_msa
  Title    : read_msa
  Incept   : EPN, Mon Jan 28 09:26:24 2013
  Usage    : $msaObject->read_msa($fileLocation)
  Function : Opens $fileLocation, reads first MSA, sets it.
  Args     : <fileLocation>: file location of alignment, required unless $self->{path} already set
           : <reqdFormat>:   optional, required format of alignment file
           : <do_text>:      optional, TRUE to read alignment in text mode
  Returns  : void

  nseq
  Title    : nseq
  Incept   : EPN, Mon Jan 28 09:35:21 2013
  Usage    : $msaObject->nseq()
  Function : Gets number of seqs in MSA
  Args     : none
  Returns  : number of sequences (esl_msa->nseq)

  alen
  Title    : alen
  Incept   : EPN, Tue Jan 29 07:41:08 2013
  Usage    : $msaObject->alen()
  Function : Get alignment length.
  Args     : none
  Returns  : alignment length, number of columns (esl_msa->alen)

  checksum
  Title    : checksum
  Incept   : EPN, Tue Mar  4 09:42:52 2014
  Usage    : $msaObject->checksum()
  Function : Determine the checksum for an MSA. Caution: the
           : same MSA will give a different checksum depending
           : on whether it was read in text or digital mode.
  Args     : none
  Returns  : checksum as in integer.

  has_rf
  Title    : has_rf
  Incept   : EPN, Tue Apr  2 19:44:21 2013
  Usage    : $msaObject->has_rf()
  Function : Does MSA have RF annotation?
  Args     : none
  Returns  : '1' if MSA has RF annotation, else returns 0

  has_ss_cons
  Title    : has_ss_cons
  Incept   : EPN, Fri May 24 09:56:40 2013
  Usage    : $msaObject->has_ss_cons()
  Function : Does MSA have SS_cons annotation?
  Args     : none
  Returns  : '1' if MSA has SS_cons annotation, else returns 0

  get_rf
  Title    : get_rf
  Incept   : EPN, Thu Nov 21 10:10:00 2013
  Usage    : $msaObject->get_rf()
  Function : Returns msa->rf if it exists, else dies via croak.
  Args     : None
  Returns  : msa->rf if it exists, else dies

  get_rflen
  Title     : get_rflen
  Incept    : EPN, Fri Mar 15 15:48:42 2019
  Usage     : $msaObject->rflen
  Function  : Return nongap RF length for the MSA
  Args      : $gapstr: string of characters to consider as gaps,
            :          if undefined we use '.-~'
  Returns   : length of msa->rf after removing gaps, if it exists, else dies

  set_rf
  Title    : set_rf
  Incept   : EPN, Tue Feb 18 09:54:20 2014
  Usage    : $msaObject->set_rf()
  Function : Sets msa->rf given a string.
  Args     : $rfstr: string that will become RF
  Returns  : void
  Dies     : if length($rfstr) != msa->alen

  get_ss_cons
  Title    : get_ss_cons
  Incept   : EPN, Fri May 24 10:03:41 2013
  Usage    : $msaObject->get_ss_cons()
  Function : Returns msa->ss_cons if it exists, else dies via croak.
  Args     : None
  Returns  : msa->ss_cons if it exists, else dies

  get_ss_cons_dot_parantheses
  Title    : get_ss_cons_dot_parantheses
  Incept   : EPN, Wed May 21 12:01:48 2014
  Usage    : $msaObject->get_ss_cons_dot_parantheses()
  Function : Returns a dot-parantheses format of msa->ss_cons if it exists, else dies via croak.
  Args     : None
  Returns  : msa->ss_cons in dot-parantheses format, if it exists, else dies

  get_ss_cons_ct
  Title    : get_ss_cons_ct
  Incept   : EPN, Mon Jul  7 09:41:58 2014
  Usage    : $msaObject->get_ss_cons_ct()
  Function : Returns a 'CT' array describing the consensus secondary structure
           : of an msa.
  Args     : msa
  Returns  : a 'CT' array, msa->alen+1 elements
           : ct[i] is the position that 'i' basepairs to, else '0' [1..alen] (NOT 0..alen-1)

  set_ss_cons
  Title    : set_ss_cons
  Incept   : EPN, Tue Feb 18 10:15:25 2014
  Usage    : $msaObject->set_ss_cons()
  Function : Sets msa->ss_cons given a string.
  Args     : $ss_cons_str: string that will become msa->ss_cons
  Returns  : void
  Dies     : if length($ss_cons_str) != msa->alen

  set_ss_cons_wuss
  Title    : set_ss_cons_wuss
  Incept   : EPN, Mon Jul  7 11:12:23 2014
  Usage    : $msaObject->set_ss_cons_wuss()
  Function : Sets msa->ss_cons given a string and convert it to full WUSS annotation.
  Args     : $ss_cons_str: string that will become msa->ss_cons
  Returns  : void
  Dies     : if length($ss_cons_str) != msa->alen, or there is a problem converting to full WUSS

  set_blank_ss_cons
  Title    : set_blank_ss_cons
  Incept   : EPN, Tue Oct 22 10:38:39 2013
  Usage    : $msaObject->set_blank_ss_cons()
  Function : Sets msa->ss_cons as all '.' characters (zero basepairs).
  Args     : None
  Returns  : Nothing

  get_sqname
  Title    : get_sqname
  Incept   : EPN, Mon Jan 28 09:35:21 2013
  Usage    : $msaObject->get_sqname($idx)
  Function : Returns name of sequence $idx in MSA.
  Args     : index of sequence
  Returns  : name of sequence $idx (esl_msa->sqname[$idx])
             ($idx runs 0..nseq-1)

  get_sqidx
  Title    : get_seqidx
  Incept   : EPN, Mon Feb  3 14:20:07 2014
  Usage    : $msaObject->_get_sqidx($sqname)
  Function : Return the index of sequence $sqname in the MSA.
  Args     : $sqname: the sequence of interest
  Returns  : index of $sqname in $msa, or -1 if it does not exit
  Dies     : if msa->index is not setup

  set_sqname
  Title    : set_sqname
  Incept   : EPN, Mon Jan 28 09:48:42 2013
  Usage    : $msaObject->set_sqname($idx, $newName)
  Function : Returns nothing
  Args     : index of sequence, new sequence name.
  Returns  : void

  has_sqwgts
  Title    : has_sqwgts
  Incept   : EPN, Tue Apr  1 13:50:53 2014
  Usage    : $msaObject->has_sqwgts()
  Function : Returns '1' if MSA has valid sequence weights, else returns '0'
  Args     : none
  Returns  : '1' if MSA has valid sequence weights, else '0'

  get_sqwgt
  Title    : get_sqwgt
  Incept   : EPN, Fri May 24 10:47:03 2013
  Usage    : $msaObject->get_sqwgt($idx)
  Function : Returns weight of sequence $idx in MSA.
  Args     : index of sequence
  Returns  : weight of sequence $idx (esl_msa->wgt[$idx])
             ($idx runs 0..nseq-1)
  Dies     : if MSA does not have sequence weight annotation

  remove_sqwgts
  Title    : remove_sqwgts
  Incept   : EPN, Thu Feb 20 14:25:35 2014
  Usage    : $msaObject->remove_sqwgts()
  Function : Removes GF WT annotation from an MSA.
  Args     : none
  Returns  : void

  get_accession
  Title    : get_accession
  Incept   : EPN, Fri Feb  1 11:43:08 2013
  Usage    : $msaObject->get_accession()
  Function : Gets accession for MSA.
  Args     : none
  Returns  : the accession, a string

  get_name
  Title    : get_name
  Incept   : EPN, Mon Jul  8 10:00:44 2013
  Usage    : $msaObject->get_name($name)
  Function : Gets name for MSA.
  Args     : none
  Returns  : the name, a string

  set_accession
  Title    : set_accession
  Incept   : EPN, Fri Feb  1 11:11:05 2013
  Usage    : $msaObject->set_accession($acc)
  Function : Sets accession for MSA in <esl_msa>
  Args     : accession string to set
  Returns  : void

  set_name
  Title    : set_name
  Incept   : EPN, Fri Feb  1 11:11:05 2013
  Usage    : $msaObject->set_name($acc)
  Function : Sets name for MSA in <esl_msa>
  Args     : name string to set
  Returns  : void

  write_msa
  Title    : write_msa
  Incept   : EPN, Mon Jan 28 09:58:19 2013
  Usage    : $msaObject->write_msa($fileLocation)
  Function : Write MSA to a file
  Args     : $outfile: name of output file, if "STDOUT" output to stdout, not to a file
           : $format:  ('stockholm', 'pfam', 'a2m', 'phylip', 'phylips', 'psiblast', 'selex', 'afa', 'clustal', 'clustallike', 'fasta')
           :           if 'fasta', write out seqs in unaligned fasta.
           : $do_append_if_exists: if $outfile exists, append to it, else create it
  Returns  : void

  write_single_unaligned_seq
  Title    : write_single_unaligned_seq
  Incept   : EPN, Mon Nov  4 09:53:50 2013
  Usage    : Bio::Easel::MSA->write_single_unaligned_seq($idx)
  Function : Writes out a single seq from MSA in FASTA format to a file.
  Args     : $idx:     index of seq in MSA to output
           : $outfile: name of file to create
           : $do_append_if_exists: if $outfile exists, append to it, else create it
  Returns  : void

  any_allgap_columns
  Title    : any_allgap_columns
  Incept   : EPN, Mon Jan 28 10:44:12 2013
  Usage    : $msaObject->any_allgap_columns()
  Function : Return TRUE if any all gap columns exist in MSA
  Args     : none
  Returns  : TRUE if any all gap columns, FALSE if not

  average_id
  Title    : average_id
  Incept   : EPN, Fri Feb  1 06:59:50 2013
  Usage    : $msaObject->average_id($max_nseq)
  Function : Calculate and return average fractional identity of
           : all pairs of sequences in msa. If more than $max_nseq
           : sequences exist in the seed, an average is computed
           : over a stochastic sample (the sample and thus the
           : result with vary over multiple runs).
  Args     : max number of sequences for brute force calculation
  Returns  : average percent id of all seq pairs or a sample

  get_sqstring_aligned
  Title    : get_sqstring_aligned
  Incept   : EPN, Fri May 24 11:02:21 2013
  Usage    : $msaObject->get_sqstring_aligned()
  Function : Return an aligned sequence from an MSA.
  Args     : index of sequence you want
  Returns  : aligned sequence index idx

  swap_gap_and_closest_residue
  Title    : swap_gap_and_closest_residue
  Incept   : EPN, Fri Feb 19 06:39:54 2021
  Usage    : $msaObject->swap_gap_and_closest_residue()
  Function : For a specific sequence, swap a gap in the alignment
             with the nearest residue before or after it.
             Also relocates ss,sa annotation for the relocated residue, if it exists
             Changes pp annotation for the relocated residue to 0, if it exists

  Args     : seqidx:    sequence index we are swapping residue in
             gap_apos:  aligned position of the gap [1..alen]
             do_before: '1' to swap with first residue before gap,
                        '0' to swap with first residue after gap
  Returns  : Two values: $ret_apos (or -1) and error message (or "")
             If successful:
                return value 1: $res_apos: (integer) the position $gap_apos was switched with
                return value 2: "", empty string indicating no error
             If unsuccessful because either $gap_apos is not a gap for $seqidx,
             or   $do_before and no nongaps exist before $gap_apos
             or ! $do_before and no nongaps exist after $gap_apos
                return value 1: -1, did not swap, so returns -1 as $res_apos
                return value 2: string beginning with "ERROR" explaining problem
  Dies     : If there's a problem getting or setting sqstring or annotation strings

  get_sqstring_aligned_and_truncated
  Title    : get_sqstring_aligned_and_truncated
  Incept   : EPN, Fri Mar 15 14:58:04 2019
  Usage    : $msaObject->get_sqstring_aligned_and_truncated()
  Function : Return an aligned sequence from an MSA
           : truncated to include only aligned positions
           : from $start to $stop.
  Args     : $idx:    index of sequence you want
           : $astart: start alignment position [1..alen]
           : $astop:  stop alignment position  [1..alen]
  Returns  : aligned sequence index idx from $astart..$astop
  Dies     : if $astart and $astop don't make sense or
           : sequence index $idx does not exist

  get_ppstring_aligned
  Title    : get_ppstring_aligned
  Incept   : EPN, Mon Jul  7 09:12:09 2014
  Usage    : $msaObject->get_ppstring_aligned()
  Function : Return an aligned posterior probability annotation for a seq from an MSA.
  Args     : index of sequence you want PP annotation
  Returns  : aligned posterior probability annotation for sequence index idx

  get_sastring_aligned
  Title    : get_sastring_aligned
  Incept   : EPN, Fri Feb 19 15:09:04 2021
  Usage    : $msaObject->get_sastring_aligned()
  Function : Return an aligned SA annotation string for a seq from an MSA.
  Args     : index of sequence you want SA annotation
  Returns  : aligned SA annotation for sequence index idx

  get_ssstring_aligned
  Title    : get_ssstring_aligned
  Incept   : EPN, Mon Jul  7 09:12:09 2014
  Usage    : $msaObject->get_ssstring_aligned()
  Function : Return an aligned posterior probability annotation for a seq from an MSA.
  Args     : index of sequence you want SS annotation
  Returns  : aligned SS annotation for sequence index idx

  get_sqstring_unaligned
  Title    : get_sqstring_unaligned
  Incept   : EPN, Fri May 24 11:02:21 2013
  Usage    : $msaObject->get_sqstring_unaligned()
  Function : Return an unaligned sequence from an MSA.
  Args     : index of sequence you want
  Returns  : unaligned sequence, index idx

  get_sqstring_unaligned_and_truncated
  Title    : get_sqstring_unaligned_and_truncated
  Incept   : EPN, Fri Mar 15 14:59:44 2019
  Usage    : $msaObject->get_sqstring_aligned_and_truncated()
  Function : Return an unaligned sequence from an MSA
           : truncated to include only aligned positions
           : from $start to $stop.
  Args     : $idx:    index of sequence you want
           : $astart: start alignment position [1..alen]
           : $astop:  stop alignment position  [1..alen]
           : $gapstr: string of characters to consider as gaps,
           :          if undefined we use '.-~'
  Returns  : unaligned sequence index idx from $astart..$astop
  Dies     : if $astart and $astop don't make sense or
           : sequence index $idx does not exist

  get_sqlen
  Title    : get_sqlen
  Incept   : EPN, Fri Feb  1 16:56:24 2013
  Usage    : $msaObject->get_sqlen()
  Function : Return unaligned sequence length of
           : sequence <idx>.
  Args     : index of sequence you want length of
  Returns  : unaligned sequence length of sequence idx

  get_column
  Title    : get_column
  Incept   : EPN, Tue Feb 18 09:22:05 2014
  Usage    : $msaObject->get_column($apos)
  Function : Return a string that is column $apos of the alignment,
           : where apos runs 1..alen. So to get the first column
           : of the alignment pass in 1 for $apos, pass in 2 for the
           : second column, etc.
  Args     : $apos: [1..alen] the desired column of the alignment
  Returns  : $column: column $apos of the alignment, as a string

  count_residues
  Title    : count_residues
  Incept   : March 5, 2013
  Usage    : $msaObject->count_residues()
  Function : Calculate and return total sequence length
           : in the MSA.
  Args     : none
  Returns  : total sequence length

  average_sqlen
  Title    : average_sqlen
  Incept   : EPN, Fri Feb  1 06:59:50 2013
  Usage    : $msaObject->average_sqlen()
  Function : Calculate and return average unaligned sequence length
           : in the MSA.
  Args     : none
  Returns  : average unaligned sequence length

  rfam_qc_stats
  Title    : rfam_qc_stats
  Incept   : EPN, Fri Feb  1 10:29:11 2013
  Usage    : $msaObject->rfam_qc_stats($fam_outfile, $seq_outfile, $bp_outfile)
  Function : Calculate per-family, per-sequence and per-basepair stats for a
           : SS_cons annotated RNA alignment and output it.
           : See 'Purpose' section of _c_rfam_qc_stats() C function in
           : MSA.c for more information.
  Args     : fam_outfile: name of output file for per-family stats
           : seq_outfile: name of output file for per-sequence stats
           : bp_outfile:  name of output file for per-basepair stats
  Returns  : void

  setDesc
  Title    : setDesc
  Incept   : EPN, Tue Mar 21 13:35:18 2017
  Usage    : $msaObject->setDesc($value)
  Function : Set the description line of an ESL_MSA object.
  Args     : $value: text for the line
  Returns  : void

  setAccession
  Title    : setAccession
  Incept   : EPN, Tue Mar 21 13:36:34 2017
  Usage    : $msaObject->setAccession($value)
  Function : Set the accession field of an ESL_MSA object.
  Args     : $value: text for the line
  Returns  : void

  getDesc
  Title    : getDesc
  Incept   : EPN, Tue Mar 21 10:18:25 2017
  Usage    : $msaObject->getDesc()
  Function : Return description line of an ESL_MSA
           : as a string, or "" if it does not exist
  Args     : none
  Returns  : $descstr: desc annotation, as a string.

  getAccession
  Title    : getAccession
  Incept   : EPN, Tue Mar 21 10:20:41 2017
  Usage    : $msaObject->getAccession()
  Function : Return accession field of an ESL_MSA
           : as a string, or "" if it does not exist
  Args     : none
  Returns  : $accstr: accession, as a string.

  addGF
  Title    : addGF
  Incept   : EPN, Fri Feb  1 17:43:38 2013
  Usage    : $msaObject->addGF($tag, $value)
  Function : Add GF tag/value to a C ESL_MSA object.
  Args     : $tag:   two letter tag
           : $value: text for the line
  Returns  : void

  addGS
  Title    : addGS
  Incept   : EPN, Fri Feb  1 17:43:38 2013
  Usage    : $msaObject->addGF($tag, $value)
  Function : Add GS tag/value for a specific sequence
           : to a C ESL_MSA object.
  Args     : $tag:   two letter tag
           : $value: text for the line
           : $sqidx: seq index to add GS for
  Returns  : void
  Dies     : via croak() if seq $sqidx doesn't exist

  addGC
  Title    : addGC
  Incept   : EPN, Wed Feb  4 10:54:27 2015
  Usage    : $msaObject->addGC($tag, $annAR)
  Function : Add GC annotation to an ESL_MSA with
           : tag <$tag> and column annotation in
           : the array referenced by <$annAR>
  Args     : $tag: name of GC annotation (e.g. SS_cons)
           : $annAR: ref to array of per-column annotation
           :         must be same size as alignment length.
  Returns  : void

  addGC_identity
  Title    : addGC_identity
  Incept   : EPN, Fri Nov  8 09:31:00 2013
  Usage    : $msaObject->addGC_identity($use_res)
  Function : Add GC annotation to an ESL_MSA with
           : tag 'ID' with a '*' indicating columns
           : for which all sequences have an identical
           : residue, or instead of '*' use the
           : residue itself, if $use_res is 1.
  Args     : $use_res: '1' to use residue for marking 100%
           :          identical columns, '0' to use '*'.
  Returns  : void

  addGC_rf_column_numbers
  Title    : addGC_rf_column_numbers
  Incept   : EPN, Fri Jun 11 13:26:23 2021
  Usage    : $msaObject->addGC_rf_column_numbers()
  Function : Add GC annotation to an ESL_MSA with
           : tag 'RFCOLX...' for RF positions.
  Args     : void
  Returns  : void
  Dies     : via croak() if msa does not have RF annotation

  addGC_all_column_numbers
  Title    : addGC_all_column_numbers
  Incept   : EPN, Fri Jun 11 13:26:23 2021
  Usage    : $msaObject->addGC_all_column_numbers()
  Function : Add GC annotation to an ESL_MSA with
           : tag 'COLX...' for all positions.
  Args     : void
  Returns  : void
  Dies     : via croak() if msa has 0 seqs (should be impossible)

  getGC_given_tag
  Title    : getGC_given_tag
  Incept   : EPN, Wed Feb  4 14:51:03 2015
  Usage    : $msaObject->getGC_given_tag($tag)
  Function : Return GC annotation named <tag> of an ESL_MSA
           : as a string.
  Args     : $tag:    name of GC annotation
  Returns  : $annstr: GC annotation, as a string.

  getGC_given_idx
  Title    : getGC_given_idx
  Incept   : EPN, Wed Feb  4 20:56:31 2015
  Usage    : $msaObject->getGC_given_idx($tagidx)
  Function : Return GC annotation of idx <tagidx> of an ESL_MSA
           : as a string.
  Args     : $tagidx: idx of GC annotation
  Returns  : $annstr: GC annotation, as a string.

  hasGC
  Title    : hasGC
  Incept   : EPN, Wed Feb  4 15:28:23 2015
  Usage    : $msaObject->hasGC($tag)
  Function : Return '1' if GC annotation named <tag> exists,
           : else return '0'.
  Args     : $tag:    name of GC annotation (e.g. SS_cons)
  Returns  : '1' if it exists, else '0'

  getGC_number
  Title    : getGC_number
  Incept   : EPN, Wed Feb  4 17:37:44 2015
  Usage    : $msaObject->getGC_number()
  Function : Return number of GC annotations available.
  Args     : none
  Returns  : number of GC annotations stored in MSA
             (not including SS_cons, SA_cons, PP_cons, RF
              and MM, which are stored in a special way
              (not in msa->gc))

  getGC_tag
  Title    : getGC_tag
  Incept   : EPN, Wed Feb  4 14:51:03 2015
  Usage    : $msaObject->getGC_tag($tagidx)
  Function : Return GC tag of idx <tagidx> as a string
  Args     : $tagidx: idx of tag you want
  Returns  : $tag: string

  getGC_tagidx
  Title    : getGC_tagidx
  Incept   : EPN, Wed Feb  4 21:03:49 2015
  Usage    : $msaObject->getGC_tagidx($tag)
  Function : Return the idx of GC annotation with tag <tag>.
  Args     : $tag: tag of annotation you want idx of
  Returns  : $tagidx: idx of GC annotation
  Dies     : if annotation with tag $tag does not exist.

  addGR
  Title    : addGR
  Incept   : EPN, Wed Jan 29 11:13:04 2020
  Usage    : $msaObject->addGR($tag, $seqidx, $annAR)
  Function : Add GR annotation to an ESL_MSA for sequence
           : <$sqidx> with tag <$tag> and column annotation
           : in the array referenced by <$annAR>
  Args     : $tag:    name of GC annotation (e.g. SS_cons)
           : $sqidx:  seq index to add GR for [0..nseq-1]
           : $annstr: string that is the per-residue annotation
           :          must be same length as alignment length.
  Returns  : void

  addGR_seq_position_numbers
  Title    : addGR_seq_position_numbers
  Incept   : EPN, Fri Jun 11 15:02:07 2021
  Usage    : $msaObject->addGS_seq_position_numbers($sqidx)
  Function : Add GR annotation to an ESL_MSA with
           : tag 'POSX...' indicating the positions of each
           : aligned residue within the sequence
  Args     : void
  Returns  : void
  Dies     : via croak() if seq $sqidx doesn't exist

  addGR_all_seqs_position_numbers
  Title    : addGR_all_seqs_position_numbers
  Incept   : EPN, Mon Jun 14 07:35:39 2021
  Usage    : $msaObject->addGS_all_seqs_position_numbers()
  Function : Add GR annotation to an ESL_MSA with
           : tag 'POSX...' indicating the positions of each
           : aligned residue within the sequence
           : for all sequences
  Args     : void
  Returns  : void

  getGR_given_tag_sqidx
  Title    : getGR_given_tag_sqidx
  Incept   : EPN, Wed Jan 29 11:47:34 2020
  Usage    : $msaObject->getGR_given_tag_sqidx($tag, $sqidx)
  Function : Return GR annotation named <tag> of an ESL_MSA
           : for sequence <$sqidx> as a string.
  Args     : $tag:    name of GR annotation
           : $sqidx:  sequence index [0..nseq-1]
  Returns  : $annstr: GR annotation, as a string.

  getGR_given_tagidx_sqidx
  Title    : getGR_given_tagidx_sqidx
  Incept   : EPN, Wed Jan 29 12:16:41 2020
  Usage    : $msaObject->getGR_given_tagidx_sqidx($tagidx, $sqidx)
  Function : Return GR annotation of idx <tagidx> of an ESL_MSA
           : for sequence <$sqidx> as a string.
  Args     : $tagidx: idx of GR annotation
           : $sqidx:  sequence index [0..nseq-1]
  Returns  : $annstr: GR annotation, as a string.

  hasGR_given_tag_sqidx
  Title    : hasGR_given_tag_sqidx
  Incept   : EPN, Wed Jan 29 11:29:32 2020
  Usage    : $msaObject->hasGR_given_tag_sqidx($tag, $sqidx)
  Function : Return '1' if GR annotation named <tag> exists
           : for sequence index $sqidx (0..$nseq-1),
           : else return '0'.
  Args     : $tag:   name of unparsed GR annotation
           : $sqidx: seq index we are interested in
  Returns  : '1' if it exists, else '0'

  hasGR_given_tagidx_sqidx
  Title    : hasGR_given_tagidx_sqidx
  Incept   : EPN, Wed Jan 29 12:22:16 2020
  Usage    : $msaObject->hasGR_given_tagidx_sqidx($tagidx, $sqidx)
  Function : Return '1' if GR annotation with tag idx <tagidx> exists
           : for sequence index $sqidx (0..$nseq-1),
           : else return '0'.
  Args     : $tagidx: index of tag (not including SS, SA, PP)
           : $sqidx:  seq index we are interested in
  Returns  : '1' if it exists, else '0'

  hasGR_any_sqidx_given_tag
  Title    : hasGR_any_sqidx_given_tag
  Incept   : EPN, Wed Jan 29 12:44:00 2020
  Usage    : $msaObject->hasGR_given_tag_any_seqidx($tag)
  Function : Return '1' if GR annotation named <tag> exists
           : for any sequence index
           : else return '0'.
  Args     : $tag:   name of unparsed GR annotation
  Returns  : '1' if it exists, else '0'

  hasGR_any_sqidx_given_tagidx
  Title    : hasGR_any_sqidx_given_tagidx
  Incept   : EPN, Wed Jan 29 12:46:50 2020
  Usage    : $msaObject->hasGR_any_sqidx_given_tagidx($tagidx)
  Function : Return '1' if GR annotation with tag idx <tagidx> exists
           : else return '0'.
  Args     : $tagidx: index of tag (not including SS, SA, PP)
  Returns  : '1' if it exists, else '0'

  getGR_number
  Title    : getGR_number
  Incept   : EPN, Wed Jan 29 12:19:28 2020
  Usage    : $msaObject->getGR_number()
  Function : Return number of GR annotations available.
  Args     : none
  Returns  : number of GR annotations stored in MSA
             (not including SS, SA, and PP,
               which are stored in a special way
              (not in msa->gr))

  getGR_tag
  Title    : getGR_tag
  Incept   : EPN, Wed Jan 29 12:28:39 2020
  Usage    : $msaObject->getGR_tag($tagidx)
  Function : Return GR tag of idx <tagidx> as a string
  Args     : $tagidx: idx of tag you want
  Returns  : $tag: string

  getGR_tagidx
  Title    : getGR_tagidx
  Incept   : EPN, Wed Jan 29 12:29:44 2020
  Usage    : $msaObject->getGR_tagidx($tag)
  Function : Return the idx of GR annotation with tag <tag>.
  Args     : $tag: tag of annotation you want idx of
  Returns  : $tagidx: idx of GR annotation
  Dies     : if annotation with tag $tag does not exist.

  weight_GSC
  Title    : weight_GSC
  Incept   : EPN, Fri May 24 10:42:44 2013
  Usage    : $msaObject->weight_GSC($tag, $value)
  Function : Compute and annotate MSA with sequence weights using the
           : GSC algorithm. Dies with croak if something goes wrong.
  Args     : none
  Returns  : void

  free_msa
  Title    : free_msa
  Incept   : EPN, Mon Jan 28 11:06:18 2013
  Usage    : $msaObject->free_msa()
  Function : Frees an MSA->{$esl_msa} object
  Args     : name of output file
  Returns  : void

  revert_to_original
  Title    : revert_to_original
  Incept   : EPN, Sat Feb  2 14:53:27 2013
  Usage    : $msaObject->revert_to_original()
  Function : Frees current $msaObject->{esl_msa} object
             and rereads it from $msaObject->{path}
  Args     : none
  Returns  : void

  weight_id_filter
  Title     : weight_id_filter
  Incept    : March 1, 2013
  Usage     : $msaObject->weight_id_filter($idf)
  Function  : performs id weight filtering on the msa object
  Args      : Identity floating point from 0 to 1, id ratio above which will be filtered
  Returns   : void

  filter_msa_subset_target_nseq
  Title     : filter_msa_subset_target_nseq
  Incept    : EPN, Thu Nov 21 13:40:52 2013
  Usage     : $msaObject->filter_msa_subset_target_nseq($idf)
  Function  : Filter a subset of sequences in an MSA such that no
            : two sequences in the filtered subset are more than $idf
            : fractionally identical, where $idf is the maximum value
            : that results in <= $nseq sequences (within 0.01, that is,
            : $idf + 0.01 gives > $nseq sequences).
            : $idf is found by a binary search.
  Args      : $usemeAR:  [0..$i..$self->nseq]: '1' if we should consider sequence $i, else ignore it.
            :            set to all '1' to consider all sequences in the msa.
            : $nseq:     fractional identity threshold no pair of seqs in $keepmeAR will exceed
            : $keepmeAR: [0..$i..$self->nseq]: '1' if seq $i survives the filtering.
            :            note that $keepmeAR->[$i] can only be '1' if $usemeAR->[$i] is also '1'.
  Returns   : $idf:   the fractional identity used to fill keepmeAR
            : $nkeep: number of '1' in keepmeAR

  filter_msa_subset
  Title     : filter_msa_subset
  Incept    : EPN, Thu Nov 21 13:30:15 2013
  Usage     : $nkept = $msaObject->filter_msa_subset($usmeAR, $idf, $keepmeAR)
  Function  : Filter a subset of sequences in an MSA such that no
            : two sequences in the filtered subset are more than $idf
            : fractionally identical.
            : Similar to weight_id_filter() except does not create a new
            : MSA of only the filtered set, and this function is flexible
            : to only considering a subset of the passed in alignment.
  Args      : $usemeAR:  [0..$i..$self->nseq]: '1' if we should consider sequence $i, else ignore it.
            : $idf:      fractional identity threshold no pair of seqs in $keepmeAR will exceed
            : $keepmeAR: [0..$i..$self->nseq]: '1' if seq $i survives the filtering.
            :            note that $keepmeAR->[$i] can only be '1' if $usemeAR->[$i] is also '1'.
  Returns   : Number of sequences that are '1' in $keepmeAR upon exit.

  alignment_coverage
  Title     : alignment_coverage_id
  Incept    : March 5, 2013
  Usage     : $msaObject->alignment_coverage_id()
  Function  : determine coverage ratios of msa
  Args      : None
  Returns   : Success:
                Array from 0 to msa->alen, contains decimals from 0 to 1
                representing coverage ratio of that msa position
              Failure:
                Nothing

  count_msa
  Title     : count_msa
  Incept    : EPN, Fri Jul  5 13:46:51 2013
  Usage     : $msaObject->count_msa()
  Function  : Count residues and basepairs in an MSA
  Args      : None
  Returns   :

  pairwise_identity
  Title     : pairwise_identity
  Incept    : EPN, Wed Aug 21 10:19:07 2013
  Usage     : $msaObject->pairwise_identity($i, $j)
  Function  : Return fractional identity between seqs $i and $j in the MSA
  Args      : None
  Returns   : fraction identity of i and j

  check_if_prefix_added_to_sqnames
  Title     : check_if_prefix_added_to_sqnames
  Incept    : EPN, Fri Nov  1 15:15:12 2013
  Usage     : $msaObject->check_if_prefix_added_to_sqnames
  Function  : Return '1' if it appears that prefixes were added
            : to all sqnames in the MSA, by Easel to avoid two
            : sequences having an identical name.
  Args      : None
  Returns   : '1' of '0'

  remove_prefix_from_sqname
  Title     : remove_prefix_from_sqname
  Incept    : EPN, Fri Nov  1 15:25:27 2013
  Usage     : $msaObject->remove_prefix_from_sqname
  Function  : Remove a numerical prefix from a sequence name.
            : Only meant to be used for MSAs for which
            : check_if_prefix_added_to_sqnames returned
            : TRUE (which had numerical prefixes added to
            : sqnames to avoid duplicate names).
  Args      : $sqname
  Returns   : $sqname with numerical prefix removed.
  Dies      : If $sqname does not have a numerical prefix,
            : this means caller does not know what its doing.

  clone_msa
  Title     : clone_msa
  Incept    : EPN, Thu Nov 21 09:38:23 2013
  Usage     : $newmsaObject = $msaObject->clone_msa()
  Function  : Creates a new MSA, a duplicate of $self.
  Args      : None
  Returns   : $new_msa: a new Bio::Easel::MSA object, a duplicate of $self

  reorder_all
  Title     : reorder_msa_all
  Incept    : EPN, Mon Feb  3 14:32:59 2014
  Usage     : $msaObject->reorder_all
  Function  : Reorder all sequences in an MSA by swapping pointers.
  Args      : $nameorderAR: [0..i..nseq-1] ref to array with names
            :               of sequences in preferred order.
  Returns   : void
  Dies      : If not all sequences are listed exactly once in $nameorderAR.

  sequence_subset
  Title     : sequence_subset
  Incept    : EPN, Thu Nov 14 10:24:50 2013
  Usage     : $newmsaObject = $msaObject->sequence_subset($usemeAR)
  Function  : Create a new MSA containing a subset of the
            : sequences in a passed in MSA.
            : Keep any sequence with index i if
            : usemeAR->[i] == 1, else remove it.
            : All gap columns will not be removed from the MSA,
            : caller may want to do that immediately with
            : remove_all_gap_columns().
  Args      : $usemeAR: [0..i..nseq-1] ref to array with value
            :           '1' to keep seq i, '0' to remove it
  Returns   : $new_msa: a new Bio::Easel::MSA object, with
            :           a subset of the sequences in $self.

  sequence_subset_given_names
  Title     : sequence_subset_given_names
  Incept    : EPN, Tue Feb  4 09:17:37 2014
  Usage     : $newmsaObject = $msaObject->sequence_subset_given_names($nameAR)
  Function  : Create a new MSA containing a subset of the
            : sequences in a passed in MSA.
            : Keep any sequence with name listed in @{$nameAR}
            : All gap columns will not be removed from the MSA,
            : caller may want to do that immediately with
            : remove_all_gap_columns().
  Args      : $nameAR: ref to array with list of names of seqs to keep
  Returns   : $new_msa: a new Bio::Easel::MSA object, with
            :           a subset of the sequences in $self.

  sequence_subset_and_reorder
  Title     : sequence_subset_and_reorder
   Incept    : EPN, Tue Feb  4 08:54:13 2014
  Usage     : $newmsaObject = $msaObject->sequence_subset_and_reorder($nameorderAR)
  Function  : Create a new MSA containing a subset of the
            : sequences in a passed in MSA reordered to
            : the order in @{$nameorderAR}.
            : @{$nameorderAR} contains a subset of the sequences
            : in the MSA with no duplicates.
            : All gap columns will not be removed from the MSA,
            : caller may want to do that immediately with
            : remove_all_gap_columns().
  Args      : $nameorderAR: names of sequences to put in subset in desired order.
  Returns   : $new_msa: a new Bio::Easel::MSA object, with
            :           a subset of the sequences in $self,
            :           reordered to the order in @{$nameorderAR}.

  column_subset
  Title     : column_subset
  Incept    : EPN, Thu Nov 14 10:24:50 2013
  Usage     : $msaObject->column_subset($usemeAR)
  Function  : Remove a subset of columns from an MSA.
            : If the column for one half of a SS_cons basepair is
            : removed but not the other half, the basepair
            : will be removed from SS_cons.
  Args      : $usemeAR: [0..i..alen-1] ref to array with value
            :           '1' to keep column i, '0' to remove it
  Returns   : void

  column_subset_rename_nse
  Title     : column_subset_rename_nse
  Incept    : EPN, Thu Apr 17 09:59:48 2014
  Usage     : $msaObject->column_subset_rename_nse($usemeAR)
  Function  : Remove a subset of columns from an MSA and
            : add /start-end to the end of all of the names
            : in the alignment. All removed residues must be at terminii
            : (no 'internal' residues can be removed).
            :
            : For example, imagine a 3 seq alignment:
            : seq1/5-9   AAAAA
            : seq2/12-13 --AA-
            : seq3       AABAA
            : with a @{$usemeAR} of (0, 0, 1, 1, 0).
            :
            : The returned alignment would be:
            : seq1/5-9/3-4    AA
            : seq2/12-13/1-2  AA
            : seq3/3-4        BA
            :
            : If ($do_update == 1) the behavior of this function
            : changes to updating any sequences that are already in
            : name/start-end format so that '/start-end'
            : are consistent with removed residues at the alignment
            : ends. In the above example, the returned alignment
            : would be:
            : seq1/7-8    AA
            : seq2/12-13  AA
            : seq3        BA
            :
            : Note the first sequence has been renamed, the second
            : has not because no residues were removed. The third
            : did have residues removed but it is not in
            : "name/start-end" format so it was not renamed.
            :
            :
  Dies      : If any internal residues (non-terminii) are going to be removed.
            :
  Args      : $usemeAR: [0..i..alen-1] ref to array with value
            :           '1' to keep column i, '0' to remove it
  Returns   : void

  remove_all_gap_columns
  Title     : remove_all_gap_columns
  Incept    : EPN, Thu Nov 14 13:39:42 2013
  Usage     : $msaObject->remove_all_gap_columns
  Function  : Remove all gap columns from an MSA.
            : If the column for one half of a SS_cons basepair is
            : removed but not the other half, the basepair
            : will be removed from SS_cons.
  Args      : $consider_rf: '1' to not delete any nongap RF column, else '0'
  Returns   : void
  Dies      : upon an error with croak

  remove_rf_gap_columns
  Title     : remove_rf_gap_columns
  Incept    : EPN, Thu Nov 21 10:07:07 2013
  Usage     : $msaObject->remove_rf_gap_columns
  Function  : Remove any column from an MSA that is a gap (exists in $gapstr)
            : in the GC RF annotation of the MSA.
  Args      : $gapstr: string of characters to consider as gaps,
            :             if undefined we use '.-~'
  Returns   : void
  Dies      : upon an error with croak

  find_divergent_seqs_from_subset
  Title     : find_divergent_seqs_from_subset
  Incept    : EPN, Thu Nov 21 08:41:06 2013
  Usage     : $msaObject->find_divergent_seqs_from_subset
  Function  : Given a subset of sequences, find all other sequences
            : not in the subset that are <= $id_thr fractionally
            : identical to *all* seqs in the subset.
  Args      : $subsetAR: [0..$i..$msa->nseq-1] '1' if sequence i is in the subset, else 0
            : $id_thr:   fractional identity threshold
            : $divAR:    FILLED HERE: [0..$i..$msa->nseq-1] ref to array, '1'  if a sequence
            :            is <= $id_thr fractionally identical to all seqs in subset, else 0
            : $nnidxAR:  FILLED HERE: [0..$i..$msa->nseq-1] ref to array, index of nearest
            :            neighbor (index that is '1' in subsetAR) if $divAR->[$i] == 1, else -1
            : $nnfidAR:  FILLED HERE: [0..$i..$msa->nseq-1] ref to array, index of fractional
            :            identity to nearest neighbor, if $divAR->[$i] == 1, else 0.
            : Example: if sequence idx 5 is $id_thr or less fractionally identical to all
            :          sequences in the subset, but closest to sequence index 11 at 0.73,
            :          then $divAR->[5] = 1, $nnidxAR->[5] = 11, $nnfidAR->[5] = 0.73.
  Returns   : Number of divergent seqs found. This will also be the size of @{$divAR}, @{$nnidxAR} and @{$nnfidAR}
  Dies      : if no sequences exist in $subsetAR, or any indices are invalid
            : with croak

  find_most_divergent_seq_from_subset
  Title     : find_most_divergent_seq_from_subset
  Incept    : EPN, Thu Nov 21 08:41:06 2013
  Usage     : $msaObject->find_most_divergent_seq_from_subset
  Function  : Given a subset of sequences, find all other sequences
            : not in the subset that are <= $id_thr fractionally
            : identical to *all* seqs in the subset.
  Args      : $subsetAR: [0..$i..$msa->nseq-1] '1' if sequence i is in the subset, else 0
  Returns   : $idx: Index of sequence in $msa that is most divergent from all seqs in
            :       subsetAR, that is, the sequence for which the fractional identity
            :       to its closest neighbor in subsetAR is minimized.
            : $fid: fractional identity of idx to its closest neighbor in msa
            : $nnidx: idx of <$idx>s nearest neighbor in $msa
  Dies      : if no sequences exist in $subsetAR, or any indices are invalid
            : with croak

  avg_min_max_pid_to_seq
  Title    : avg_min_max_pid_to_seq
  Incept   : EPN, Fri Nov 22 08:53:56 2013
  Usage    : $msaObject->avg_min_max_pid_to_seq($i);
  Function : Calculates the average, minimum and maximum
           : fractional identity of seq $idx to all other seqs.
           : If optional parameter, $usemeAR is passed in
           : then only consider sequences $j for which
           : $usemeAR->[$j] is '1' (except $idx even if
           : $usemeAR->[$idx] is '1').
  Args     : $idx:     index of sequence we want avg/min/max pid to
           : $usemeAR: OPTIONAL: if defined:
           :           [0..$j..nseq-1]: '1' if we should consider
           :           seq $j in calculation of avg/min/max.
  Returns  : $avg_pid: average fractional id b/t $idx and all other seqs
           : $min_pid: minimum fractional id b/t $idx and all other seqs
           : $min_idx: index of seq that gives $min_pid to $idx
           : $max_pid: minimum fractional id b/t $idx and all other seqs
           : $max_idx: index of seq that gives $max_pid to $idx

  create_from_string
  Title     : create_from_string
  Incept    : EPN, Fri Nov 29 07:03:12 2013
  Usage     : $newmsaObject = Bio::Easel::MSA::create_from_string($msa_str, $format)
  Function  : Create a new MSA from a string that is a properly
            : formatted MSA in format <$format>. If $format is undefined
            : we will use Easels format autodetection capability.
            : If <$do_digitize> we will digitize the alignment before
            : returning, if this is undefined, we do it anyway since
            : most of the BioEasel MSA code requires a digitized MSA.
            :
  Args      : $msa_str:     the string that is an MSA
            : $format:      string defining format of $msa_str.
            :               valid format strings are:
            :               "stockholm", "pfam", "a2m", "phylip", "phylips", "psiblast",
            :               "selex", "afa", "clustal", "clustallike", "unknown", or undefined
            : $abc:         string defining alphabet of MSA, valid options:
            :               "amino", "rna", "dna", "coins", "dice", "custom"
            : $do_digitize: '1' to digitize alignment, '0' not do, use '1' unless you know
            :               what you are doing.
  Returns   : $new_msa: a new Bio::Easel::MSA object, created
            :           from $msa_str

  is_residue
  Title     : is_residue
  Incept    : EPN, Fri Nov 29 17:05:44 2013
  Usage     : $msaObject->is_residue($sqidx, $apos)
  Function  : Return '1' if alignment position $apos of sequence $sqidx
            : is a residue, and '0' if not.
  Args      : $sqidx:   sequence index in MSA
            : $apos:    alignment position [1..alen]
  Returns   : '1' if position $apos of $sqidx is a residue, else '0'
  Dies      : with 'croak' if sequence $sqidx or apos $apos is invalid

  capitalize_based_on_rf
  Title     : capitalize_based_on_rf
  Incept    : EPN, Tue Feb 18 10:44:11 2014
  Usage     : $msaObject->capitalize_based_on_rf
  Function  : Set all residues in nongap RF columns as uppercase,
            : and all gap characters ('.-_') to '-'. Set all residues
            : in gap RF columns to lowercase and all gap characters
            : '.-_' to '.'.
  Args      : none
  Returns   : void
  Dies      : if RF annotation does not exist, or alignment is not in text mode.

  get_all_GF
  Title     : get_all_GF
  Incept    : EPN, Thu May  8 13:40:50 2014
  Usage     : $msaObject->get_all_GF
  Function  : Get all GF annotation for an MSA by filling a passed in hash.
  Args      : none
  Returns   : void

  most_informative_sequence
  Title     : most_informative_sequence
  Incept    : EPN, Thu May 15 13:16:06 2014
  Usage     : $msaObject->most_informative_sequence
  Function  : Calculate the "most informative sequence" (Freyhult, Moulton and Gardner, 2005)
            : Taken from pre-2013 Rfam codebase (Rfam/RfamAlign.pm module).
            : Website definition: "Any residue that has
            : a higher frequency than than the background frequency is projected
            : into the IUPAC redundancy codes."
  Args      : $gapthresh: only columns with >= $gapthresh nongaps will be converted to a nongap residue in the most informative sequence
            : $use_weights: '1' to use weights in the MSA, '0' not to
  Returns   : a string, the most informative sequence

  pos_fcbp
  Title     : pos_fcbp
  Incept    : EPN, Mon May 19 13:23:33 2014
  Usage     : $msaObject->pos_fcbp
  Function  : Calculate the fraction of canonical basepairs for each nongap RF position in a MSA.
  Args      : none
  Returns   : array of length msa->alen: the fraction of canonical bps
            : at each position, 0. for non-paired positions.

  pos_covariation
  Title     : pos_covariation
  Incept    : EPN, Tue May 20 09:23:26 2014
  Usage     : $msaObject->pos_covariation
  Function  : Calculate the 'RNAalifold covariation statistic (Lindgreen, Gardner, Krogh, 2006)'
            : for each basepair in an alignment and return as an array [0..alen-1].
  Args      : none
  Returns   : array of length msa->alen: the covariation statistic
            : at each position, 0. for non-paired positions.

  pos_entropy
  Title     : pos_entropy
  Incept    : EPN, Tue May 20 10:44:33 2014
  Usage     : $msaObject->pos_entropy
  Function  : Calculate and return the entropy at each position of an msa.
  Args      : $use_weights: '1' to use weights in the MSA, '0' not to
  Returns   : array of length msa->alen: the entropy at each posn

  pos_conservation
  Title     : pos_conservation
  Incept    : EPN, Tue May 20 15:00:12 2014
  Usage     : $msaObject->pos_conservation
  Function  : Calculate and return the 'sequence conservation' at each position of an msa.
            : 'sequence conservation' of a position is the maximum frequency of any
            :  residue in a column, where frequency is number of occurences divided by
            :  number of sequences (so no column with >=1 gap can have a conservation of 1.0).
            :  And all gap columns have a conservation of 0.0.
  Args      : $use_weights: '1' to use weights in the MSA, '0' not to
  Returns   : array of length msa->alen: the 'sequence conservation' at each posn

  remove_gap_rf_basepairs
  Title     : remove_gap_rf_basepairs
  Incept    : EPN, Fri Jan 29 16:19:17 2016
  Usage     : $msaObject->remove_gap_rf_basepairs
  Function  : Remove any basepair (i,j) (by setting both positions to a '.')
            : in MSA->SS_cons for which exactly one or both of
            : i and j maps to a gap in the RF annotation.
            : This works with pseudoknots.
  Args      : $do_wussify: '1' to convert SS_cons to full WUSS notation after removing gap-RF basepairs, '0' not to
  Returns   : void, msa->ss_cons is updated
  Dies      : if msa->ss_cons is inconsistent

  aligned_to_unaligned_pos
  Title     : aligned_to_unaligned_pos
  Incept    : EPN, Thu Jul 14 15:31:16 2016
  Usage     : $msaObject->aligned_to_unaligned_pos($sqidx, $apos)
  Function  : Return the unaligned position $uapos [1..ualen] of
            : sequence $sqidx that is aligned at position $apos
            : of the MSA.
            :
            : $apos could be a gap for $sqidx. In this case, the behavior
            : depends on the value of the argument $do_after. If $do_after is
            : '0' or undefined, then:
            :    - return $uapos for alignment position $ret_apos, where $ret_apos
            :      is not a gap for $sqidx and $ret_apos is the highest possible
            :      value that is less than $apos.
            :    - if all alignment positions 1..$apos are gaps for $sqidx
            :      we return -1 for both $uapos and for $ret_apos.
            :
            : If $do_after is '1', then:
            :    - return $uapos for alignment position $ret_apos, where $ret_apos
            :      is not a gap for $sqidx and $ret_apos is the lowest possible
            :      value that is greater than $apos.
            :    - if all alignment positions $apos..$alen are gaps for $sqidx
            :      we return -1 for both $uapos and for $ret_apos.
            :
  Args      : $sqidx:   index of sequence we are interested in
            : $apos:     alignment position we are interested it
            : $do_after: '1' to return $ret_apos > $apos if $apos is
            :            a gap, '0' to return $ret_apos < $apos if
            :            $apos is a gap, can be undef -- treated as 0.
  Returns   : $uapos:    unaligned position that aligns at $ret_apos,
            :            can be -1 in special circumstances (see 'Function'
            :            section above).
            : $ret_apos: the aligned position that $uapos corresponds to,
            :            this will be $apos (passed in) if alignment position
            :            $apos is not a gap. See 'function' section above
            :            for explanation of what it is if $apos is a gap.
  Dies      : if $apos is < 0 or $apos > $alen

  rfpos_to_aligned_pos
  Title     : rfpos_to_aligned_pos
  Incept    : EPN, Mon Jul 18 15:11:02 2016
  Usage     : $msaObject->rfpos_to_aligned_pos($rfpos)
  Function  : Return the alignment position corresponding to RF position
            : (nongap in GC RF annotation) $rfpos.
            :
  Args      : $rfpos:  RF position we are interested in
            : $gapstr: string of characters to consider as gaps,
            :          if undefined we use '.-~'
  Returns   : $apos:   alignment position (1..$alen) that $rfpos corresponds
            :          to
  Dies      : if $rfpos is < 0 or $rfpos > $rflen (number of nongap RF positions)
            : if $self->{esl_msa} does not have RF annotation

  get_pp_avg
  Title    : get_pp_avg
  Incept   : EPN, Mon Aug 29 15:38:37 2016
  Usage    : $msaObject->get_pp_avg()
  Function : Return the average posterior probability of an aligned sequence
           : for positions spos to epos.
  Args     : <idx>:  index of sequence you want avg PP for [0..nseq-1]
           : <spos>: first aligned position you want avg PP for (pass 1 for first position) [1..alen]
           : <epos>: final aligned position you want avg PP for (pass msa->alen for final position) [1..alen]
  Returns  : two values:
           :   1) average aligned posterior probability annotation for sequence index idx from aligned positions spos..epos
           :   2) number of nongap positions for sequence index idx from aligned positions spos..epos

  get_ppstr_avg
  Title    : get_ppstr_avg
  Incept   : EPN, Wed Jan 29 09:45:37 2020
  Usage    : Bio::Easel::MSA::get_ppstr_avg($ppstr)
  Function : Return the average posterior probability of a posterior probability
           : string, potentially with gaps.
  Args     : <ppstr>:  string of posterior probability values, possible with gaps (.)
  Returns  : two values:
           :   1) average aligned posterior probability annotation for sequence index idx from aligned positions spos..epos
           :   2) number of nongap positions for sequence index idx from aligned positions spos..epos

  DESTROY
  Title    : DESTROY
  Incept   : EPN, Mon Jan 28 10:09:55 2013
  Usage    : $msaObject->DESTROY()
  Function : Frees an MSA object
  Args     : none
  Returns  : void

  _check_msa
  Title    : _check_msa
  Incept   : EPN, Sat Feb  2 13:42:27 2013
  Usage    : $msaObject->_check_msa()
  Function : Reads msa only if it is currently undefined
  Args     : none
  Returns  : void

  _check_sqidx
  Title    : _check_sqidx
  Incept   : EPN, Sat Feb  2 13:46:08 2013
  Usage    : $msaObject->_check_sqidx($idx)
  Function : Check if $idx is in range 0..nseq-1,
             if not, croak.
  Args     : $idx
  Returns  : void

  _check_ppidx
  Title    : _check_ppidx
  Incept   : EPN, Mon Jul  7 09:14:06 2014
  Usage    : $msaObject->_check_ppidx($idx)
  Function : Check if $idx is in range 0..nseq-1,
           : and that the MSA has PP annoation for $idx
  Args     : $idx
  Returns  : void
  Dies     : via croak if no PP annotation exists for sequence $idx

  _check_saidx
  Title    : _check_saidx
  Incept   : EPN, Fri Feb 19 15:19:55 2021
  Usage    : $msaObject->_check_saidx($idx)
  Function : Check if $idx is in range 0..nseq-1,
           : and that the MSA has SA annoation for $idx
  Args     : $idx
  Returns  : void
  Dies     : via croak if no SA annotation exists for sequence $idx

  _check_ssidx
  Title    : _check_ssidx
  Incept   : EPN, Fri Feb 19 15:19:58 2021
  Usage    : $msaObject->_check_ssidx($idx)
  Function : Check if $idx is in range 0..nseq-1,
           : and that the MSA has SS annoation for $idx
  Args     : $idx
  Returns  : void
  Dies     : via croak if no SS annotation exists for sequence $idx

  _check_ax_apos
  Title    : _check_ax_apos
  Incept   : EPN, Fri Nov 29 17:09:11 2013
  Usage    : $msaObject->_check_ax_apos($apos)
  Function : Check if $apos is in range 1..alen,
             if not, croak.
  Args     : $apos
  Returns  : void

  _check_aseq_apos
  Title    : _check_aseq_apos
  Incept   : EPN, Fri Nov 29 17:09:11 2013
  Usage    : $msaObject->_check_aseq_apos($apos)
  Function : Check if $apos is in range 0..alen-1,
             if not, croak.
  Args     : $apos
  Returns  : void

  _check_reqd_format
  Title    : _check_reqd_format
  Incept   : EPN, Thu Jul 18 11:06:02 2013
  Usage    : $msaObject->_check_reqd_format()
  Function : Check if $self->{reqdFormat} is a valid format or 'unknown'
           : if not, croak. Also returns fine if self->{reqdFormat} is not
           : defined.
  Args     : none
  Returns  : void

  _check_index
  Title    : _check_index
  Incept   : EPN, Mon Feb  3 15:17:21 2014
  Usage    : $msaObject->_check_index()
  Function : Check if an MSA has a hash and if not, create one.
  Args     : none
  Returns  : void
  Dies     : If no index exists and unable to create one.

  _sqname_nse_breakdown
  Title    : _sqname_nse_breakdown
  Incept   : EPN, Thu Apr 17 10:05:51 2014
  Usage    : $msaObject->_sqname_nse_breakdown($i)
  Function : Checks if sequence $i name is of format "name/start-end" and if so
           : breaks it down into $n, $s, $e, $str (see 'Returns' section)
  Args     : <sqname>: seqname, possibly of format "name/start-end"
  Returns  : 5 values:
           :   '1' if seqname was of "name/start-end" format, else '0'
           :   $n:   name ("" if seqname does not match "name/start-end")
           :   $s:   start, maybe <= or > than $e (0 if seqname does not match "name/start-end")
           :   $e:   end,   maybe <= or > than $s (0 if seqname does not match "name/start-end")
           :   $str: strand, 1 if $s <= $e, else -1

  _check_all_sqname_nse
  Title    : _check_all_sqname_nse
  Incept   : EPN, Thu Apr 17 10:06:36 2014
  Usage    : $msaObject->_check_all_sqname_nse()
  Function : Check if all sequence names in the msa are in 'name/start-end' format.
           : If so, return '1', else return '0'.
  Args     : none
  Returns  : '1' if all sequence names are in name/start-end format, else '0'.

  _get_nongap_numbering_for_aligned_string
  Title    : _get_nongap_numbering_for_aligned_string
  Incept   : EPN, Fri Jun 11 12:22:30 2021
  Usage    : _get_nongap_numbering_for_aligned_string($aligned_sqstring, $gap_str, $gap_char, $num_str_AR)
  Function : Fill @{$num_str_AR} with strings that given numbering for nongap columns.
           : Example:               AGCGA--GCGACG-GACG.GG
           : Returns:
           :    @{$num_str_AR->[0]} 00000..000011.1111.11
           :    @{$num_str_AR->[1]} 12345..678901.2345.67
  Args     : $aligned_sqstring: aligned seq string for a sequence or RF (or other)
           : $num_str_AR:       RETURN: filled with N numberings, where N is number of digits in
           :                    unaligned length of $aligned_sqstring
           : $gap_str:          string with characters that are gaps in $aligned_sqstring (e.g. ".-~";), set to ""
           :                    to number ALL columns (even gap ones)
           : $gap_char:         character to use for gaps in @{$num_str_AR}
           :
  Returns  : void, fills @{$num_str_AR}

  _c_read_msa =head2 _c_write_msa =head2 _c_nseq =head2 _c_alen =head2 _c_get_accession =head2 _c_set_accession =head2 _c_get_sqname =head2 _c_set_sqname =head2 _c_any_allgap_columns =head2 _c_average_id =head2 _c_get_sqlen =head2 _c_average_sqlen =head2 _c_addGF =head2 _c_addGS =head2 _c_count_msa =head2 _c_bp_is_canonical =head2 _c_calc_and_write_bp_stats =head2 dl_load_flags

AUTHORS
Eric Nawrocki, "<nawrocke at ncbi.nlm.nih.gov>" Jody Clements, "<clementsj at janelia.hhmi.org>" Rob Finn, "<rdf at ebi.ac.uk>" William Arndt, "<warndt at lbl.gov>"

BUGS
Please report any bugs or feature requests to "bug-bio-easel at rt.cpan.org".

SUPPORT
You can find documentation for this module with the perldoc command.

    perldoc Bio::Easel::MSA

ACKNOWLEDGEMENTS
Sean R. Eddy is the author of the Easel C library of functions for biological sequence analysis, upon which this module is based.

LICENSE AND COPYRIGHT
Copyright 2013 Eric Nawrocki.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.