Skip to content
Commits on Source (6)
Show whitespace changes
Inline Side-by-side
debian/changelog
View file @ ca680705
htseq (0.9.1-1) UNRELEASED; urgency=medium
htseq (0.9.1-1) unstable; urgency=medium
* New upstream version
* Point Vcs fields to salsa.debian.org
......@@ -8,8 +8,13 @@ htseq (0.9.1-1) UNRELEASED; urgency=medium
- Remove unused get-orig-source target
- There is no clean script any more so remove the specific targets
* Sphinx doc does not seem to reported any more
* Provide Python3 package
* Binaries are provided in python3-htseq package
* hardening=+all
* Secure URI in watch file (pointing to new PyPi)
* Testsuite: autopkgtest-pkg-python
-- Andreas Tille <tille@debian.org> Tue, 01 May 2018 07:49:00 +0200
-- Andreas Tille <tille@debian.org> Tue, 01 May 2018 11:29:55 +0200
htseq (0.6.1p1-4) unstable; urgency=medium
......
debian/control
View file @ ca680705
......@@ -3,6 +3,7 @@ Maintainer: Debian Med Packaging Team <debian-med-packaging@lists.alioth.debian.
Uploaders: Diane Trout <diane@ghic.org>,
Andreas Tille <tille@debian.org>
Section: python
Testsuite: autopkgtest-pkg-python
Priority: optional
Build-Depends: debhelper (>= 11~),
python-debian,
......@@ -52,7 +53,7 @@ Depends: ${misc:Depends},
${python3:Depends},
${shlibs:Depends}
Breaks: python-htseq (<= 0.9.1)
Provides: python-htseq (<= 0.9.1)
Provides: python-htseq
Description: Python3 high-throughput genome sequencing read analysis utilities
HTSeq can be used to performing a number of common analysis tasks
when working with high-throughput genome sequencing reads:
......
debian/man/htseq-count.1 0 → 100644
View file @ ca680705
.\" Man page generated from reStructuredText.
.
.TH "HTSEQ-COUNT" "1" "Oct 01, 2017" "0.6.1p1" "HTSeq"
.SH NAME
htseq-count \- Count the number of reads in a SAM alignment file that map to GFF features
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
Given a file with aligned sequencing reads and a list of genomic
features, a common task is to count how many reads map to each feature.
.sp
A feature is here an interval (i.e., a range of positions) on a chromosome
or a union of such intervals.
.sp
In the case of RNA\-Seq, the features are typically genes, where each gene
is considered here as the union of all its exons. One may also consider
each exon as a feature, e.g., in order to check for alternative splicing.
For comparative ChIP\-Seq, the features might be binding region from a
pre\-determined list.
.sp
Special care must be taken to decide how to deal with reads that overlap more
than one feature. The \fBhtseq\-count\fP script allows one to choose between three
modes. Of course, if none of these fits your needs, you can write your own
script with HTSeq. See the chapter tour for a step\-by\-step guide on
how to do so. See also the FAQ at the end, if the following explanation seems
to technical.
.sp
The three overlap resolution modes of \fBhtseq\-count\fP work as follows. For
each position \fIi\fP in the read, a set \fIS(i)\fP is defined as the set of all
features overlapping position \fIi\fP\&. Then, consider the set \fIS\fP, which is
(with \fIi\fP running through all position within the read or a read pair)
.INDENT 0.0
.IP \(bu 2
the union of all the sets \fIS(i)\fP for mode \fBunion\fP\&. This mode is recommended for most use cases.
.IP \(bu 2
the intersection of all the sets \fIS(i)\fP for mode \fBintersection\-strict\fP\&.
.IP \(bu 2
the intersection of all non\-empty sets \fIS(i)\fP for mode \fBintersection\-nonempty\fP\&.
.UNINDENT
.sp
If \fIS\fP contains precisely one feature, the read (or read pair) is counted for this feature. If
it contains more than one feature, the read (or read pair) is counted as \fBambiguous\fP (and
not counted for any features), and if \fBS\fP is empty, the read (or read pair) is counted
as \fBno_feature\fP\&.
.sp
The following figure illustrates the effect of these three modes:
[image]
.SH USAGE
.sp
After you have installed HTSeq (see install), you can run \fBhtseq\-count\fP from
the command line:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
htseq\-count [options] <alignment_file> <gff_file>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If the file \fBhtseq\-qa\fP is not in your path, you can, alternatively, call the script with
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
python \-m HTSeq.scripts.count [options] <alignment_file> <gff_file>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fB<alignment_file>\fP contains the aligned reads in the SAM format. (Note that the
\fI\%SAMtools\fP contain Perl scripts to convert most alignment formats to SAM.)
Make sure to use a splicing\-aware aligner such as TopHat. HTSeq\-count makes
full use of the information in the CIGAR field.
.sp
To read from standard input, use \fB\-\fP as \fB<alignment_file>\fP\&.
.sp
If you have paired\-end data, pay attention to the \fB\-r\fP option described below.
.sp
The \fB<gff_file>\fP contains the features in the \fI\%GFF format\fP\&.
.sp
The script outputs a table with counts for each feature, followed by
the special counters, which count reads that were not counted for any feature
for various reasons. The names of the special counters all start with
a double underscore, to facilitate filtering. (Note: The double unscore
was absent up to version 0.5.4). The special counters are:
.INDENT 0.0
.IP \(bu 2
\fB__no_feature\fP: reads (or read pairs) which could not be assigned to any feature
(set \fIS\fP as described above was empty).
.IP \(bu 2
\fB__ambiguous\fP: reads (or read pairs) which could have been assigned to more than
one feature and hence were not counted for any of these (set \fIS\fP
had more than one element).
.IP \(bu 2
\fB__too_low_aQual\fP: reads (or read pairs) which were skipped due to the \fB\-a\fP
option, see below
.IP \(bu 2
\fB__not_aligned\fP: reads (or read pairs) in the SAM file without alignment
.IP \(bu 2
\fB__alignment_not_unique\fP: reads (or read pairs) with more than one reported alignment.
These reads are recognized from the \fBNH\fP optional SAM field tag.
(If the aligner does not set this field, multiply aligned reads will
be counted multiple times, unless they getv filtered out by due to the \fB\-a\fP option.)
.UNINDENT
.sp
\fIImportant:\fP The default for strandedness is \fIyes\fP\&. If your RNA\-Seq data has not been made
with a strand\-specific protocol, this causes half of the reads to be lost.
Hence, make sure to set the option \fB\-\-stranded=no\fP unless you have strand\-specific
data!
.SS Options
.INDENT 0.0
.TP
.B \-f <format>, \-\-format=<format>
Format of the input data. Possible values are \fBsam\fP (for text SAM files)
and \fBbam\fP (for binary BAM files). Default is \fBsam\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-r <order>, \-\-order=<order>
For paired\-end data, the alignment have to be sorted either by read name or
by alignment position. If your data is not sorted, use the \fBsamtools sort\fP
function of \fBsamtools\fP to sort it. Use this option, with \fBname\fP or \fBpos\fP
for \fB<order>\fP to indicate how the input data has been sorted. The default
is \fBname\fP\&.
.sp
If \fBname\fP is indicated, \fBhtseq\-count\fP expects all the alignments for the
reads of a given read pair to appear in adjacent records in the input data.
For \fBpos\fP, this is not expected; rather, read alignments whose mate alignment
have not yet been seen are kept in a buffer in memory until the mate is found.
While, strictly speaking, the latter will also work with unsorted data, sorting
ensures that most alignment mates appear close to each other in the data
and hence the buffer is much less likely to overflow.
.UNINDENT
.INDENT 0.0
.TP
.B \-s <yes/no/reverse>, \-\-stranded=<yes/no/reverse>
whether the data is from a strand\-specific assay (default: \fByes\fP)
.sp
For \fBstranded=no\fP, a read is considered overlapping with a feature regardless
of whether it is mapped to the same or the opposite strand as the feature.
For \fBstranded=yes\fP and single\-end reads, the read has to be mapped to the same
strand as the feature. For paired\-end reads, the first
read has to be on the same strand and the second read on the opposite strand.
For \fBstranded=reverse\fP, these rules are reversed.
.UNINDENT
.INDENT 0.0
.TP
.B \-a <minaqual>, \-\-a=<minaqual>
skip all reads with alignment quality lower than the given
minimum value (default: 10 — Note: the default used to be 0 until
version 0.5.4.)
.UNINDENT
.INDENT 0.0
.TP
.B \-t <feature type>, \-\-type=<feature type>
feature type (3rd column in GFF file) to be used, all
features of other type are ignored (default, suitable
for RNA\-Seq analysis using an \fI\%Ensembl GTF\fP file: \fBexon\fP)
.UNINDENT
.INDENT 0.0
.TP
.B \-i <id attribute>, \-\-idattr=<id attribute>
GFF attribute to be used as feature ID. Several GFF lines with the same
feature ID will be considered as parts of the same feature. The feature ID
is used to identity the counts in the output table. The default, suitable
for RNA\-Seq analysis using an Ensembl GTF file, is \fBgene_id\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-m <mode>, \-\-mode=<mode>
Mode to handle reads overlapping more than one feature. Possible values for
\fI<mode>\fP are \fBunion\fP, \fBintersection\-strict\fP and \fBintersection\-nonempty\fP
(default: \fBunion\fP)
.UNINDENT
.INDENT 0.0
.TP
.B \-o <samout>, \-\-samout=<samout>
write out all SAM alignment records into an output SAM
file called <samout>, annotating each line with its
assignment to a feature or a special counter
(as an optional field with tag ‘XF’)
.UNINDENT
.INDENT 0.0
.TP
.B \-q, \-\-quiet
suppress progress report and warnings
.UNINDENT
.INDENT 0.0
.TP
.B \-h, \-\-help
Show a usage summary and exit
.UNINDENT
.SS Frequenctly asked questions
.INDENT 0.0
.TP
.B \fIMy shell reports “command not found” when I try to run “htseq\-count”. How can I launch the script?\fP
The file “htseq\-count” has to be in the system’s \fI\%search path\fP\&. By default, Python places it
in its script directory, which you have to add to your search path. A maybe easier alternative
is to write \fBpython \-m HTSeq.scripts.count\fP instead of \fBhtseq\-count\fP, followed by the
options and arguments, which will launch the htseq\-count script as well.
.UNINDENT
.INDENT 0.0
.TP
.B \fIWhy are multi\-mapping reads and reads overlapping multiple features discarded rather than counted for each feature?\fP
The primary intended use case for \fBhtseq\-count\fP is \fIdifferential\fP expression analysis, where
one compares the expression of the same gene across samples and not the expression of different
genes within a sample. Now, consider two genes, which share a stretch of common sequence
such that for a read mapping to this stretch, the aligner cannot decide which of the two genes
the read originated from and hence reports a multiple alignment. If we discard all such reads,
we undercount the total output of the genes, but the \fIratio\fP of expression strength (the “fold
change”) between samples or experimental condition will still be correct, because we discard the
same fratcion of reads in all samples. On the other hand, if we counted these reads for both
genes, a subsequent diffential\-expression analysis might find false positives: Even if only one of the
gene changes increases its expression in reaction to treatment, the additional read caused by this
would be counted for both genes, giving the wrong appearance that both genes reacted to the treatment.
.TP
.B \fII have used a GTF file generated by the Table Browser function of the UCSC Genome Browser, and most reads are counted as ambiguous. Why?\fP
In these files, the \fBgene_id\fP attribute incorrectly contains the same value as the \fBtranscript_id\fP
attribute and hence a different value for each transcript of the same gene. Hence, if a read maps to
an exon shared by several transcripts of the same gene, this will appear to \fBhtseq\-count\fP as and
overlap with several genes. Therefore, these GTF files cannot be used as is. Either correct the
incorrect \fBgene_id\fP attributes with a suitable script, or use a GTF file from a different source.
.TP
.B \fICan I use htseq\-count to count reads mapping to transcripts rather than genes?\fP
In principle, you could instruct htseq\-count to count for each of a gene’s transcript individually, by
specifying \fB\-\-idattr transcript_id\fP\&. However, all reads mapping to exons shared by several
transcripts will then be considered ambiguous. (See second question.) Counting them for each transcript
that contains the exons would be possible but makes little sense for typical use cases. (See first
question.) If you want to perform differential expression analysis on the level of
individual transcripts, maybe ahve a look at \fI\%our paper on DEXSeq\fP for a discussion on why we
prefer performing such analyses on the level of exons instead.
.UNINDENT
.INDENT 0.0
.TP
.B \fIFor paired\-end data, does htseq\-count count reads or read pairs?\fP
Read pairs. The script is designed to count “units of evidence” for gene expression. If both mates map
to the same gene, this still only shows that one cDNA fragment originated from that gene. Hence, it
should be counted only once.
.TP
.B \fIWhat happens if the two reads in a pair overlap two different features?\fP
The same as if one read overlaps two features: The read or read pair is counted as ambiguous.
.TP
.B \fIWhat happened if the mate of an aligned read is not aligned?\fP
For the default mode “union”, only the aligned read determines how the read pair is counted. For the
other modes, see their description.
.TP
.B \fIMost of my RNA\-Seq reads are counted as \(ga\(ga__no_feature\(ga\(ga. What could have gone wrong?\fP
Common causes include:
\- The \fB\-\-stranded\fP option was set wrongly. Use a genome browser (e.g., IGV) to check.
\- The GTF file uses coordinates from another reference assembly as the SAM file.
\- The chromosome names differ between GTF and SAM file (e.g., \fBchr1\fP in one file and jsut \fB1\fP in the other).
.TP
.B \fIWhich overlap mode should I use?\fP
When I wrote \fBhtseq\-count\fP, I was not sure which option is best and included three possibilities. Now,
several years later, I have seen very few cases where the default \fBunion\fP would not be appropriate
and hence tend to recommend to just stick to \fBunion\fP\&.
.TP
.B \fII have a GTF file? How do I convert it to GFF?\fP
No need to do that, because GTF is a tightening of the GFF format. Hence, all GTF files are GFF files, too.
By default, htseq\-count expects a GTF file.
.TP
.B \fII have a GFF file, not a GTF file. How can I use it to count RNA\-Seq reads?\fP
The GTF format specifies, inter alia, that exons are marked by the word \fBexon\fP in the third column and
that the gene ID is given in an attribute named \fBgene_id\fP, and htseq\-count expects these words to be used
by default. If you GFF file uses a word other than \fBexon\fP in its third column to mark lines describing
exons, notify \fBhtseq\-count\fP using the \fB\-\-type\fP option. If the name of the attribute containing the
gene ID for exon lines is not \fBgene_id\fP, use the \fB\-\-idattr\fP\&. Often, its is, for example,
\fBParent\fP, \fBGeneID\fP or \fBID\fP\&. Make sure it is the gene ID and not the exon ID.
.TP
.B \fIHow can I count overlaps with features other than genes/exons?\fP
If you have GFF file listing your features, use it together with the \fB\-\-type\fP and \fB\-\-idattr\fP options.
If your feature intervals need to be computed, you are probably better off writing your own
counting script (provided you have some knowledge of Python). Follow the tutorial in the other pages
of this documentation to see how to use HTSeq for this.
.TP
.B \fIHow should I cite htseq\-count in a publication?\fP
Please cite HTSeq as follows: S Anders, T P Pyl, W Huber: \fIHTSeq — A Python framework to work with
high\-throughput sequencing data\fP\&. bioRxiv 2014. \fI\%doi: 10.1101/002824\fP\&.
(This is a preprint currently under review. We will replace this with the reference to the final
published version once available.)
.UNINDENT
.SH AUTHOR
Simon Anders
.SH COPYRIGHT
2017, Simon Anders
.\" Generated by docutils manpage writer.
.
debian/man/htseq-qa.1 0 → 100644
View file @ ca680705
.\" Man page generated from reStructuredText.
.
.TH "HTSEQ-QA" "1" "Oct 01, 2017" "0.6.1p1" "HTSeq"
.SH NAME
htseq-qa \- Perform simple quality assessment of high-throughput sequencing reads
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
The Python script \fBhtseq\-qa\fP takes a file with sequencing reads (either
raw or aligned reads) and produces a PDF file with useful plots to assess
the technical quality of a run.
.SH PLOT
.sp
Here is a typical plot:
[image]
.sp
The plot is made from a SAM file, which contained aligned and unalignable reads.
The left column is made from the non\-aligned, the right column from the aligned
reads. The header informs you about the name of the SAM file, and the number of
reads.
.sp
The upper row shows how often which base was called for each position in the
read. In this sample, the non\-alignable reads have a clear excess in A. The
aligned reads have a balance between complementing reads: A and C (reddish colours)
have equal levels, and so do C and G (greenish colours). The sequences seem to be AT
rich. Furthermore, nearly all aligned reads start with a T, followed by an A, and then,
a C in 70% and an A in 30% of the reads. Such an imbalance would be reason for concern
if it has no good explanation. Here, the reason is that the fragmentation of the sample
was done by enzyme digestion.
.sp
The lower half shows the abundance of base\-call quality scores at the different positions
in the read. Nearly all aligned reads have a quality of 34 over their whole length, while
for the non\-aligned reads, some reads have lower quality scores towards their ends.
.SH USAGE
.sp
Note that \fBhtseq\-qa\fP needs matplotlib to produce the plot, so you need to install this
module, as described \fI\%here\fP on the matplotlib web site.
.sp
After you have installed HTSeq (see install) and matplotlib, you can run \fBhtseq\-qa\fP from
the command line:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
htseq\-qa [options] read_file
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If the file \fBhtseq\-qa\fP is not in your path, you can, alternatively, call the script with
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
python \-m HTSeq.scripts.qa [options] read_file
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fIread_file\fP is either a FASTQ file or a SAM file. For a SAM file, a plot with two columns
is produced as above, for a FASTQ file, you get only one column.
.sp
The output is written into a file with the same name as \fIread_file\fP, with the suffix \fB\&.pdf\fP
added. View it with a PDF viewer such as the Acrobat Reader.
.SS Options
.INDENT 0.0
.TP
.B \-t <type>, \-\-type=<type>
The file type of the \fIread_file\fP\&. Supported values for \fI<type>\fP are:
.INDENT 7.0
.IP \(bu 2
\fBsam\fP: a SAM file (Note that the \fI\%SAMtools\fP contain Perl scripts to convert
most alignment formats to SAM)
.IP \(bu 2
\fBsolexa\-export\fP: an \fB_export.txt\fP file as produced by the SolexaPipeline
software after aligning with Eland (\fBhtseq\-qa\fP expects the new Solexa quality
encoding as produced by version 1.3 or newer of the SolexaPipeline)
.IP \(bu 2
\fBfastq\fP: a FASTQ file with standard (Sanger or Phred) quality encoding
.IP \(bu 2
\fBsolexa\-fastq\fP: a FASTQ file with Solexa quality encoding, as produced by
the SolexaPipeline after base\-calling with Bustard (\fBhtseq\-qa\fP expects
the new Solexa quality encoding as produced by version 1.3 or newer
of the SolexaPipeline)
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-o <outfile>, \-\-outfile=<outfile>
output filename (default is \fI<read_file>\(ga\(ga\fP\&.pdf\(ga\(ga)
.UNINDENT
.INDENT 0.0
.TP
.B \-r <readlen>, \-\-readlength=<readlen>
the maximum read length (when not specified, the
script guesses from the file
.UNINDENT
.INDENT 0.0
.TP
.B \-g <gamma>, \-\-gamma=<gamma>
the gamma factor for the contrast adjustment of the
quality score plot
.UNINDENT
.INDENT 0.0
.TP
.B \-n, \-\-nosplit
do not split reads in unaligned and aligned ones, i.e., produce
a one\-column plot
.UNINDENT
.INDENT 0.0
.TP
.B \-m, \-\-maxqual
the maximum quality score that appears in the data (default: 40)
.UNINDENT
.INDENT 0.0
.TP
.B \-h, \-\-help
Show a usage summary and exit
.UNINDENT
.SH AUTHOR
Simon Anders
.SH COPYRIGHT
2017, Simon Anders
.\" Generated by docutils manpage writer.
.
debian/rules
View file @ ca680705
......@@ -5,6 +5,8 @@ export PYBUILD_NAME=htseq
# see https://wiki.debian.org/Python/LibraryStyleGuide
export http_proxy=http://127.0.9.1:9
export DEB_BUILD_MAINT_OPTIONS=hardening=+all
%:
dh $@ --with python2,python3 --buildsystem=pybuild
......@@ -15,3 +17,8 @@ override_dh_auto_clean:
for link in 'src' 'HTSeq' 'doc' 'scripts' 'test' ; do \
if [ -L $${link} ] ; then rm $${link} ; fi \
done
override_dh_install:
dh_install
# binaries should be only in python3 package
rm -rf debian/python-$(PYBUILD_NAME)/usr/bin
\ No newline at end of file
debian/watch
View file @ ca680705
version=3
http://pypi.debian.net/HTSeq/HTSeq-([0-9.p]*)\.tar\.gz
version=4
https://pypi.python.org/pypi/HTSeq .*/HTSeq@ANY_VERSION@@ARCHIVE_EXT@