Bio::S...::table(3pm)

📦
version 1.7.8 · 3 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

Bio::SeqIO::table 💅✨

sequence input/output stream from a delimited table

okay bestie, this page lives in the User Contributed Perl Documentation section of the manual (you'll see it filed under Bio::S...::table(3pm)), and it's literally the glow-up guide for turning boring spreadsheet-looking text files into actual Bio::Seq objects. let's get into it 🎀

✨ NAME ✨

Bio::SeqIO::table — sequence input/output stream from a delimited table

✨ SYNOPSIS ✨

  # Do not to use this object directly, use Bio::SeqIO, for example:

  $in = Bio::SeqIO->new(-file => $filename, -format => 'table');

  while ( my $seq = $in->next_seq() ) {
        # do something with $seq
  }
no cap, don't touch this class directly, go through Bio::SeqIO like a civilized icon 💅

✨ DESCRIPTION ✨

so basically this class takes records in a table-formatted text file and transforms them into Bio::Seq objects. it's giving glow up, but for spreadsheets. 🦋

for this module's purposes, a "table-formatted text file of sequence records" is defined as a text file where each row = one sequence, and the sequence's attributes live in different columns. columns get split apart by a common delimiter — think tab, or comma, whatever your heart desires. 💖

the module lets you say which column holds which type of annotation. some attributes have pre-defined semantics if they show up (hi, accession number and sequence 👋). and you can absolutely add extra attributes onto the annotation bundle. slay.

✨ FEEDBACK ✨

Mailing Lists

user feedback is literally 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. 🫶

  bioperl-l@bioperl.org                  - General discussion
  http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

Support

please direct usage questions or support issues to the mailing list:

bioperl-l@bioperl.org

rather than sliding into the module maintainer's DMs directly. there are so many experienced and responsive experts who will 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. 🙏

Reporting Bugs

report bugs to the Bioperl bug tracking system so we can keep track of the bugs and their resolutions. it's the responsible main character move. 👑

bug reports can be submitted via email or the web:

  https://github.com/bioperl/bioperl-live/issues

✨ AUTHOR - Hilmar Lapp ✨

Email hlapp at gmx.net

✨ APPENDIX ✨

the rest of the docs get into the deets of each object method. internal methods usually get a _ slapped in front of them, iykyk. 💀

new

  • Title: new
  • Usage: $stream = Bio::SeqIO->new(-file => $filename, -format => 'table')
  • 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) that introduce 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 it's not a number, it'll be used as the static species common to all records
    • -annotation — if provided and it's a scalar (but see below 👇), it's a flag for whether or not all additional columns are to be preserved as annotation. the tags used will either be 'colX' if there's no column header (where X is the one-based column index), and otherwise the column headers will be used as tags;

if it's 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 it's 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).

next_seq

  • Title: next_seq
  • Usage: $seq = $stream->next_seq()
  • Function: returns the next sequence in the stream
  • Returns: Bio::Seq::RichSeq object
  • Args: (none)

comment_char

  • Title: comment_char
  • Usage: $obj->comment_char($newval)
  • Function: get/set the leading character(s) designating a line as a comment-line.
  • Example: (none)
  • Returns: value of comment_char (a scalar)
  • Args: on set, new value (a scalar or undef, optional)
  • 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, it means there is no header and therefore also no column headers.

  • Example: (none)
  • Returns: value of header (a scalar)
  • Args: on set, new value (a scalar or undef, optional)

delimiter

  • 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: (none)
  • Returns: value of delimiter (a scalar)
  • Args: on set, new value (a scalar or undef, optional)

attribute_map

  • 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: (none)
  • Returns: value of attribute_map (a reference to a hash)
  • Args: on set, new value (a reference to a hash or undef, optional)

annotation_map

  • 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: (none)
  • Returns: value of annotation_map (a reference to a hash)
  • Args: on set, new value (a reference to a hash or undef, optional)

keep_annotation

  • 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't referenced in the attribute map.

  • Example: (none)
  • Returns: value of keep_annotation (a scalar)
  • Args: on set, new value (a scalar or undef, optional)

annotation_columns

  • 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: (none)
  • Returns: value of annotation_columns (a reference to an array)
  • Args: on set, new value (a reference to an array of undef, optional)

trim_values

  • 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: (none)
  • Returns: value of trim_values (a scalar)
  • Args: on set, new value (a scalar or undef, optional)

write_seq

  • Title: write_seq
  • Usage: write_seq() is not implemented for table format output.

✨ Internal methods ✨

Every method with a leading underscore is not part of the 'official' API, bestie. They're for this module's own use only — treat them as private unless you're a developer actively trying to modify this module. iykyk 💅

🎀 _attribute_map

Title: _attribute_map

Usage: $obj->_attribute_map($newval)

Function: Get only. Same as attribute_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 _attribute_map (a reference to a hash)

Args: none

🦋 _annotation_map

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

🌸 _header_skipped

Title: _header_skipped

Usage: $obj->_header_skipped($newval)

Function: Get/set the flag for 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)

🔥 _next_record

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 exists to serve as a hook for other formats that conceptually also represent tables but aren't 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:

🌈 _parse_header

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 exists to serve as a hook for other formats that conceptually also represent tables but aren't 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:

⭐ _get_row_values

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 exists to serve as a hook for other formats that conceptually also represent tables but aren't formatted as row-based text files.

Example:

Returns: An array of column values for the current row.

Args:

okay bestie that's the whole page, you made it, congrats, main character energy fr fr 🫶 this lil time capsule was perl v5.32.1, stamped 2021-08-15, and it's the Bio::S...::table(3pm) page from the User Contributed Perl Documentation. slay 💖✨

📦 where this page comes from