Junction.hpp

Go to the documentation of this file.

// Copyright 2010 Complete Genomics, Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License"); you
// may not use this file except in compliance with the License. You
// may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
// implied. See the License for the specific language governing
// permissions and limitations under the License.

#ifndef CGA_TOOLS_JUNCTION_HPP_
#define CGA_TOOLS_JUNCTION_HPP_



#include "cgatools/core.hpp"
#include "cgatools/reference/CrrFile.hpp"

// Boost.
#include <boost/array.hpp>

// Standard library.
#include <string>
#include <vector>
#include <map>


namespace cgatools { namespace junctions {

    class Junction;
    typedef reference::CrrFile  ReferenceGenome;
    typedef uint8_t             Base;
    typedef reference::Location Location;

    class Range : public reference::Range 
    {
    public:
        void setContig(uint16_t contigId) {
            chromosome_ = contigId;
        }
    };

    // Constants for the two possible sides of a Junction.
    const int JUNCTION_LEFT_SIDE = 0;
    const int JUNCTION_RIGHT_SIDE = 1;

    // Constanrt to indicate an unknown length.
    const int JUNCTION_UNKNOWN_LENGTH = -1;


    // Possible zygosity for each side of a junction.
    enum JunctionSideSectionZygosity {
        JUNCTION_UNKNOWN_ZYGOSITY = 0,
        JUNCTION_HETEROZYGOUS = 1,
        JUNCTION_HOMOZYGOUS = 2
    };
    void read(std::vector<std::string>::const_iterator&, JunctionSideSectionZygosity&);
    void write(std::ostream&, JunctionSideSectionZygosity, const std::string &separator);



    // The two possible strands of a Junction.
    enum JunctionStrand {
        JUNCTION_MINUS_STRAND = -1,
        JUNCTION_UNKNOWN_STRAND = 0,
        JUNCTION_PLUS_STRAND = +1
    };
    void read(std::vector<std::string>::const_iterator&, JunctionStrand&);
    void write(std::ostream&, JunctionStrand, const std::string &separator);


    // Class describing the left or right side of a junction.
    class JunctionSideSection {
    public:

        // Strand of the reference that this junction side maps to.
        JunctionStrand strand_;

        // Position of the base closest to the transition section.
        Location position_;

        // Number of bases in this side of the junction, or -1 if unknown.
        int length_;

        // The zygosity of this side section.
        JunctionSideSectionZygosity zygosity_;

        // Flag that indicates whether this side of the junction is known.
        // If false, this this is a semi-junction
        // and all remaining data members are invalid.
        bool isKnown_;

        // The default constructor constructs an unknown junction side.
        JunctionSideSection();

        // Constructor from strand/position, with unknown length and zygosity.
        JunctionSideSection(JunctionStrand, const Location&);

        // Constructor from strand/position/length, with unknown zygosity.
        JunctionSideSection(JunctionStrand, const Location&, int length);

        // Constructor from strand/position/zygosity, with unknown length.
        JunctionSideSection(JunctionStrand, const Location&, JunctionSideSectionZygosity);

        // Constructor from strand/position/length/zygosity.
        JunctionSideSection(JunctionStrand, const Location&, int length, JunctionSideSectionZygosity);

        // Number of string tokens used to represent a JunctionSideSection.
        static const int TOKEN_COUNT = 5;

        // Return the genome range covered by this section.
        Range getRange(int side) const;

        // Input/output.
        void read(std::vector<std::string>::const_iterator&, const ReferenceGenome&);
        void write(std::ostream&, const ReferenceGenome&, const std::string &separator) const;
    };



    // Class describing the transition region of a junction.
    class JunctionTransitionSection {
    public:

        // The base sequence of the transition region which "bridges"
        // between the left and right side. Can be empty if there
        // is no transition section.
        std::vector<Base> sequence_;

        // Flag that indicates whether this junction transition region is known.
        // If false, the sequence is invalid.
        bool isKnown_;

        // The default constructor constructs an unknown transition section.
        JunctionTransitionSection();

        // Constructor from a sequence, which can be empty if the left section
        // transitions into the right section without any intervening non-reference bases.
        JunctionTransitionSection(const std::vector<Base>&);
        JunctionTransitionSection(const std::string&);

        // Reverse complement the transition region.
        void reverseComplement();

        // Reverse complement a vector of bases.
        static void reverseComplement(std::vector<Base>&);

        // Number of string tokens used to represent a JunctionTransitionSection.
        static const int TOKEN_COUNT = 2;

        // Input/output.
        void read(std::vector<std::string>::const_iterator&);
        void write(std::ostream&, const std::string &separator) const;
    };



    // Class describing the score of a junction. The meaning of the number is
    // dependent on the type. Type 'U' is used to code an unknown score.
    class JunctionScore {
        friend std::ostream& operator<<(std::ostream& ostr, const JunctionScore& o);
    public:
        double score_;
        char type_;

        // The default constructor constructs an unknown score.
        JunctionScore();

        // Constructor from type and value.
        JunctionScore(double score, char type);

        // Number of string tokens used to represent a JunctionScore.
        static const int TOKEN_COUNT = 1;

        // Input/output.
        void read(std::vector<std::string>::const_iterator&);
        void write(std::ostream&, const std::string &separator) const;
    };



    // Class to describe a Junction id. It consists of an arbitrary number
    // of strings, each composed of letters and numbers only.
    // The strings are written seperated by dashes.
    // The first string is used to identify the originating program.
    // "U" is used for an unassigned or unknown id.
    // A program can generate "child junctions" from a parent junction.
    // The id of a child junction is obtained by appending an
    // additional string to the id of the parent junction.
    class JunctionId {
        friend std::ostream& operator<<(std::ostream& ostr, const JunctionId& o);
    public:
        typedef std::vector<std::string> IdType;
        IdType id_;

        // The default constructor construct an invalid junction id ("U").
        JunctionId();

        // Constructor from a code and an integer id.
        JunctionId(const std::string& code, int id);

        // Constructor from a string id.
        JunctionId(const std::string& id);

        // Comparison
        bool operator==(const JunctionId&) const;
        bool operator!=(const JunctionId&) const;
        bool operator<(const JunctionId&) const;

        // Input/output
        void read(std::vector<std::string>::const_iterator&);
        void write(std::ostream&, const std::string &separator) const;
        std::string string() const;
    };



    // An object that generates junction ids.
    class JunctionIdGenerator {
    public:
        // Generate simple ids consisting of a string and a number.
        JunctionIdGenerator(const std::string&);

        // Generate children of a given junction id.
        JunctionIdGenerator(const Junction&);
        JunctionIdGenerator(const JunctionId&);
        JunctionIdGenerator(const std::vector<std::string>&);

        // The next id we will generate.
        std::vector<std::string> nextId_;

        // Call operator() to generate a new junction id.
        JunctionId operator()();
    };



    // Main class describing a single Junction.
    class Junction {
    public:
        JunctionId id_;

        // The three sections that make up this junction.
        boost::array<JunctionSideSection,2> sideSections_;
        JunctionTransitionSection transitionSection_;

        JunctionScore score_;
        std::vector<std::string> comments_;

        // The default constructor constructs an invalid Junction
        // missing both side sections and the transition section.
        Junction();

        // Constructors from the three sections.
        Junction(
            const JunctionId&,
            const JunctionSideSection& leftSection,
            const JunctionTransitionSection&,
            const JunctionSideSection& rightSection,
            const JunctionScore& score=JunctionScore());
        Junction(
            const JunctionId&,
            const boost::array<JunctionSideSection,2>&,
            const JunctionTransitionSection&,
            const JunctionScore& score=JunctionScore());

        // Constructors from the two sections, with 
        // unknown transition section.
        Junction(
            const JunctionId&,
            const JunctionSideSection& leftSection,
            const JunctionSideSection& rightSection,
            const JunctionScore& score=JunctionScore());
        Junction(
            const JunctionId&,
            const boost::array<JunctionSideSection,2>&,
            const JunctionScore& score=JunctionScore());

        // Constructor for a semi-junction without the right section.
        Junction(
            const JunctionId&,
            const JunctionSideSection& leftSection,
            const JunctionTransitionSection&,
            const JunctionScore& score=JunctionScore());

        // Constructor for a semi-junction without the left section.
        Junction(
            const JunctionId&,
            const JunctionTransitionSection&,
            const JunctionSideSection& rightSection,
            const JunctionScore& score=JunctionScore());

        // Constructor from a string (the junction as represented
        // in a junction file).
        Junction(const std::string&, const ReferenceGenome& reference, const std::string &separator);

        // Add a comment.
        void addComment(const std::string&);

        // Return true if in canonical form.
        bool isCanonical() const;

        // Change to canonical form.
        void canonicalize();

        // Return true if it is a semi-junction.
        bool isSemiJunction() const;

        // Reverse complement the junction.
        void reverseComplement();

        // Return the position of the side section that comes earliest in the reference.
        Location position() const;

        // Remove duplicate comments.
        void removeDuplicateComments();

        // Comparison operator to sort in reference order.
        bool operator<(const Junction& that) const;

        // Compute the distance between the two side sections, or return -1
        // if the distance cannot be computed.
        int computeDistance(const ReferenceGenome&) const;

        // Input/output.
        void read(const std::vector<std::string>&, const ReferenceGenome&);
        void write(std::ostream&, const ReferenceGenome&, const std::string &separator) const;
    };

    typedef std::vector<Junction> Junctions;

    // Class describing a Junction file.
    class JunctionFile {
    public:

        // Create a populated JunctionFile object in memory by
        // reading an existing junction file.
        // The name excludes the extension and the dot which precedes it.
        JunctionFile(const std::string& name, const ReferenceGenome&, std::string separator="\t");

        // Create an empty JunctionFile object in memory.
        JunctionFile(std::string separator="\t");

        // Read junctions from a file.
        // The name excludes the extension and the dot which precedes it.
        // This should no be used to read a file written using writeWithReplication!
        void read(const std::string& name, const ReferenceGenome& reference, std::string extraId="");

        // Write a junction file representing this JunctionFile object.
        // The name excludes the extension and the dot which precedes it.
        void write(const std::string& name, const ReferenceGenome&);
        void writeSortedWithoutReplication(const std::string& name, const ReferenceGenome&);
        void writeSortedWithReplication(const std::string& name, const ReferenceGenome&);

        // Add a new junction.
        void add(const Junction&);

        // Canonicalize all junctions.
        void canonicalize();

        // Sort the junctions in reference order.
        void sort();

        // Remove duplicate comments.
        void removeDuplicateComments();

        // The junctions in this file.
        Junctions junctions_;

        // Header line.
        static const std::string header_;

        // Character separator for junction fields.
        std::string separator_;
    };

    // Exception class thrown when an invalid junction is read.
    class InvalidJunction {
    };

    // Output operators.
    std::ostream& operator<<(std::ostream&, const JunctionId&);

    void parseTokenString(std::string const & inputString, char const * sep, 
        std::vector<std::string> & tokens, 
        bool trimWhitespace = false, 
        bool compressEmpty = false);



}}


#endif //CGA_TOOLS_JUNCTION_HPP_

---