Provided by: libbio-perl-perl_1.6.923-1_all bug

NAME

       Bio::LiveSeq::Chain - DoubleChain DataStructure for Perl

SYNOPSIS

         #documentation needed

DESCRIPTION

       This is a general purpose module (that's why it's not in object-oriented form) that
       introduces a novel datastructure in PERL. It implements the "double linked chain". The
       elements of the chain can contain basically everything. From chars to strings, from object
       references to arrays or hashes.  It is used in the LiveSequence project to create a
       dynamical DNA sequence, easier to manipulate and change. It's use is mainly for sequence
       variation analysis but it could be used - for example - in e-cell projects.  The Chain
       module in itself doesn't have any biological bias, so can be used for any programming
       purpose.

       Each element of the chain (with the exclusion of the first and the last of the chain) is
       connected to other two elements (the PREVious and the NEXT one).  There is no absolute
       position (like in an array), hence if positions are important, they need to be computed
       (methods are provided).  Otherwise it's easy to keep track of the elements with their
       "LABELs".  There is one LABEL (think of it as a pointer) to each ELEMENT. The labels won't
       change after insertions or deletions of the chain. So it's always possible to retrieve an
       element even if the chain has been modified by successive insertions or deletions.  From
       this the high potential profit for bioinformatics: dealing with sequences in a way that
       doesn't have to rely on positions, without the need of constantly updating them if the
       sequence changes, even dramatically.

AUTHOR - Joseph A.L. Insana

       Email:  Insana@ebi.ac.uk, jinsana@gmx.net

APPENDIX

       The rest of the documentation details each of the object methods. Internal methods are
       usually preceded with a _

   _updown_chain2string
         Title   : chain2string
         Usage   : $string = Bio::LiveSeq::Chain::chain2string("down",$chain,6,9)
         Function: reads the contents of the chain, outputting a string
         Returns : a string
         Examples:
                 : down_chain2string($chain) -> all the chain from begin to end
                 : down_chain2string($chain,6) -> from 6 to the end
                 : down_chain2string($chain,6,4) -> from 6, going on 4 elements
                 : down_chain2string($chain,6,"",10) -> from 6 to 10
                 : up_chain2string($chain,10,"",6) -> from 10 to 6 upstream
         Defaults: start=first element; if len undef, goes to last
                   if last undef, goes to end
                   if last defined, it overrides len (undefining it)
         Error code: -1
         Args    : "up"||"down" as first argument to specify the reading direction
                   reference (to the chain)
                   [first] [len] [last] optional integer arguments to specify how
                   much and from (and to) where to read

   _updown_labels
        Title   : labels
        Usage   : @labels = Bio::LiveSeq::Chain::_updown_labels("down",$chain,4,16)
        Function: returns all the labels in a chain or those between two
                  specified ones (termed "first" and "last")
        Returns : a reference to an array containing the labels
        Args    : "up"||"down" as first argument to specify the reading direction
                  reference (to the chain)
                  [first] [last] (integer for the starting and eneding labels)

   start
        Title   : start
        Usage   : $start = Bio::LiveSeq::Chain::start()
        Returns : the label marking the start of the chain
        Errorcode: -1
        Args    : none

   end
        Title   : end
        Usage   : $end = Bio::LiveSeq::Chain::end()
        Returns : the label marking the end of the chain
        Errorcode: -1
        Args    : none

   label_exists
        Title   : label_exists
        Usage   : $check = Bio::LiveSeq::Chain::label_exists($chain,$label)
        Function: It checks if a label is defined, i.e. if an element is there or
                  is not there anymore
        Returns : 1 if the label exists, 0 if it is not there, -1 error
        Errorcode: -1
        Args    : reference to the chain, integer

   down_get_pos_of_label
        Title   : down_get_pos_of_label
        Usage   : $position = Bio::LiveSeq::Chain::down_get_pos_of_label($chain,$label,$first)
        Function: returns the position of $label counting from $first, i.e. taking
                  $first as 1 of coordinate system. If $first is not specified it will
                  count from the start of the chain.
        Returns :
        Errorcode: 0
        Args    : reference to the chain, integer (the label of interest)
                  optional: integer (a different label that will be taken as the
                  first one, i.e. the one to count from)
        Note:     It counts "downstream". To proceed backward use up_get_pos_of_label

   down_subchain_length
        Title   : down_subchain_length
        Usage   : $length = Bio::LiveSeq::Chain::down_subchain_length($chain,$first,$last)
        Function: returns the length of the chain between the labels "first" and "last", included
        Returns : integer
        Errorcode: 0
        Args    : reference to the chain, integer, integer
        Note:     It counts "downstream". To proceed backward use up_subchain_length

   invert_chain
        Title   : invert_chain
        Usage   : $errorcode=Bio::LiveSeq::Chain::invert_chain($chain)
        Function: completely inverts the order of the chain elements; begin is swapped with end and all links updated (PREV&NEXT fields swapped)
        Returns : 1 if all OK, 0 if errors
        Errorcode: 0
        Args    : reference to the chain

   down_get_value_at_pos
        Title   : down_get_value_at_pos
        Usage   : $value = Bio::LiveSeq::Chain::down_get_value_at_pos($chain,$position,$first)
        Function: used to access the value of the chain at a particular position instead than directly with a label pointer. It will count the position from the start of the chain or from the label $first, if $first is specified
        Returns : whatever is stored in the element of the chain
        Errorcode: 0
        Args    : reference to the chain, integer, [integer]
        Note:     It works "downstream". To proceed backward use up_get_value_at_pos

   down_set_value_at_pos
        Title   : down_set_value_at_pos
        Usage   : $errorcode = Bio::LiveSeq::Chain::down_set_value_at_pos($chain,$newvalue,$position,$first)
        Function: used to store a new value inside an element of the chain at a particular position instead than directly with a label pointer. It will count the position from the start of the chain or from the label $first, if $first is specified
        Returns : 1
        Errorcode: 0
        Args    : reference to the chain, newvalue, integer, [integer]
                  (newvalue can be: integer, string, object reference, hash ref)
        Note:     It works "downstream". To proceed backward use up_set_value_at_pos
        Note2:    If the $newvalue is undef, it will delete the contents of the
                  element but it won't remove the element from the chain.

   down_set_value_at_label
        Title   : down_set_value_at_label
        Usage   : $errorcode = Bio::LiveSeq::Chain::down_set_value_at_label($chain,$newvalue,$label)
        Function: used to store a new value inside an element of the chain defined by its label.
        Returns : 1
        Errorcode: 0
        Args    : reference to the chain, newvalue, integer
                  (newvalue can be: integer, string, object reference, hash ref)
        Note:     It works "downstream". To proceed backward use up_set_value_at_label
        Note2:    If the $newvalue is undef, it will delete the contents of the
                  element but it won't remove the element from the chain.

   down_get_value_at_label
        Title   : down_get_value_at_label
        Usage   : $value = Bio::LiveSeq::Chain::down_get_value_at_label($chain,$label)
        Function: used to access the value of the chain from one element defined by its label.
        Returns : whatever is stored in the element of the chain
        Errorcode: 0
        Args    : reference to the chain, integer
        Note:     It works "downstream". To proceed backward use up_get_value_at_label

   down_get_label_at_pos
        Title   : down_get_label_at_pos
        Usage   : $label = Bio::LiveSeq::Chain::down_get_label_at_pos($chain,$position,$first)
        Function: used to retrieve the label of an an element of the chain at a particular position. It will count the position from the start of the chain or from the label $first, if $first is specified
        Returns : integer
        Errorcode: 0
        Args    : reference to the chain, integer, [integer]
        Note:     It works "downstream". To proceed backward use up_get_label_at_pos

   _praepostinsert_array
        Title   : _praepostinsert_array
        Usage   : ($insbegin,$insend) = Bio::LiveSeq::Chain::_praepostinsert_array($chainref,"post",$arrayref,$position)
        Function: the elements of the array specified by $arrayref are inserted (creating a new subchain) in the chain specified by $chainref, before or after (depending on the "prae"||"post" keyword passed as second argument) the specified position.
        Returns : two labels: the first and the last of the inserted subchain
        Defaults: if no position is specified, the new chain will be inserted after
        (post) the first element of the chain
        Errorcode: 0
        Args    : chainref, "prae"||"post", arrayref, integer (position)

   is_downstream
         Title   : is_downstream
         Usage   : Bio::LiveSeq::Chain::is_downstream($chainref,$firstlabel,$secondlabel)
         Function: checks if SECONDlabel follows FIRSTlabel
                   It runs downstream the elements of the chain from FIRST searching
                   for SECOND.
         Returns : 1 if SECOND is found /after/ FIRST; 0 otherwise (i.e. if it
                   reaches the end of the chain without having found it)
         Errorcode -1
         Args    : two labels (integer)

   is_upstream
         Title   : is_upstream
         Usage   : Bio::LiveSeq::Chain::is_upstream($chainref,$firstlabel,$secondlabel)
         Function: checks if SECONDlabel follows FIRSTlabel
                   It runs upstream the elements of the chain from FIRST searching
                   for SECOND.
         Returns : 1 if SECOND is found /after/ FIRST; 0 otherwise (i.e. if it
                   reaches the end of the chain without having found it)
         Errorcode -1
         Args    : two labels (integer)

   check_chain
        Title   : check_chain
        Usage   : @errorcodes = Bio::LiveSeq::Chain::check_chain()
        Function: a wraparound to a series of check for consistency of the chain
                  It will check for boundaries, size, backlinking and forwardlinking
        Returns : array of 4 warn codes, each can be 1 (all ok) or 0 (something wrong)
        Errorcode: 0
        Args    : none
        Note    : this is slow and through. It is not really needed. It is mostly
                  a code-developer tool.

   splice_chain
        Title   : splice_chain
        Usage   : @errorcodes = Bio::LiveSeq::Chain::splice_chain($chainref,$first,$length,$last)
        Function: removes the elements designated by FIRST and LENGTH from a chain.
                  The chain shrinks accordingly. If LENGTH is omitted, removes
                  everything from FIRST onward.
                  If END is specified, LENGTH is ignored and instead the removal
                  occurs from FIRST to LAST.
        Returns : the elements removed as a string
        Errorcode: -1
        Args    : chainref, integer, integer, integer

   array2chain
         Title   : array2chain
         Usage   : $chainref = Bio::LiveSeq::Chain::array2chain($arrayref,$offset)
         Function: creation of a double linked chain from an array
         Returns : reference to a hash containing the chain
         Defaults: OFFSET defaults to 1 if undef
         Error code: 0
         Args    : a reference to an array containing the elements to be chainlinked
                   an optional integer > 0 (this will be the starting count for
                   the chain labels instead than having them begin from "1")