Gene_obj(3)

NAME
package Gene_obj

DESCRIPTION
    Gene_obj(s) encapsulate the elements of both gene structure and gene function. The gene structure is stored in a hierarchical fashion as follows:

    Gene  =========================================================

    Exon  =========     =========         =========        ========

    CDS      ======     =========         ======

    where a Gene is a container for Exon(s), and each Exon is a container for a CDS, and an Exon can contain a single CDS component.  An Exon lacking a CDS exon is an untranslated exon or UTR exon.  The region of an Exon which extends beyond the CDS is also considered a UTR.

    There are several ways to instantiate gene objects.  A simple example is described:

    Exon and CDS component coordinates can be assigned as hashes.

    ie.

    my %mrna = ( 100 => 200,
                 300 => 500 );

    my %CDS = ( 150=>200,
                300=>450);

    my $sequence = "GACTACATTTAATAGGGCCC"; #string representing the genomic sequence
    my $gene = new Gene_obj();

    $gene->{com_name} = "hypothetical protein";

    $gene->populate_gene_obj(\%CDS, \%mRNA, \$sequence);
    print $gene->toString();

    Alternatively, the individual components of genes (Exons and CDSs) can be instantiated separately and used to build the Gene from the ground up (See packages mRNA_exon_obj and CDS_exon_obj following this Gene_obj documentation).

    my $cds_exon = new CDS_exon_obj (150, 200);

    my $mRNA_exon = new mRNA_exon_obj (100, 200);

    $mRNA_exon->set_CDS_exon_obj($cds_exon);

    my $gene_obj = new Gene_obj ();

    $gene_obj->{gene_name} = "hypothetical gene";
    $gene_obj->{com_name} = "hypothetical protein";

    $gene_obj->add_mRNA_exon_obj($mRNA_exon);

    $gene_obj->refine_gene_object();

    $gene_obj->create_all_sequence_types (\$sequence);  #ref to genomic sequence string.

    print $gene_obj->toString();

    The API below describes useful functions for navigating and manipulating the Gene object along with all of its attributes.

new()
    Description: Constructor for Gene_obj

    Parameters: none

    Returns: $gene_obj

    The Gene_obj contains several attributes which can be manipulated directly (or by get/set methods if they exist). These attributes include:

        asmbl_id # identifier for the genomic contig for which this gene is anchored.
        TU_feat_name #feat_names are TIGR temporary identifiers.
        Model_feat_name # temp TIGR identifier for gene models
        locus  #identifier for a gene (TU) ie. T2P3.5
        pub_locus  #another identifier for a gene (TU)   ie. At2g00010
        model_pub_locus #identifier for a gene model (model)  ie. At2g00010.1
        model_locus #analagous to locus, but for model rather than gene (TU)
        alt_locus   #alternative locus
        gene_name # name for gene
        com_name  # name for gene product
        comment #internal comment
        pub_comment #comment related to gene
        ec_num   # enzyme commission number
        gene_sym  # gene symbol
        is_5prime_partial # 0|1  missing start codon.
        is_3prime_partial # 0|1  missing stop codon.
        is_pseudogene # 0|1
        curated_com_name # 0|1
        curated_gene_structure # 0|1

        ## Other attributes set internally  Access-only, do not set directly.

        gene_length  # length of gene span (int).
        mid_pt  # holds midpoint of gene-span
        strand  # [+-]
        protein_seq # holds protein sequence
        protein_seq_length
        CDS_sequence  #holds CDS sequence (translated to protein); based on CDS_exon coordinates
        CDS_seq_length
        cDNA_sequence  #holds cDNA sequence; based on mRNA exon coordinates.
        cDNA_seq_length
        gene_sequence #holds unspliced transcript
        gene_sequence_length #length of unspliced transcript
        gene_type # "protein-coding", #default type for gene object.  Could be changed to "rRNA|snoRNA|snRNA|tRNA" to accommodate other gene or feature types.
        num_additional_isoforms # int

erase_gene_structure()
    Description: Removes the structural components of a gene (ie. exons, CDSs, coordinate spans, any corresponding sequences)

    Parameters: none

    Returns: none

clone_gene()
    Description: Clones this Gene_obj by copying attributes from this Gene to a new gene. Does NOT do a deep clone for all attributes. See dclone() for a more rigorous cloning method. This method is safer because all references are not cloned, only the critical ones.

    Parameters: none

    Returns: new Gene_obj

deep_clone()
    Description: Provides a deep clone of a gene_obj. Only references supported in Gene_obj documentation are supported. Those added in a rogue way are undef()d

    Parameters: none

    Returns: $gene_obj

    uses the Storable dclone() function to deep clone the Gene_obj

populate_gene_obj()
    Description: Given CDS and mRNA coordinates stored in hash form, a gene object is populated with mRNA and CDS exons. This is one available way to populate a newly instantiated Gene_obj.

    Parameters: $cds_hash_ref, $mRNA_hash_ref, <$seq_ref>

    $mRNA_hash_ref is a reference to a hash holding the end5 => end3 coordinates of the Exons

    $cds_hash_ref same as mRNA_has_ref except holds the CDS end5 => end3 coordinates.

    $seq_ref is a reference to a string containing the genomic sequence. This is an optional parameter.

    Returns: none

AAToNucleotideCoords()
    Description: Converts an amino acid -based coordinate to a genomic sequence -based coordinate.

    Parameters: $aa_coord

    Returns: $genomic_coord

    undef is returned if the aa_coord could not be converted.

get_gene_span()
    Description: Retrieves the coordinates which span the length of the gene along the genomic sequence.

    Parameters: none

    Returns: (end5, end3)

    These coordinates represent the minimal and maximal exonic coordinates of the gene. Orientation can be inferred by the relative values of end5 and end3.

get_coords()
    Description: See get_gene_span()

    Parameters: none

    Returns: (end5, end3)

get_model_span()
    Description: Retrieves the coordinates spanned by the protein-coding region of the gene along the genomic sequence.

    Parameters: none

    Returns: (end5, end3)

    These coordinates are determined by the min and max of the CDS components of the gene.

get_transcript_span()
    Description: Retrieves the coordinates spanned by the exonic regions of the gene along the genomic sequence.

    Parameters: none

    Returns: (lend, rend)

    These coordinates are determined by the min and max of the CDS components of the gene.

refine_gene_object()
    Description: This method performs some data management operations and should be called at any time modifications have been made to the gene structure (ie. exons added or modified, model isoforms added, etc). It performs the following orientations:

        -Sets (or resets)  gene span and model span coordinates, strand orientation, gene length, mid-point.

    Parameters: none

    Returns: none

get_exons()
    Description:Retrieves a list of exons belonging to this Gene_obj

    Parameters: none

    Returns: @exons

    @exons is an ordered list of mRNA_exon_obj; the first exon of the list corresponds to the first exon of the spliced gene.

number_of_exons()
    Description: Provides the number of exons contained by the Gene

    Parameters: none

    Returns: int

get_intron_coordinates()
    Description: Provides an ordered list of intron coordinates

    Parameters: none

    Returns: ( [end5,end3], ....)

    A list of arrayRefs are returned providing the coordinates of introns, ordered from first intron to last intron within the gene.

add_mRNA_exon_obj()
    Description: Used to add a single mRNA_exon_obj to the Gene_obj

    Parameters: mRNA_exon_obj

    Returns: none

create_all_sequence_types()
    Description: Given a scalar reference to the genomic sequence, the CDS, cDNA, unspliced transcript and protein sequences are constructed and populated within the Gene_obj

    Parameters: $genomic_seq_ref, [%params]

    Returns: 0|1

    returns 1 upon success, 0 upon failure

    By default, the protein and CDS sequence are populated. If you want the unspliced genomic sequence, you need to specify this in the attributes:

        %params = ( potein => 1,
                    CDS => 1,
                    cDNA => 1,
                    unspliced_transcript => 0)

get_protein_sequence()
    Description: Retrieves the protein sequence

    Parameters: none

    Returns: $protein

    Note: You must have called create_all_sequence_types($genomic_ref) before protein sequence is available for retrieval.

get_CDS_sequence()
    Description: Retrieves the CDS sequence. The CDS sequence is the protein-coding nucleotide sequence.

    Parameters: none

    Returns: $cds

    Note: You must have called create_all_sequence_types($genomic_ref) before protein sequence is available for retrieval.

get_cDNA_sequence()
    Description: Retrieves the tentative cDNA sequence for the Gene. The cDNA includes the CDS with potential UTR extensions.

    Parameters: none

    Returns: $cdna

    Note: You must have called create_all_sequence_types($genomic_ref) before protein sequence is available for retrieval.

get_gene_sequence()
    Description: Retrieves the unspliced transcript of the gene.

    Parameters: none

    Returns: $unspliced_transcript

get_gene_synonyms()
    Description: Retrieves the Model_feat_name(s) for the synonomous gene models found on other BACs or contigs.

    Parameters: none

    Returns: @model_feat_names

    For Arabidopsis, gene models are found within overlapping regions of BAC sequences, in which the gene models are annotated on both corresponding BACs. Given a Gene_obj for a model on one BAC, the synomous gene on the overlapping BAC can be identified via this method.

clear_sequence_info()
    Description: Clears the sequence fields stored within a Gene_obj, including the CDS, cDNA, gene_sequence, and protein sequence. Often, these sequence fields, when populated, can consume large amounts of memory in comparison to the coordinate and functional annotation data. This method is useful to clear this memory when the sequences are not needed. The create_all_sequence_types($genomic_seq_ref) can be called again later to repopulate these sequences when they are needed.

    Parameters: none

    Returns: none

set_gene_type()
    Description: Sets the type of gene. Expected types include:

        protein-coding #default setting
        rRNA
        snoRNA
        snRNA
        tRNA

        ...or others as needed.  Nothing is restricted.

    Parameters: $type

    Returns: none

adjust_gene_coordinates()
    Description: Used to add or subtract a specified number of bases from each gene component coordinate.

    Parameters: $adj_amount

    $adj_amoount is a positive or negative integer.

    Returns: none

toString()
    Description: Textually describes the Gene_obj including coordinates and attributes.

    Parameters: <%attributes_list>

    %attributes_list is optional and can control whether certain attributes are included in the textual output

    Default settings are:

        %attributes_list = (
                             -showIsoforms => 1,  #set to 0 to avoid isoform info to the text output.
                             -showSeqs => 0  #set to 1 for avoiding protein, cds, genomic, cdna seqs as output.
                             )

    Returns: $text

validate_splice_sites()
    Description: Validates the presence of consensus splice sites

    Parameters: $genomic_seq_ref

    $genomic_seq_ref is a scalar reference to the string containing the genomic sequence.

    Returns: $errors

    If the empty string ("") is returned, then no inconsistencies were identified.

get_annot_text()
    Description: Provides basic functional annotation for a Gene_obj

    Parameters: none

    Returns: $string

    $string includes locus, pub_locus, com_name, and pub_comment

add_isoform()
    Description: Adds a Gene_obj to an existing Gene_obj as an alternative splicing variant.

    Parameters: Gene_obj

    Returns: none

has_additional_isoforms()
    Description: Provides number of additional isoforms. Typically used as a boolean.

    Parameters: none

    Returns: number of additional isoforms (int)

    If no additional isoforms exist, returns 0

    boolean usage:

    0 = false (has no more) nonzero = true (has additional isoforms)

delete_isoforms()
    Description: removes isoforms stored in this Gene_obj (assigning to a new anonymous arrayref)

    Parameters: Gene_obj

    Returns: none

get_additional_isoforms()
    Description: Retrieves the additional isoforms for a given Gene_obj

    Parameters: none

    Returns: @Gene_objs

    If no additional isoforms exist, an empty array is returned.

get_orientation()
    Description: Retrieves the strand orientation of the Gene_obj

    Parameters: none

    Returns: +|-

add_gene_ontology_objs()
    Description: Adds a list of Gene_ontology objects to a Gene_obj

    Parameters: @Gene_ontology_objs

    @Gene_ontology_objs is a list of objects instantiated from Gene_ontology.pm

    Returns: none

get_gene_ontology_objs()
    Description: Retrieves Gene_ontology objs assigned to the Gene_obj

    Parameters: none

    Returns: @Gene_ontology_objs

    @Gene_ontology_objs are objects instantiated from package Gene_ontology (See Gene_ontology.pm)

set_5prime_partial()
    Description: Sets the status of the is_5prime_partial attribute

    Parameters: 1|0

    Returns: none

    5prime partials are partial on their 5prime end and lack start codons.

set_3prime_partial()
    Description: Sets the is_3prime_partial status

    Parameters: 1|0

    Returns: none

    3prime partials are partial on their 3prime end and lack stop codons.

is_5prime_partial()
    Description: Retrieves the 5-prime partial status of the gene.

    Parameters: none

    Returns: 1|0

is_3prime_partial()
    Description: Retrieves the 3-prime partial status of the gene.

    Parameters: none

    Returns: 1|0

get_5prime_UTR_coords
    Description: returns a list of coordinate pairs corresponding to the 5\' UTR coordinates

    Parameters: none

    Returns: ([end5,end3], ...) or empty list if none exist

get_3prime_UTR_coords
    Description: returns a list of coordinate pairs corresponding to the 3\' UTR coordinates

    Parameters: none

    Returns: ([end5,end3], ...) or empty list if none exist

has_UTRs()
    Description: indicates presence of UTR annotated in Gene

    Parameters: none

    Returns: ( has_5prime_UTR() || has_3prime_UTR() )

get_5prime_UTR_sequence()
    Description: retrieves 5prime UTR sequence

    Parameters: genome sequence reference

    Returns: string

get_3prime_UTR_sequence()
    Description: retrieves 5prime UTR sequence

    Parameters: genome sequence reference

    Returns: string

trim_UTRs()
    Description: Trims the UTR of the Gene_obj so that the Exon coordinates are identical to the CDS coordinates. Exons which lack CDS components and are completely UTR are removed.

    Parameters: none

    Returns: none

remove_CDS_exon()
    Description: Removes any existing CDS_exon_obj from this mRNA_exon_obj

    Parameters: none

    Returns: none

get_gene_names()
    Description: Retrieves gene names (primary gene name followed by secondary gene names, "$;" delimited.

    Parameters: none

    Returns: string

         see $gene_obj->{gene_name}
         see $gene_obj->get_secondary_names()

    secondary gene names sorted lexicographically

get_secondary_gene_names()
    Description: Retrieves secondary gene names as a "$;" delimited string.

    Parameters: none

    Returns: string

get_product_names()
    Description: Retrieves product name, with the primary product name followed by secondary product names, delimited by "$;"

    Parameters: none

    Returns: string

        see $gene_obj->{com_name} for primary product name
        see $gene_obj->get_secondary_product_names()

get_secondary_product_names()
    Description: Retrieves secondary product names, delimited by "$;" and sorted lexicographically.

    Parameters: none

    Returns: string

get_gene_symbols()
    Description: Retrieves primary gene symbol followed by secondary gene symbols, delimited by "$;"

    Parameters: none

    Returns: string

        see $gene_obj->{gene_sym}
        see $gene_obj->get_secondary_gene_symbols()

get_secondary_gene_symbols()
    Description: Retrieves secondary gene symbols, delimited by "$;" and sorted lexicographically

    Parameters: none

    Returns: string

get_ec_numbers()
    Description: Retrieves primary EC number followed by secondary EC numbers, "$;" delimited

    Parameters: none

    Returns: string

        see $gene_obj->{ec_num}
        see $gene_obj->get_secondary_ec_numbers()

get_secondary_ec_numbers()
    Description: Retrieves secondary EC numbers, "$;" delimited and sorted lexicographically

    Parameters: none

    Returns: string

add_secondary_gene_names()
    Description: Adds secondary gene name(s)

    Parameters: (gene_name_1, gene_name_2, ....)

    Single gene name or list of gene names is allowed

    Returns: none

add_secondary_product_names()
    Description: Adds secondary product names

    Parameters: (product_name_1, product_name_2, ...)

    Single or list of product names as parameter

    Returns: none

    Primary gene name added directly as an attribute like so
        $gene_obj->{gene_name} = name

add_secondary_gene_symbols()
    Description: Add secondary gene symbols

    Parameters: (gene_symbol_1, gene_symbol_2, ...)

    String or list context

    Returns: none

    Primary gene_symbol added directly as attribute like so:
        $gene_obj->{gene_sym} = symbol

add_secondary_ec_numbers()
    Description: Add secondary Enzyme Commission (EC) numbers

    Parameters: (EC_1, EC_2, ...)

    String or list context

    Returns: none

    Primary EC number added directly as an attribute like so:
        $gene_obj->{ec_num} = EC_number

to_GTF_format()
    Description: Outputs text corresponding to the representation of the gene in GTF format.

    Parameters: $genome_seq_ref, %preferences

    Returns: string

    GTF format is described in "Current Protocols in Bioinformatics(2003)" 4.8.1-4.8.19 in "Using TWINSCAN to Predict Gene Structures in Genomic DNA Sequences".

    Each line of the GTF format includes the following tab-delimited fields:

    [seqname] [source] [feature] [start] [end] [score] [strand] [frame] [attributes]

    This is further elaborated below:

    [feature] contains one of the following: start_codon, stop_codon, CDS [attributes] contains 'gene_id' and 'transcript_id' fields. All features of the same transcript should share the same transcript_id value. By default, the TU_feat_name and model_feat_name are used as the gene_id and transcript_id, respectively.

        Using the %preferences input parameter, the preferred values or gene attributes can be used for seqname, source, gene_id, or transcript_id, each used as a key to the %preferences hash.  Given the value of %preferences is a gene attribute, that attribute value will be used, otherwise, the raw value will be used.

    For example: %preferences = ( seqname => 'mySeqname',
                            gene_id => 'pub_locus' );

    Would result in 'mySeqname' used in the [seqname] field, and the $gene_obj->{pub_locus} value

    Here are the defaults: [seqname] = asmbl_id [source] = annotation gene_id (TU_feat_name) transcript_id (Model_feat_name)

    ** Partial Genes are NOT Supported ** ( undef is returned ) ** Genes with split start or stop codons are unsupported ** (undef is returned)

to_GFF3_format()
    Description: Outputs text corresponding to the representation of the gene in GFF3 format (still under development).

    Parameters:

    Returns: string

    GFF3 defined at: http://song.sourceforge.net/gff3-jan04.shtml

    (some text lifted from above site provided below for reference purposes)

    The format consists of 9 columns, separated by tabs or spaces. The following unescaped characters are allowed within fields: [a-zA-Z0-9.:^*$@!+_?-]. All other characters must must be escaped using the URL escaping conventions. Unescaped quotation marks, backslashes and other ad-hoc escaping conventions that have been added to the GFF format are explicitly forbidden. The =, ; and % characters have reserved meanings as described below, and must be escaped when used in other contexts.

    Undefined fields are replaced with the "." character, as described in the original GFF spec.

    Column 1: "seqid"

    The ID of the landmark used to establish the coordinate system for the current feature. IDs must contain alphanumeric characters. Whitespace, if present, must be escaped using URL escaping rule (e.g. space="%20" or "+"). Sequences must *NOT* begin with an unescaped ">".

    Column 2: "source"

    The source of the feature. This is unchanged from the older GFF specs and is not part of a controlled vocabulary.

    Column 3: "type"

    The type of the feature (previously called the "method"). This is constrained to be either: (a) a term from the "lite" sequence ontology, SOFA; or (b) a SOFA accession number. The latter alternative is distinguished using the syntax SO:000000.

    Columns 4 & 5: "start" and "end"

    The start and end of the feature, in 1-based integer coordinates, relative to the landmark given in column 1. Start is always less than or equal to end.

    For zero-length features, such as insertion sites, start equals end and the implied site is to the right of the indicated base. This convention holds regardless of the strandedness of the feature.

    Column 6: "score"

    The score of the feature, a floating point number. As in earlier versions of the format, the semantics of the score are ill-defined. It is strongly recommended that E-values be used for sequence similarity features, and that P-values be used for ab initio gene prediction features.

    Column 7: "strand"

    The strand of the feature. + for positive strand (relative to the landmark), - for minus strand, and . for features that are not stranded. In addition, ? can be used for features whose strandedness is relevant, but unknown.

    Column 8: "phase"

    For features of type "exon", the phase indicates where the feature begins with reference to the reading frame. The phase is one of the integers 0, 1,or 2, indicating that the first base of the feature corresponds to the first, second or last base of the codon, respectively. This is NOT to be confused with the frame, but relates to the relative position of the translational start in whatever strand the feature is in.

    Column 9: "attributes"

    A list of feature attributes in the format tag=value. Multiple tag=value pairs are separated by semicolons. URL escaping rules are used for tags or values containing the following characters: ",=;". Whitespace should be replaced with the "+" character or the %20 URL escape. This will allow the file to survive text processing programs that convert tabs into spaces.

    These tags have predefined meanings:

        ID     Indicates the name of the feature.  IDs must be unique
               within the scope of the GFF file.

        Name   Display name for the feature.  This is the name to be
               displayed to the user.  Unlike IDs, there is no requirement
               that the Name be unique within the file.

        Alias  A secondary name for the feature.  It is suggested that
               this tag be used whenever a secondary identifier for the
               feature is needed, such as locus names and
               accession numbers.  Unlike ID, there is no requirement
               that Alias be unique within the file.

        Parent Indicates the parent of the feature.  A parent ID can be
               used to group exons into transcripts, transcripts into
               genes, an so forth.  A feature may have multiple parents.

        Target Indicates the target of a nucleotide-to-nucleotide or
               protein-to-nucleotide alignment.  The format of the
               value is "target_id+start+end".

        Gap    The alignment of the feature to the target if the two are
              not colinear (e.g. contain gaps).  The alignment format is
              taken from the CIGAR format described in the
              Exonerate documentation.
              (http://cvsweb.sanger.ac.uk/cgi-bin/cvsweb.cgi/exonerate
               ?cvsroot=Ensembl).  See "THE GAP ATTRIBUTE" for a description
               of this format.

        Note   A free text note.

        Dbxref A database cross reference.  See the section
               "Ontology Associations and Db Cross References" for
               details on the format.

        Ontology_term  A cross reference to an ontology term.  See
               the section "Ontology Associations and Db Cross References"
               for details.

    Multiple attributes of the same type are indicated by separating the values with the comma "," character, as in:

           Parent=AF2312,AB2812,abc-3

    Note that attribute names are case sensitive. "Parent" is not the same as "parent".

    All attributes that begin with an uppercase letter are reserved for later use. Attributes that begin with a lowercase letter can be used freely by applications.

to_BED_format()
    Description: describes gene in BED format Parameters: (uri_encode => 1|0) Returns: string

    BED format described here: http://genome.ucsc.edu/FAQ/FAQformat.html#format1

            BED format

    BED format provides a flexible way to define the data lines that are displayed in an annotation track. BED lines have three required fields and nine additional optional fields. The number of fields per line must be consistent throughout any single set of data in an annotation track. The order of the optional fields is binding: lower-numbered fields must always be populated if higher-numbered fields are used.

    The first three required BED fields are:

    1. chrom - The name of the chromosome (e.g. chr3, chrY, chr2_random) or scaffold (e.g. scaffold10671).

    2. chromStart - The starting position of the feature in the chromosome or scaffold. The first base in a chromosome is numbered 0.

    3. chromEnd - The ending position of the feature in the chromosome or scaffold. The chromEnd base is not included in the display of the feature. For example, the first 100 bases of a chromosome are defined as chromStart=0, chromEnd=100, and span the bases numbered 0-99.

    The 9 additional optional BED fields are:

    4. name - Defines the name of the BED line. This label is displayed to the left of the BED line in the Genome Browser window when the track is open to full display mode or directly to the left of the item in pack mode.

    5. score - A score between 0 and 1000. If the track line useScore attribute is set to 1 for this annotation data set, the score value will determine the level of gray in which this feature is displayed (higher numbers = darker gray). This table shows the Genome Browsers translation of BED score values into shades of gray

    6. strand - Defines the strand - either '+' or '-'.

    7. thickStart - The starting position at which the feature is drawn thickly (for example, the start codon in gene displays).

    8. thickEnd - The ending position at which the feature is drawn thickly (for example, the stop codon in gene displays).

    9. itemRgb - An RGB value of the form R,G,B (e.g. 255,0,0). If the track line itemRgb attribute is set to "On", this RBG value will determine the display color of the data contained in this BED line. NOTE: It is recommended that a simple color scheme (eight colors or less) be used with this attribute to avoid overwhelming the color resources of the Genome Browser and your Internet browser.

    10. blockCount - The number of blocks (exons) in the BED line.

    11. blockSizes - A comma-separated list of the block sizes. The number of items in this list should correspond to blockCount.

    12. blockStarts - A comma-separated list of block starts. All of the blockStart positions should be calculated relative to chromStart. The number of items in this list should correspond to blockCount.

    Example: Heres an example of an annotation track that uses a complete BED definition: track name=pairedReads description="Clone Paired Reads" useScore=1 chr22 1000 5000 cloneA 960 + 1000 5000 0 2 567,488, 0,3512 chr22 2000 6000 cloneB 900 - 2000 6000 0 2 433,399, 0,3601

    to_GTF2_format()
        Description: provides gene in GTF2 format

        Parameters: genome_seq_ref, [properties_href]

        Returns: text

        properties_href encodes preferences like so

            properties_href = {
                                  seqname => tigr_asmbl_id_1000, # by default, asmbl_id is used as encoded in gene_obj

                                  source => MyGenePrediction,   # by default, set to "TIGR"

                                  include_comments => 0,   # turned on by default, indicating partial or pseudogenes with preceding comment lines

                              }

        The GTF2 format is described here: http://genes.cs.wustl.edu/GTF2.html

        as follows:

        GTF2 format (Revised Ensembl GTF) Gene transfer format. This borrows from GFF, but has additional structure that warrants a separate definition and format name. NEW! Validating Parser for GTF

        Structure is as GFF, so the fields are: <seqname> <source> <feature> <start> <end> <score> <strand> <frame> [attributes] [comments]

        Here is a simple example with 3 translated exons. Order of rows is not important.

        AB000381 Twinscan CDS 380 401 . + 0 gene_id "001"; transcript_id "001.1"; AB000381 Twinscan CDS 501 650 . + 2 gene_id "001"; transcript_id "001.1"; AB000381 Twinscan CDS 700 707 . + 2 gene_id "001"; transcript_id "001.1"; AB000381 Twinscan start_codon 380 382 . + 0 gene_id "001"; transcript_id "001.1"; AB000381 Twinscan stop_codon 708 710 . + 0 gene_id "001"; transcript_id "001.1";

        The whitespace in this example is provided only for readability. In GTF, fields must be separated by a single TAB and no white space.

        <seqname> The FPC contig ID from the Golden Path.

        <source> The source column should be a unique label indicating where the annotations came from --- typically the name of either a prediction program or a public database.

        <feature> The following feature types are required: "CDS", "start_codon", "stop_codon". The feature "exon" is optional, since this project will not evaluate predicted splice sites outside of protein coding regions. All other features will be ignored.

        CDS represents the coding sequence starting with the first translated codon and proceeding to the last translated codon. Unlike Genbank annotation, the stop codon is not included in the CDS for the terminal exon.

        <start> <end> Integer start and end coordinates of the feature relative to the beginning of the sequence named in <seqname>. <start> must be less than or equal to <end>. Sequence numbering starts at 1. Values of <start> and <end> that extend outside the reference sequence are technically acceptable, but they are discouraged for purposes of this project.

        <score> The score field will not be used for this project, so you can either provide a meaningful float or replace it by a dot.

        <frame> 0 indicates that the first whole codon of the reading frame is located at 5'-most base. 1 means that there is one extra base before the first codon and 2 means that there are two extra bases before the first codon. Note that the frame is not the length of the CDS mod 3.

        Here are the details excised from the GFF spec. Important: Note comment on reverse strand.

            '0' indicates that the specified region is in frame, i.e. that its first base corresponds to the first base of a codon. '1' indicates that there is one extra base, i.e. that the second base of the region corresponds to the first base of a codon, and '2' means that the third base of the region is the first base of a codon. If the strand is '-', then the first base of the region is value of <end>, because the corresponding coding region will run from <end> to <start> on the reverse strand.

        [attributes] All four features have the same two mandatory attributes at the end of the record:

            * gene_id value;     A globally unique identifier for the genomic source of the transcript
            * transcript_id value;     A globally unique identifier for the predicted transcript.

        These attributes are designed for handling multiple transcripts from the same genomic region. Any other attributes or comments must appear after these two and will be ignored.

        Attributes must end in a semicolon which must then be separated from the start of any subsequent attribute by exactly one space character (NOT a tab character).

        Textual attributes should be surrounded by doublequotes.

        Here is an example of a gene on the negative strand. Larger coordinates are 5' of smaller coordinates. Thus, the start codon is 3 bp with largest coordinates among all those bp that fall within the CDS regions. Similarly, the stop codon is the 3 bp with coordinates just less than the smallest coordinates within the CDS regions.

        AB000123 Twinscan CDS 193817 194022 . - 2 gene_id "AB000123.1"; transcript_id "AB00123.1.2"; AB000123 Twinscan CDS 199645 199752 . - 2 gene_id "AB000123.1"; transcript_id "AB00123.1.2"; AB000123 Twinscan CDS 200369 200508 . - 1 gene_id "AB000123.1"; transcript_id "AB00123.1.2"; AB000123 Twinscan CDS 215991 216028 . - 0 gene_id "AB000123.1"; transcript_id "AB00123.1.2"; AB000123 Twinscan start_codon 216026 216028 . - . gene_id "AB000123.1"; transcript_id "AB00123.1.2"; AB000123 Twinscan stop_codon 193814 193816 . - . gene_id "AB000123.1"; transcript_id "AB00123.1.2";

        Note the frames of the coding exons. For example:

           1. The first CDS (from 216028 to 215991) always has frame zero.
           2. Frame of the 1st CDS =0, length =38.  (frame - length) % 3  = 1, the frame of the 2nd CDS.
           3. Frame of the 2nd CDS=1, length=140. (frame - length) % 3  = 2, the frame of the 3rd CDS.
           4. Frame of the 3rd CDS=2, length=108. (frame - length) % 3  =  2, the frame of the terminal CDS.
           5. Alternatively, the frame of terminal CDS can be calculated without the rest of the gene. Length of the terminal CDS=206. length % 3 =2, the frame of the terminal CDS.

        Here is an example in which the "exon" feature is used. It is a 5 exon gene with 3 translated exons.

        AB000381 Twinscan exon 150 200 . + . gene_id "AB000381.000"; transcript_id "AB000381.000.1"; AB000381 Twinscan exon 300 401 . + . gene_id "AB000381.000"; transcript_id "AB000381.000.1"; AB000381 Twinscan CDS 380 401 . + 0 gene_id "AB000381.000"; transcript_id "AB000381.000.1"; AB000381 Twinscan exon 501 650 . + . gene_id "AB000381.000"; transcript_id "AB000381.000.1"; AB000381 Twinscan CDS 501 650 . + 2 gene_id "AB000381.000"; transcript_id "AB000381.000.1"; AB000381 Twinscan exon 700 800 . + . gene_id "AB000381.000"; transcript_id "AB000381.000.1"; AB000381 Twinscan CDS 700 707 . + 2 gene_id "AB000381.000"; transcript_id "AB000381.000.1"; AB000381 Twinscan exon 900 1000 . + . gene_id "AB000381.000"; transcript_id "AB000381.000.1"; AB000381 Twinscan start_codon 380 382 . + 0 gene_id "AB000381.000"; transcript_id "AB000381.000.1"; AB000381 Twinscan stop_codon 708 710 . + 0 gene_id "AB000381.000"; transcript_id "AB000381.000.1";

    dispose()
        Description: Sets all attributes = 0, hopefully to faciliate targeting for garbage collection. (experimental method)

        Parameters: none

        Returns: none

NAME
package mRNA_exon_obj

DESCRIPTION
    The mRNA_exon_obj represents an individual spliced mRNA exon of a gene.  The coordinates of the exon can be manipulated, and the mRNA_exon_obj can contain a single CDS_exon_obj.  A mRNA_exon_obj lacking a CDS_exon_obj component is an untranslated (UTR) exon.

    A mature Gene_obj is expected to have at least one mRNA_exon_obj component.

new()
    Description: Instantiates an mRNA_exon_obj

    Parameters: <(end5, end3)>

    The end5 and end3 coordinates can be optionally passed into the constructor to set these attributes. Alternatively, the set_coords() method can be used to set these values.

    Returns: $mRNA_exon_obj

get_CDS_obj()
    Description: Retrieves the CDS_exon_obj component of this mRNA_exon_obj

    Parameters: none

    Returns: $cds_exon_obj

    If no CDS_exon_obj is attached, returns 0

get_mRNA_exon_end5_end3()
    Description: Retrieves the end5, end3 coordinates of the exon

    **Method Deprecated**, use get_coords()

    Parameters: none

    Returns: (end5, end3)

set_CDS_exon_obj()
    Description: Sets the CDS_exon_obj of the mRNA_exon_obj

    Parameters: $cds_exon_obj

    Returns: none

add_CDS_exon_obj()
    Description: Instantiates and adds a new CDS_exon_obj to the mRNA_exon_obj given the CDS coordinates.

    Parameters: (end5, end3)

    Returns: none

set_feat_name()
    Description: Sets the feat_name attribute of the mRNA_exon_obj

    Parameters: $feat_name

    Returns: none

clone_exon()
    Description: Creates a deep clone of this mRNA_exon_obj, using dclone() of Storable.pm

    Parameters: none

    Returns: $mRNA_exon_obj

get_CDS_end5_end3 ()
    Description: Retrieves end5, end3 of the CDS_exon_obj component of this mRNA_exon_obj

    Parameters: none

    Returns: (end5, end3)

    An empty array is returned if no CDS_exon_obj is attached.

get_coords()
    Description: Retrieves the end5, end3 coordinates of this mRNA_exon_obj

    Parameters: none

    Returns: (end5, end3)

set_coords()
    Description: Sets the end5, end3 coordinates of the mRNA_exon_obj

    Parameters: (end5, end3)

    Returns: none

get_strand()
    Description: Retrieves the orientation of the mRNA_exon_obj based on gene models transcribed orientation.

    Parameters: none

    Returns: +|-|undef

    If end5 == end3, strand orientation cannot be inferred based on coordinates alone, so undef is returned.

toString()
    Description: Provides a textual description of the mRNA_exon_obj

    Parameters: none

    Returns: $text

NAME
package CDS_exon_obj

DESCRIPTION
    The CDS_exon_obj represents the protein-coding portion of an mRNA_exon_obj.

new()
    Description: Cosntructor for the CDS_exon_obj

    Parameters: <(end5, end3)>

    The (end5, end3) parameter is optional. Alternatively, the set_coords() method can be used to set these values.

    Returns: $cds_exon_obj

set_feat_name()
    Description: Sets the feat_name attribute value of the CDS_exon_obj

    Parameters: $feat_name

    Returns: none

get_CDS_end5_end3()
    Description: Retrieves the end5, end3 coordinates of the CDS_exon_obj

    ** Method deprecated **, use get_coords()

    Parameters: none

    Returns: (end5, end3)

set_coords()
    Description: Sets the (end5, end3) values of the CDS_exon_obj

    Parameters: (end5, end3)

    Returns: none

get_coords()
    Description: Retrieves the (end5, end3) coordinates of the CDS_exon_obj

    Parameters: none

    Returns: (end5, end3)

    The get_coords() method behaves similarly among Gene_obj, mRNA_exon_obj, and CDS_exon_obj, and is generally preferred to other existing methods for extracting these coordinate values. Other methods persist for backwards compatibility with older applications, but have been largely deprecated.

get_orientation()
    Description: Retrieves the orientation of the CDS_exon_obj based on gene models orientation.

    Parameters: none

    Returns: +|-|undef

    undef returned if end5 == end3

toString()
    Description: Retrieves a textual description of the CDS_exon_obj

    Parameters: none

    Returns: $text

clone_cds()
    Description: Creates a deep clone of this CDS_exon_obj, using dclone() of Storable.pm

    Parameters: none

    Returns: $mRNA_exon_obj

length()
    Description: length of this cds segment

    Parameters: none

    Returns: int

set_phase()
    Description: set phase of the CDS incident bp

    Parameters: [012]

    Returns: self

    phase 0 = first bp of codon phase 1 = second bp of codon phase 2 = third bp of codon

get_phase()
    Description: gets phase of the CDS incident bp

    Parameters: none

    Returns: [012] or undef if not set

    phase 0 = first bp of codon phase 1 = second bp of codon phase 2 = third bp of codon

POD ERRORS
Hey! The above document had some coding errors, which are explained below:

Around line 4648:
    You forgot a '=back' before '=head1'