org.biojava.nbio.genome.io.fastq.FastqVariant Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of biojava-genome Show documentation
The newest version!
/*
 *                    BioJava development code
 *
 * This code may be freely distributed and modified under the
 * terms of the GNU Lesser General Public Licence.  This should
 * be distributed with the code.  If you do not have a copy,
 * see:
 *
 *      http://www.gnu.org/copyleft/lesser.html
 *
 * Copyright for this code is held jointly by the individual
 * authors.  These should be listed in @author doc comments.
 *
 * For more information on the BioJava project and its aims,
 * or to join the biojava-l mailing list, visit the home page
 * at:
 *
 *      http://www.biojava.org/
 *
 */
package org.biojava.nbio.genome.io.fastq;

import java.util.HashMap;
import java.util.Map;

/**
 * FASTQ sequence format variant.
 *
 * @since 3.0.3
 */
public enum FastqVariant
{
	/** Sanger FASTQ sequence format variant. */
	FASTQ_SANGER("Original or Sanger format")
	{
		@Override
		public int minimumQualityScore()
		{
			return 0;
		}

		@Override
		public int maximumQualityScore()
		{
			return 93;
		}

		@Override
		public int qualityScore(final char c)
		{
			return (c) - 33;
		}

		@Override
		public int qualityScore(final double errorProbability)
		{
			// eq. 2
			int phredQ = constrain(-10.0d * Math.log10(errorProbability));
			return phredQ;
		}

		@Override
		public char quality(final int qualityScore)
		{
			if (qualityScore < minimumQualityScore())
			{
				throw new IllegalArgumentException("qualityScore must be greater than or equal to minimumQualityScore()");
			}
			if (qualityScore > maximumQualityScore())
			{
				throw new IllegalArgumentException("qualityScore must be less than or equal to maximumQualityScore()");
			}
			return (char) (qualityScore + 33);
		}

		@Override
		public double errorProbability(final int qualityScore)
		{
			return Math.pow(10.0d, (qualityScore) / -10.0d);
		}
	},

	/** Solexa FASTQ sequence format variant. */
	FASTQ_SOLEXA("Solexa and early Illumina format")
	{
		@Override
		public int minimumQualityScore()
		{
			return -5;
		}

		@Override
		public int maximumQualityScore()
		{
			return 62;
		}

		@Override
		public int qualityScore(final char c)
		{
			return (c) - 64;
		}

		@Override
		public int qualityScore(final double errorProbability)
		{
			// eq. 2
			double phredQ = -10.0d * Math.log10(errorProbability);
			// eq. 4
			int solexaQ = constrain(10.0d * Math.log10(Math.pow(10.0d, (phredQ/10.0d)) - 1.0d));

			return solexaQ;
		}

		@Override
		public char quality(final int qualityScore)
		{
			if (qualityScore < minimumQualityScore())
			{
				throw new IllegalArgumentException("qualityScore must be greater than or equal to minimumQualityScore()");
			}
			if (qualityScore > maximumQualityScore())
			{
				throw new IllegalArgumentException("qualityScore must be less than or equal to maximumQualityScore()");
			}
			return (char) (qualityScore + 64);
		}

		@Override
		public double errorProbability(final int qualityScore)
		{
			double q = Math.pow(10.0d, (qualityScore) / -10.0d);
			return q / (1.0d + q);
		}
	},

	/** Illumina FASTQ sequence format variant. */
	FASTQ_ILLUMINA("Illumina 1.3+ format")
	{
		@Override
		public int minimumQualityScore()
		{
			return 0;
		}

		@Override
		public int maximumQualityScore()
		{
			return 62;
		}

		@Override
		public int qualityScore(final char c)
		{
			return (c) - 64;
		}

		@Override
		public int qualityScore(final double errorProbability)
		{
			// eq. 2
			int phredQ = constrain(-10.0d * Math.log10(errorProbability));
			return phredQ;
		}

		@Override
		public char quality(final int qualityScore)
		{
			if (qualityScore < minimumQualityScore())
			{
				throw new IllegalArgumentException("qualityScore must be greater than or equal to minimumQualityScore()");
			}
			if (qualityScore > maximumQualityScore())
			{
				throw new IllegalArgumentException("qualityScore must be less than or equal to maximumQualityScore()");
			}
			return (char) (qualityScore + 64);
		}

		@Override
		public double errorProbability(final int qualityScore)
		{
			return Math.pow(10.0d, (qualityScore) / -10.0d);
		}
	};


	/** Map of FASTQ sequence format variants keyed by name and lowercase-with-dashes name. */
	private static final Map FASTQ_VARIANTS = new HashMap<>(6);

	static
	{
		for (FastqVariant fastqVariant : values())
		{
			FASTQ_VARIANTS.put(fastqVariant.name(), fastqVariant);
			FASTQ_VARIANTS.put(fastqVariant.lowercaseName(), fastqVariant);
		}
	}

	/** Description of this FASTQ sequence format variant. */
	private final String description;


	/**
	 * Create a new FASTQ sequence format variant with the specified description.
	 *
	 * @param description description of this FASTQ sequence format variant, must not be null
	 */
	private FastqVariant(final String description)
	{
		if (description == null)
		{
			throw new IllegalArgumentException("description must not be null");
		}
		this.description = description;
	}


	/**
	 * Return the description of this FASTQ sequence format variant.
	 * The description will not be null.
	 *
	 * @return the description of this FASTQ sequence format variant
	 */
	public String getDescription()
	{
		return description;
	}

	/**
	 * Return true if this FASTQ sequence format variant is {@link #FASTQ_SANGER}.
	 *
	 * @return true if this FASTQ sequence format variant is {@link #FASTQ_SANGER}
	 */
	public boolean isSanger()
	{
		return (this == FASTQ_SANGER);
	}

	/**
	 * Return true if this FASTQ sequence format variant is {@link #FASTQ_SOLEXA}.
	 *
	 * @return true if this FASTQ sequence format variant is {@link #FASTQ_SOLEXA}
	 */
	public boolean isSolexa()
	{
		return (this == FASTQ_SOLEXA);
	}

	/**
	 * Return true if this FASTQ sequence format variant is {@link #FASTQ_ILLUMINA}.
	 *
	 * @return true if this FASTQ sequence format variant is {@link #FASTQ_ILLUMINA}
	 */
	public boolean isIllumina()
	{
		return (this == FASTQ_ILLUMINA);
	}

	/**
	 * Return the minimum quality score for this FASTQ sequence format variant.
	 *
	 * @return the minimum quality score for this FASTQ sequence format variant.
	 */
	public abstract int minimumQualityScore();

	/**
	 * Return the maximum quality score for this FASTQ sequence format variant.
	 *
	 * @return the maximum quality score for this FASTQ sequence format variant.
	 */
	public abstract int maximumQualityScore();

	/**
	 * Convert the specified quality in ASCII format to a quality score.
	 *
	 * @param c quality in ASCII format
	 * @return the specified quality in ASCII format converted to a quality score
	 */
	public abstract int qualityScore(char c);

	/**
	 * Convert the specified error probability to a quality score.
	 *
	 * @since 4.2
	 * @param errorProbability error probability
	 * @return the specified error probability converted to a quality score
	 */
	public abstract int qualityScore(double errorProbability);

	/**
	 * Convert the specified quality score to a quality in ASCII format.
	 *
	 * @since 3.0.6
	 * @param qualityScore quality score, must be >= minimumQualityScore()
	 *    and <= maximumQualityScore()
	 * @return the quality in ASCII format converted from the specified quality score
	 */
	public abstract char quality(int qualityScore);

	/**
	 * Convert the specified quality in ASCII format to an error probability.
	 *
	 * @param c quality in ASCII format
	 * @return the specified quality in ASCII format converted to an error probability
	 */
	public double errorProbability(char c)
	{
		return errorProbability(qualityScore(c));
	}

	/**
	 * Calculate the error probability given the specified quality score.
	 *
	 * @param qualityScore quality score
	 * @return the error probability given the specified quality score
	 */
	public abstract double errorProbability(int qualityScore);

	/**
	 * Return the name of this FASTQ sequence format variant in lowercase-with-dashes style.
	 *
	 * @return the name of this FASTQ sequence format variant in lowercase-with-dashes style
	 */
	public String lowercaseName()
	{
		return name().toLowerCase().replace('_', '-');
	}

	/**
	 * Constrain the specified quality score in double precision to the minimum and maximum quality
	 * scores in int precision.
	 *
	 * @since 4.2
	 * @param qualityScore quality score in double precision
	 * @return the specified quality score in double precision constrained to the minimum and maximum quality
	 *    scores in int precision
	 */
	protected int constrain(final double qualityScore)
	{
		// ick.
		return Math.min(maximumQualityScore(), Math.max(minimumQualityScore(), Math.round((float) qualityScore)));
	}

	/**
	 * Return the FASTQ sequence format variant with the specified name, if any.  The name may
	 * be specified in either UPPERCASE_WITH_UNDERSCORES
	 * or lowercase-with-dashes style.
	 *
	 * @param name name
	 * @return the FASTQ sequence format variant with the specified name, or null
	 *    if no such FASTQ sequence format variant exists
	 */
	public static FastqVariant parseFastqVariant(final String name)
	{
		return FASTQ_VARIANTS.get(name);
	}
}