.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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::ClusterIO 3pm"
.TH Bio::ClusterIO 3pm "2022-03-27" "perl v5.34.0" "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::ClusterIO \- Handler for Cluster Formats
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  #NB: This example is unigene specific
\&
\&  use Bio::ClusterIO;
\&
\&  $stream  = Bio::ClusterIO\->new(\*(Aq\-file\*(Aq => "Hs.data", 
\&                                 \*(Aq\-format\*(Aq => "unigene");
\&  # note: we quote \-format to keep older perl\*(Aqs from complaining.
\&
\&  while ( my $in = $stream\->next_cluster() ) {
\&      print $in\->unigene_id() . "\en";
\&      while ( my $sequence = $in\->next_seq() ) {
\&          print $sequence\->accession_number() . "\en";
\&      }
\&  }
\&  # Parsing errors are printed to STDERR.
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The ClusterIO module works with the ClusterIO format module to read
various cluster formats such as \s-1NCBI\s0 UniGene.
.SH "CONSTRUCTORS"
.IX Header "CONSTRUCTORS"
.SS "Bio::ClusterIO\->\fBnew()\fP"
.IX Subsection "Bio::ClusterIO->new()"
.Vb 2
\&   $str = Bio::ClusterIO\->new(\-file => \*(Aqfilename\*(Aq,
\&                              \-format=>$format);
.Ve
.PP
The \fBnew()\fR class method constructs a new Bio::ClusterIO object.  The
returned object can be used to retrieve or print cluster
objects. \fBnew()\fR accepts the following parameters:
.IP "\-file" 4
.IX Item "-file"
A file path to be opened for reading.
.IP "\-format" 4
.IX Item "-format"
Specify the format of the file.  Supported formats include:
.Sp
.Vb 2
\&   unigene              *.data  UniGene build files.
\&   dbsnp                *.xml   dbSNP XML files
.Ve
.Sp
If no format is specified and a filename is given, then the module
will attempt to deduce it from the filename.  If this is unsuccessful,
the main UniGene build format is assumed.
.Sp
The format name is case insensitive.  '\s-1UNIGENE\s0', 'UniGene' and
\&'unigene' are all supported, as are dbSNP, dbsnp, and \s-1DBSNP\s0
.SH "OBJECT METHODS"
.IX Header "OBJECT METHODS"
See below for more detailed summaries.  The main methods are:
.ie n .SS "$cluster = $str\->\fBnext_cluster()\fP"
.el .SS "\f(CW$cluster\fP = \f(CW$str\fP\->\fBnext_cluster()\fP"
.IX Subsection "$cluster = $str->next_cluster()"
Fetch the next cluster from the stream.
.SS "\s-1\fBTIEHANDLE\s0()\fP, \s-1\fBREADLINE\s0()\fP, \s-1\fBPRINT\s0()\fP"
.IX Subsection "TIEHANDLE(), READLINE(), PRINT()"
These I've left in here because they were in the SeqIO
module. Feedback appreciated. There they provide the tie interface.
See perltie for more details.
.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.  Bug reports can be submitted via the
web:
.PP
.Vb 1
\&  https://github.com/bioperl/bioperl\-live/issues
.Ve
.SH "AUTHOR \- Andrew Macgregor"
.IX Header "AUTHOR - Andrew Macgregor"
Email andrew@anatomy.otago.ac.nz
.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 6
\& Title   : new
\& Usage   : Bio::ClusterIO\->new(\-file => $filename, \-format => \*(Aqformat\*(Aq)
\& Function: Returns a new cluster stream
\& Returns : A Bio::ClusterIO::Handler initialised with the appropriate format
\& Args    : \-file => $filename
\&           \-format => format
.Ve
.SS "format"
.IX Subsection "format"
.Vb 5
\& Title   : format
\& Usage   : $format = $stream\->format()
\& Function: Get the cluster format
\& Returns : cluster format
\& Args    : none
.Ve
.SS "next_cluster"
.IX Subsection "next_cluster"
.Vb 5
\& Title   : next_cluster
\& Usage   : $cluster = $stream\->next_cluster()
\& Function: Reads the next cluster object from the stream and returns it.
\& Returns : a L<Bio::ClusterI> compliant object
\& Args    : none
.Ve
.SS "cluster_factory"
.IX Subsection "cluster_factory"
.Vb 8
\& Title   : cluster_factory
\& Usage   : $obj\->cluster_factory($newval)
\& Function: Get/set the object factory to use for creating the cluster
\&           objects.
\& Example : 
\& Returns : a L<Bio::Factory::ObjectFactoryI> compliant object
\& Args    : on set, new value (a L<Bio::Factory::ObjectFactoryI> 
\&           compliant object or undef, optional)
.Ve
.SS "object_factory"
.IX Subsection "object_factory"
.Vb 7
\& Title   : object_factory
\& Usage   : $obj\->object_factory($newval)
\& Function: This is an alias to cluster_factory with a more generic name.
\& Example : 
\& Returns : a L<Bio::Factory::ObjectFactoryI> compliant object
\& Args    : on set, new value (a L<Bio::Factory::ObjectFactoryI> 
\&           compliant object or undef, optional)
.Ve
.SS "_load_format_module"
.IX Subsection "_load_format_module"
.Vb 6
\& Title   : _load_format_module
\& Usage   : *INTERNAL ClusterIO stuff*
\& Function: Loads up (like use) a module at run time on demand
\& Example :
\& Returns :
\& Args    :
.Ve
.SS "_guess_format"
.IX Subsection "_guess_format"
.Vb 7
\& Title   : _guess_format
\& Usage   : $obj\->_guess_format($filename)
\& Function: guess format based on file suffix
\& Example :
\& Returns : guessed format of filename (lower case)
\& Args    :
\& Notes   : formats that _filehandle() will guess include unigene and dbsnp
.Ve