.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bio::SeqIO::table 3pm"
.TH Bio::SeqIO::table 3pm "2021-08-15" "perl v5.32.1" "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::SeqIO::table \- sequence input/output stream from a delimited table
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  # Do not to use this object directly, use Bio::SeqIO, for example:
\&
\&  $in = Bio::SeqIO\->new(\-file => $filename, \-format => \*(Aqtable\*(Aq);
\&
\&  while ( my $seq = $in\->next_seq() ) {
\&        # do something with $seq
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class transforms records in a table-formatted text file into
Bio::Seq objects.
.PP
A table-formatted text file of sequence records for the purposes of
this module is defined as a text file with each row corresponding to a
sequence, and the attributes of the sequence being in different
columns. Columns are delimited by a common delimiter, for instance tab
or comma.
.PP
The module permits specifying which columns hold which type of
annotation. The semantics of certain attributes, if present, are
pre-defined, e.g., accession number and sequence. Additional
attributes may be added to the annotation bundle.
.SH "FEEDBACK"
.IX Header "FEEDBACK"
.SS "Mailing Lists"
.IX Subsection "Mailing Lists"
User feedback is an integral part of the evolution of this and other
Bioperl modules. Send your comments and suggestions preferably to one
of the Bioperl mailing lists.  Your participation is much appreciated.
.PP
.Vb 2
\&  bioperl\-l@bioperl.org                  \- General discussion
\&  http://bioperl.org/wiki/Mailing_lists  \- About the mailing lists
.Ve
.SS "Support"
.IX Subsection "Support"
Please direct usage questions or support issues to the mailing list:
.PP
\&\fIbioperl\-l@bioperl.org\fR
.PP
rather than to the module maintainer directly. Many experienced and 
reponsive experts will be able look at the problem and quickly 
address it. Please include a thorough description of the problem 
with code and data examples if at all possible.
.SS "Reporting Bugs"
.IX Subsection "Reporting Bugs"
Report bugs to the Bioperl bug tracking system to help us keep track
the bugs and their resolution.
.PP
Bug reports can be submitted via email or the web:
.PP
.Vb 1
\&  https://github.com/bioperl/bioperl\-live/issues
.Ve
.SH "AUTHOR \- Hilmar Lapp"
.IX Header "AUTHOR - Hilmar Lapp"
Email hlapp at 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 "new"
.IX Subsection "new"
.Vb 5
\& Title   : new
\& Usage   : $stream = Bio::SeqIO\->new(\-file => $filename, \-format => \*(Aqtable\*(Aq)
\& Function: Returns a new seqstream
\& Returns : A Bio::SeqIO stream for a table format
\& Args    : Named parameters:
\&
\& \-file              Name of file to read
\& \-fh                Filehandle to attach to
\& \-comment           Leading character(s) introducing a comment line
\& \-header            the number of header lines to skip; the first
\&                    non\-comment header line will be used to obtain
\&                    column names; column names will be used as the
\&                    default tags for attaching annotation.
\& \-delim             The delimiter for columns as a regular expression;
\&                    consecutive occurrences of the delimiter will
\&                    not be collapsed.
\& \-display_id        The one\-based index of the column containing
\&                    the display ID of the sequence
\& \-accession_number  The one\-based index of the column
\&                    containing the accession number of the sequence
\& \-seq               The one\-based index of the column containing
\&                    the sequence string of the sequence
\& \-desc              The one\-based index of the column containing
\&                    the description of the sequence
\& \-species           The one\-based index of the column containing the
\&                    species for the sequence record; if not a
\&                    number, will be used as the static species
\&                    common to all records
\& \-annotation        If provided and a scalar (but see below), a
\&                    flag whether or not all additional columns are
\&                    to be preserved as annotation, the tags used
\&                    will either be \*(AqcolX\*(Aq if there is no column
\&                    header and where X is the one\-based column
\&                    index, and otherwise the column headers will be
\&                    used as tags;
\&
\&                    If a reference to an array, or a square
\&                    bracket\-enclosed string of comma\-delimited
\&                    values, only those columns (one\-based index)
\&                    will be preserved as annotation, tags as before;
\&
\&                    If a reference to a hash, or a curly
\&                    braces\-enclosed string of comma\-delimited key
\&                    and value pairs in alternating order, the keys
\&                    are one\-based column indexes to be preserved,
\&                    and the values are the tags under which the
\&                    annotation is to be attached; if not provided or
\&                    supplied as undef, no additional annotation will
\&                    be preserved.
\& \-colnames          A reference to an array of column labels, or a
\&                    string of comma\-delimited labels, denoting the
\&                    columns to be converted into annotation; this is
\&                    an alternative to \-annotation and will be
\&                    ignored if \-annotation is also supplied with a
\&                    valid value.
\& \-trim              Flag determining whether or not all values should
\&                    be trimmed of leading and trailing white space
\&                    and double quotes
\&
\& Additional arguments may be used to e.g. set factories and
\& builders involved in the sequence object creation (see the
\& POD of Bio::SeqIO).
.Ve
.SS "next_seq"
.IX Subsection "next_seq"
.Vb 5
\& Title   : next_seq
\& Usage   : $seq = $stream\->next_seq()
\& Function: returns the next sequence in the stream
\& Returns : Bio::Seq::RichSeq object
\& Args    :
.Ve
.SS "comment_char"
.IX Subsection "comment_char"
.Vb 7
\& Title   : comment_char
\& Usage   : $obj\->comment_char($newval)
\& Function: Get/set the leading character(s) designating a line as
\&           a comment\-line.
\& Example :
\& Returns : value of comment_char (a scalar)
\& Args    : on set, new value (a scalar or undef, optional)
.Ve
.SS "header"
.IX Subsection "header"
.Vb 4
\& Title   : header
\& Usage   : $obj\->header($newval)
\& Function: Get/set the number of header lines to skip before the
\&           rows containing actual sequence records.
\&
\&           If set to zero or undef, means that there is no header and
\&           therefore also no column headers.
\&
\& Example :
\& Returns : value of header (a scalar)
\& Args    : on set, new value (a scalar or undef, optional)
.Ve
.SS "delimiter"
.IX Subsection "delimiter"
.Vb 5
\& Title   : delimiter
\& Usage   : $obj\->delimiter($newval)
\& Function: Get/set the column delimiter. This will in fact be
\&           treated as a regular expression. Consecutive occurrences
\&           will not be collapsed to a single one.
\&
\& Example :
\& Returns : value of delimiter (a scalar)
\& Args    : on set, new value (a scalar or undef, optional)
.Ve
.SS "attribute_map"
.IX Subsection "attribute_map"
.Vb 4
\& Title   : attribute_map
\& Usage   : $obj\->attribute_map($newval)
\& Function: Get/set the map of sequence object initialization
\&           attributes (keys) to one\-based column index.
\&
\&           Attributes will usually need to be prefixed by a dash, just
\&           as if they were passed to the new() method of the sequence
\&           class.
\&
\& Example :
\& Returns : value of attribute_map (a reference to a hash)
\& Args    : on set, new value (a reference to a hash or undef, optional)
.Ve
.SS "annotation_map"
.IX Subsection "annotation_map"
.Vb 4
\& Title   : annotation_map
\& Usage   : $obj\->annotation_map($newval)
\& Function: Get/set the mapping between one\-based column indexes
\&           (keys) and annotation tags (values).
\&
\&           Note that the map returned by this method may change after
\&           the first next_seq() call if the file contains a column
\&           header and no annotation keys have been predefined in the
\&           map, because upon reading the column header line the tag
\&           names will be set automatically.
\&
\&           Note also that the map may reference columns that are used
\&           as well in the sequence attribute map.
\&
\& Example :
\& Returns : value of annotation_map (a reference to a hash)
\& Args    : on set, new value (a reference to a hash or undef, optional)
.Ve
.SS "keep_annotation"
.IX Subsection "keep_annotation"
.Vb 4
\& Title   : keep_annotation
\& Usage   : $obj\->keep_annotation($newval)
\& Function: Get/set flag whether or not to keep values from
\&           additional columns as annotation.
\&
\&           Additional columns are all those columns in the input file
\&           that aren\*(Aqt referenced in the attribute map.
\&
\& Example :
\& Returns : value of keep_annotation (a scalar)
\& Args    : on set, new value (a scalar or undef, optional)
.Ve
.SS "annotation_columns"
.IX Subsection "annotation_columns"
.Vb 4
\& Title   : annotation_columns
\& Usage   : $obj\->annotation_columns($newval)
\& Function: Get/set the names (labels) of the columns to be used for
\&           annotation.
\&
\&           This is an alternative to using annotation_map. In order to
\&           have any effect, it must be set before the first call of
\&           next_seq(), and obviously there must be a header line (or
\&           row) too giving the column labels.
\&
\& Example :
\& Returns : value of annotation_columns (a reference to an array)
\& Args    : on set, new value (a reference to an array of undef, optional)
.Ve
.SS "trim_values"
.IX Subsection "trim_values"
.Vb 7
\& Title   : trim_values
\& Usage   : $obj\->trim_values($newval)
\& Function: Get/set whether or not to trim leading and trailing
\&           whitespace off all column values.
\& Example :
\& Returns : value of trim_values (a scalar)
\& Args    : on set, new value (a scalar or undef, optional)
.Ve
.SS "write_seq"
.IX Subsection "write_seq"
.Vb 2
\& Title: write_seq
\& Usage: write_seq() is not implemented for table format output.
.Ve
.SH "Internal methods"
.IX Header "Internal methods"
All methods with a leading underscore are not meant to be part of the
\&'official' \s-1API.\s0 They are for use by this module only, consider them
private unless you are a developer trying to modify this module.
.SS "_attribute_map"
.IX Subsection "_attribute_map"
.Vb 3
\& Title   : _attribute_map
\& Usage   : $obj\->_attribute_map($newval)
\& Function: Get only. Same as attribute_map, but zero\-based indexes.
\&
\&           Note that any changes made to the returned map will change
\&           the map used by this instance. You should know what you are
\&           doing if you modify the returned value (or if you call this
\&           method in the first place).
\&
\& Example :
\& Returns : value of _attribute_map (a reference to a hash)
\& Args    : none
.Ve
.SS "_annotation_map"
.IX Subsection "_annotation_map"
.Vb 3
\& Title   : _annotation_map
\& Usage   : $obj\->_annotation_map($newval)
\& Function: Get only. Same as annotation_map, but with zero\-based indexes.
\&
\&           Note that any changes made to the returned map will change
\&           the map used by this instance. You should know what you are
\&           doing if you modify the returned value (or if you call this
\&           method in the first place).
\&
\& Example :
\& Returns : value of _annotation_map (a reference to a hash)
\& Args    : none
.Ve
.SS "_header_skipped"
.IX Subsection "_header_skipped"
.Vb 7
\& Title   : _header_skipped
\& Usage   : $obj\->_header_skipped($newval)
\& Function: Get/set the flag whether the header was already
\&           read (and skipped) or not.
\& Example :
\& Returns : value of _header_skipped (a scalar)
\& Args    : on set, new value (a scalar or undef, optional)
.Ve
.SS "_next_record"
.IX Subsection "_next_record"
.Vb 3
\& Title   : _next_record
\& Usage   :
\& Function: Navigates the underlying file to the next record.
\&
\&           For row\-based records in delimited text files, this will
\&           skip all empty lines and lines with a leading comment
\&           character.
\&
\&           This method is here is to serve as a hook for other formats
\&           that conceptually also represent tables but aren\*(Aqt
\&           formatted as row\-based text files.
\&
\& Example :
\& Returns : TRUE if the navigation was successful and FALSE
\&           otherwise. Unsuccessful navigation will usually be treated
\&           as an end\-of\-file condition.
\& Args    :
.Ve
.SS "_parse_header"
.IX Subsection "_parse_header"
.Vb 3
\& Title   : _parse_header
\& Usage   :
\& Function: Parse the table header and navigate past it.
\&
\&           This method is called if the number of header rows has been
\&           specified equal to or greater than one, and positioned at
\&           the first header line (row). By default the first header
\&           line (row) is used for setting column names, but additional
\&           lines (rows) may be skipped too. Empty lines and comment
\&           lines do not count as header lines (rows).
\&
\&           This method will call _next_record() to navigate to the
\&           next header line (row), if there is more than one header
\&           line (row). Upon return, the file is presumed to be
\&           positioned at the first record after the header.
\&
\&           This method is here is to serve as a hook for other formats
\&           that conceptually also represent tables but aren\*(Aqt
\&           formatted as row\-based text files.
\&
\&           Note however that the only methods used to access file
\&           content or navigate the position are _get_row_values() and
\&           _next_record(), so it should usually suffice to override
\&           those.
\&
\& Example :
\& Returns : TRUE if navigation past the header was successful and FALSE
\&           otherwise. Unsuccessful navigation will usually be treated
\&           as an end\-of\-file condition.
\& Args    :
.Ve
.SS "_get_row_values"
.IX Subsection "_get_row_values"
.Vb 4
\& Title   : _get_row_values
\& Usage   :
\& Function: Get the values for the current line (or row) as an array in
\&           the order of columns.
\&
\&           This method is here is to serve as a hook for other formats
\&           that conceptually also represent tables but aren\*(Aqt
\&           formatted as row\-based text files.
\&
\& Example :
\& Returns : An array of column values for the current row.
\& Args    :
.Ve