.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Bio::LiveSeq::Chain 3pm"
.TH Bio::LiveSeq::Chain 3pm "2018-10-27" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bio::LiveSeq::Chain \- DoubleChain DataStructure for Perl
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  #documentation needed
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a general purpose module (that's why it's not in object-oriented
form) that introduces a novel datastructure in \s-1PERL.\s0 It implements
the \*(L"double linked chain\*(R". 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 \s-1DNA\s0 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.
.PP
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 \s-1NEXT\s0 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 \*(L"LABELs\*(R".
There is one \s-1LABEL\s0 (think of it as a pointer) to each \s-1ELEMENT.\s0 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.
.SH "AUTHOR \- Joseph A.L. Insana"
.IX Header "AUTHOR - Joseph A.L. Insana"
Email:  Insana@ebi.ac.uk, jinsana@gmx.net
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object
methods. Internal methods are usually preceded with a _
.SS "_updown_chain2string"
.IX Subsection "_updown_chain2string"
.Vb 10
\&  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
.Ve
.SS "_updown_labels"
.IX Subsection "_updown_labels"
.Vb 8
\& 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)
.Ve
.SS "start"
.IX Subsection "start"
.Vb 5
\& Title   : start
\& Usage   : $start = Bio::LiveSeq::Chain::start()
\& Returns : the label marking the start of the chain
\& Errorcode: \-1
\& Args    : none
.Ve
.SS "end"
.IX Subsection "end"
.Vb 5
\& Title   : end
\& Usage   : $end = Bio::LiveSeq::Chain::end()
\& Returns : the label marking the end of the chain
\& Errorcode: \-1
\& Args    : none
.Ve
.SS "label_exists"
.IX Subsection "label_exists"
.Vb 7
\& 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
.Ve
.SS "down_get_pos_of_label"
.IX Subsection "down_get_pos_of_label"
.Vb 11
\& 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
.Ve
.SS "down_subchain_length"
.IX Subsection "down_subchain_length"
.Vb 7
\& 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
.Ve
.SS "invert_chain"
.IX Subsection "invert_chain"
.Vb 6
\& 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
.Ve
.SS "down_get_value_at_pos"
.IX Subsection "down_get_value_at_pos"
.Vb 7
\& 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
.Ve
.SS "down_set_value_at_pos"
.IX Subsection "down_set_value_at_pos"
.Vb 10
\& 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\*(Aqt remove the element from the chain.
.Ve
.SS "down_set_value_at_label"
.IX Subsection "down_set_value_at_label"
.Vb 10
\& 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\*(Aqt remove the element from the chain.
.Ve
.SS "down_get_value_at_label"
.IX Subsection "down_get_value_at_label"
.Vb 7
\& 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
.Ve
.SS "down_get_label_at_pos"
.IX Subsection "down_get_label_at_pos"
.Vb 7
\& 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
.Ve
.SS "_praepostinsert_array"
.IX Subsection "_praepostinsert_array"
.Vb 8
\& 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)
.Ve
.SS "is_downstream"
.IX Subsection "is_downstream"
.Vb 9
\&  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)
.Ve
.SS "is_upstream"
.IX Subsection "is_upstream"
.Vb 9
\&  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)
.Ve
.SS "check_chain"
.IX Subsection "check_chain"
.Vb 9
\& 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.
.Ve
.SS "splice_chain"
.IX Subsection "splice_chain"
.Vb 10
\& 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
.Ve
.SS "array2chain"
.IX Subsection "array2chain"
.Vb 9
\&  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")
.Ve