net.maizegenetics.analysis.gbs.neobio.FactorSequence Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of tassel Show documentation
TASSEL is a software package to evaluate traits associations, evolutionary patterns, and linkage disequilibrium.
There is a newer version: 5.2.94
/*
 * FactorSequence.java
 *
 * Copyright 2003 Sergio Anibal de Carvalho Junior
 *
 * This file is part of NeoBio.
 *
 * NeoBio is free software; you can redistribute it and/or modify it under the terms of
 * the GNU General Public License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * NeoBio is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
 * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
 * PURPOSE. See the GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along with NeoBio;
 * if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
 * Boston, MA 02111-1307, USA.
 *
 * Proper attribution of the author as the source of the software would be appreciated.
 *
 * Sergio Anibal de Carvalho Junior		mailto:[email protected]
 * Department of Computer Science		http://www.dcs.kcl.ac.uk
 * King's College London, UK			http://www.kcl.ac.uk
 *
 * Please visit http://neobio.sourceforge.net
 *
 * This project was supervised by Professor Maxime Crochemore.
 *
 */

package net.maizegenetics.analysis.gbs.neobio;

import java.io.Reader;
import java.io.BufferedReader;
import java.io.IOException;

/**
 * This class builds a list of factors of a character sequence as induced by its
 * Lempel-Ziv (LZ78) factorisation. Each factor is enconded as the longest factor
 * previously seen plus one character.
 *
 * The input can come from any source, provided it is encapsulated in a proper
 * Reader instance. The stream is expected to be ready (i.e. the next
 * read operation must return the first character of the sequence) and it is
 * not closed when its end is reached, so the client is allowed to reset it and maybe use
 * it for another purpose.
 *
 * Sequences can contain letters only although lines started with the
 * COMMENT_CHAR character ('>') are regarded as comments and are completely
 * skipped. White spaces (including tabs, line feeds and carriage returns) are also
 * ignored throughout.
 *
 * This class uses a {@linkplain Trie} to keep track of a list of factors. Each node of
 * the trie contains a {@linkplain Factor} of the text. As the sequence is read from the
 * input, the trie is traversed as far as possible. When a leaf node is reached (which
 * means that the longest prefix of the input has been found), two tasks are
 * accomplished:
 *
 * 
 * a new Factor is created with the character at the current position of
 * the input and the leaf node's factor;
 * 
a new node is added to the trie with the character at the current position of the
 * input;
 * 
 *
 * Each factor also receives a serial number according to the order they are found and
 * a pointer to the next factor (in that order) for fast access. This pointer, together
 * with the factor's ancestor pointer forms a doubly-linked list of factors. The original
 * text can then be reconstructed simply by following the linked list and writing out its
 * factors.
 *
 * As an example, the sequence ACTAAACCGCATTAATAATAAAA is parsed into the
 * following 12 factors:
 *
 *  * 0  ( , ) = empty
 * 1  (0,A) = A
 * 2  (0,C) = C
 * 3  (0,T) = T
 * 4  (1,A) = AA
 * 5  (1,C) = AC
 * 6  (2,G) = CG
 * 7  (2,A) = CA
 * 8  (3,T) = TT
 * 9  (4,T) = AAT
 * 10 (9,A) = AATA
 * 11 (4,A) = AAA
 *
 * serial # (prefix, new char) = factor text
 * 
 *
 * This class is used by {@linkplain CrochemoreLandauZivUkelson} algorithm to speed up
 * the classic dynamic programming approach to sequence alignment.
 *
 * @author Sergio A. de Carvalho Jr.
 * @see Factor
 * @see Trie
 * @see CrochemoreLandauZivUkelson
 */
public class FactorSequence
{
	/**
	 * The character used to start a comment line in a sequence file. When this character
	 * is found, the rest of the line is ignored.
	 */
	protected static final char COMMENT_CHAR = '>';

	/**
	 * A pointer to the root factor, the one that starts the list of factors.
	 */
	protected Factor root_factor;

	/**
	 * The numbers of character represented by this sequence.
	 */
	protected int num_chars;

	/**
	 * The numbers of factors generated by the LZ78 parsing of the sequence.
	 */
	protected int num_factors;

	/**
	 * Creates a new instance of a FactorSequence, loading the sequence data
	 * from the Reader input stream. A doubly-linked list of factors is built
	 * according to its LZ78 factorisation.
	 *
	 * @param reader source of characters for this sequence
	 * @throws IOException if an I/O exception occurs when reading the input
	 * @throws InvalidSequenceException if the input does not contain a valid sequence
	 */
	public FactorSequence (Reader reader)
		throws IOException, InvalidSequenceException
	{
		BufferedReader	input = new BufferedReader(reader);
		Trie			root_node, current_node, new_node = null;
		Factor			current_factor, last_factor, new_factor;
		int				ch;
		char			c;

		// create root factor and the root node of the trie
		root_factor = new Factor ();
		root_node = new Trie (root_factor);
		num_factors = 1;
		num_chars = 0;

		current_node = root_node;
		last_factor = root_factor;

		// read characters from the input
		while ((ch = input.read()) != -1)
		{
			c = (char) ch;

			if (c == COMMENT_CHAR)
				// it's a comment line: skip it!
				input.readLine();

			// accept letters only
			else if (Character.isLetter(c))
			{
				num_chars++;

				// walk down the trie as far as possible
				new_node = current_node.spellDown(c);

				if (new_node != null)
				{
					current_node = new_node;
				}
				else
				{
					// the longest factor of the input has been found,
					// now create a new factor from the current node's factor
					current_factor = (Factor) current_node.getData();
					new_factor = new Factor (current_factor, num_factors, c);

					// add the new character to the trie as well
					current_node.add (new_factor, c);

					// set up a pointer from the last factor to the new one
					last_factor.setNext (new_factor);
					last_factor = new_factor;

					// restart at the root of the trie
					current_node = root_node;

					num_factors++;
				}
			}

			// anything else, except whitespaces, will throw an exception
			else if (!Character.isWhitespace(c))
				throw new InvalidSequenceException
					("Sequences can contain letters only.");
		}

		// if new_node is not null, the last factor is actually
		// not a new factor but a factor already created
		if (new_node != null)
		{
			// no new node is created, just point the last_factor to an
			// existing one that represents the last characters of the text
			last_factor.setNext((Factor) new_node.getData());

			num_factors++;
		}

		// check if read anything useful!
		if (num_factors <= 1)
			throw new InvalidSequenceException ("Empty sequence.");
	}

	/**
	 * Returns the root factor, the one that starts the list of factors.
	 *
	 * @return root factor
	 */
	public Factor getRootFactor ()
	{
		return root_factor;
	}

	/**
	 * Returns the number of factors produced by the LZ78 parsing of the text.
	 *
	 * @return number of factors
	 */
	public int numFactors()
	{
		return num_factors;
	}

	/**
	 * Returns the number of characters of the original sequence.
	 *
	 * @return number of characters of the original sequence
	 */
	public int numChars ()
	{
		return num_chars;
	}

	/**
	 * Reconstructs the sequence from the list of factors induced by the LZ78 parsing of
	 * the text.
	 *
	 * @return the original sequence
	 */
	public String toString ()
	{
		StringBuffer	buf = new StringBuffer();
		Factor			node;

		node = root_factor.getNext();

		for (int i = 1; i < numFactors(); i++)
		{
			buf.append(node);

			node = node.getNext();
		}

		return buf.toString();
	}

	/**
	 * Returns a string representation of the actual list of factors produced by the LZ78
	 * parsing of the text. Each factor is printed out in a separate line, in the order
	 * they appear in the text, with its serial number, its ancestor's serial number, its
	 * new character, length and a string representation of the factor itself.
	 *
	 * @return a string representation of the list of factors
	 */
	public String printFactors ()
	{
		StringBuffer	buf = new StringBuffer();
		Factor			factor;

		factor = root_factor.getNext();

		for (int i = 1; i < numFactors(); i++)
		{
			buf.append (factor.getSerialNumber() + "\t<");
			buf.append (factor.getAncestor().getSerialNumber() + " ,\t");
			buf.append (factor.getNewChar() + ">\t");
			buf.append (factor.length() + "\t" + factor + "\n");

			factor = factor.getNext();
		}

		buf.append(numFactors() + " factors\n");

		return buf.toString();
	}
}