Pysam

comes with additional capabilities for remote file access which depend
on the presence of optional system libraries. As a consequence, the
installation script :file:`setup.py` has become more complex. For an
overview, see :ref:`installation`. We have tested installation on
linux and OS X, but could not capture all variations. It is possible
that a 0.9.1 release might follow soon addressing installation issues.

The :py:class:`~.pysam.VariantFile` class provides access to
:term:`vcf` and :term:`bcf` formatted files. The class is certainly
usable and interface is reaching completion, but the API and the
functionality is subject to change.

Detailed release notes
----------------------

* upgrade to htslib 1.3
* python 3 compatibility tested throughout.
* added a first set of bcftools commands in the pysam.bcftools
submodule.
* samtools commands are now in the pysam.samtools module. For
backwards compatibility they are still imported into the pysam
namespace.
* samtools/bcftools return stdout as a single (byte) string. As output
can be binary (VCF.gz, BAM) this is necessary to ensure py2/py3
compatibility. To replicate the previous behaviour in py2.7, use::

pysam.samtools.view(self.filename).splitlines(True)

* get_tags() returns the tag type as a character, not an integer (214)
* TabixFile now raises ValueError on indices created by tabix <1.0 (206)
* improve OSX installation and develop mode
* FastxIterator now handles empty sequences (204)
* TabixFile.isremote is not TabixFile.is_remote in line with AlignmentFile
* AlignmentFile.count() has extra optional argument read_callback
* setup.py has been changed to:
* install a single builtin htslib library. Previously, each pysam
module contained its own version. This reduces compilation time
and code bloat.
* run configure for the builtin htslib library in order to detect
optional libraries such as libcurl. Configure behaviour can be
controlled by setting the environment variable
HTSLIB_CONFIGURE_OPTIONS.
* get_reference_sequence() now returns the reference sequence and not
something looking like it. This bug had effects on
get_aligned_pairs(with_seq=True), see 225. If you have relied on on
get_aligned_pairs(with_seq=True) in pysam-0.8.4, please check your
results.
* improved autodetection of file formats in AlignmentFile and VariantFile.

==============

.. rubric:: 5 February 2025

This pysam release wraps htslib/samtools/bcftools 1.21 (PR 1310).

It has been tested with Python versions 3.6 through 3.13, and wheels are
available via PyPI_ for all of those Python versions. Python versions 3.6
through 3.8 are end-of-life; particularly if you use pysam with one of
these versions, please vote in the version survey at issue 1230.

This is expected to be the last release supporting Python 3.6 and 3.7.

Bugs fixed:

* Fix :func:`pysam.samtools.command(save_stdout=filename) <.samtools.command>`
redirection of output to a file. (677, reported by Haowen Zhang and analysed
by Youri Hoogstrate)

* Reinstate HTTPS/S3/GCS support in pre-built Linux wheels when used on Debian
and Ubuntu: these wheels now work around the discrepancy between Red Hat and
Debian CA Certificate file locations. (1257, 1268, reported by Daisie Huang
and Li Tai Fang)

* Calling :meth:`.VariantHeader.new_record` repeatedly with the same
:obj:`samples` object now sets GT correctly every time. (1308, reported
by Arthur Gymer)

* Correct the exception produced when :meth:`.AlignedSegment.set_tags` is
used with an invalid value type. (1233, PR 1235, reported by Weisheng Wu
and Marcus Stoiber)

* Many type hinting corrections. (1298, 1316, PR 1296, PR 1306, PR 1313,
PR 1315, thanks to Victor Epain, Arthur Gymer, mshunjan, and Matt Stone)

* The undocumented :func:`!pysam.samtools.import_` alias for invoking
``samtools import`` has been removed;
use :func:`pysam.samtools.fqimport() <.samtools.command>` instead.

* Corrections to several test data files to account for HTSlib 1.20 and later's
improved validity checking. (1291, reported by David Seifert; etc)

New functionality:

* :meth:`.AlignedSegment.get_aligned_pairs` now optionally returns the
associated CIGAR operator in each position tuple. (1292, PR 1294,
thanks to Lara Fuhrmann and Ivan Blagoev Topolsky)

* New :meth:`AlignmentFile.flush() <.HTSFile.flush>` and
:meth:`VariantFile.flush() <.HTSFile.flush>` methods for flushing buffered
output to streams. (1299, requested by blex-max)

* Improved :class:`str() <str>` for :class:`.AlignedSegment` now displays
reference sequence names when they are available and uses ``N`` only when
necessary. (1318, requested by Liu)

* Implement :func:`repr` for :class:`.AlignedSegment` so that it displays the
most useful fields. (PR 1267, thanks to Marcel Martin)

* Pysam's tests can now run in parallel. (1284, reported by Yuri Victorovich)

Documentation improvements:

* More complete documentation of invoking SAMtools and BCFtools subcommands
via Pysam. (1096, 1241, PR 1261, PR 1275, 1323, et al, reported by
Seung-been "Steven" Lee, Robert Baldwin, Michael Hall, Indraniel Das,
and shokrofont)

* Use the Pysam names for CIGAR operators rather than internal C names.
(1255, reported by Ilya Shlyakhter)

* Mention :meth:`AlignmentFile.fetch("*") <.AlignmentFile.fetch>` in the
FAQ entry on fetching unmapped reads. (424, reported by Ben Weisburd)

==============

.. rubric:: 24 April 2024

Bugfix release, which still wraps htslib/samtools/bcftools 1.18.

Bugs fixed:

* Preserve all header field tags defined in the SAM specification (notably TP)
in :meth:`.AlignmentHeader.from_dict` and :meth:`.AlignmentHeader.to_dict`.
(1237, PR 1238, thanks to Tim Fennell and Nils Homer)

* Adjust HTSlib's Makefile so that ``make distclean`` no longer tries to
rebuild the htscodecs configury. (PR 1247, reported by Nicola Soranzo)

* Reinstate S3 support in pre-built Linux wheels: support for this protocol
was inadvertently omitted from the pre-built 0.22.0 wheels on Linux.
(1249, 1277, etc varying circumstances; likely it is this that was
reported by Mathew Baines, Benjamin Sargsyan, et al)

* Add missing :attr:`.AlignedSegment.is_mapped` etc properties to type stubs.
(PR 1273, thanks to Matt Stone)

* Fix off-by-one NamedTupleProxy, :class:`.asBed`, etc array bounds check.
(1279, reported by Dan Bolser)

* Make pysam's klib headers compatible with C++. (reported by Martin Grigorov)

==============

.. rubric:: 5 October 2023

This pysam release wraps htslib/samtools/bcftools 1.18 (PR 1208).

It has been tested with Python versions 3.6 through 3.12, and wheels are
available via PyPI_ for all of those Python versions. Python versions 3.6
and 3.7 are end-of-life; particularly if you use pysam with either of
these versions, please vote in the version survey at issue 1230.

The final pysam release that supported Python 2.7 was v0.20.0.

Bugs fixed:

* Remove Cython from runtime dependencies. (PR 1186, thanks to Nicola Soranzo,
also reported by Arya Massarat in PR 1194)

* Miscellaneous dependency improvements. (PR 1216, 1217, PR 1218, PR 1219,
thanks to Martin Larralde and Arthur Vigil)

* Suppress spurious "Could not retrieve index file" message when opening an
AlignmentFile. (939, 1214, reported by ChengYong Tham and Sebastian Röner)

* Propagate SAM parsing errors encounted in :meth:`.AlignedSegment.fromstring`.
(1196, reported by DV Klopfenstein)

* Accept invalid MD:A tagged fields produced by HTSeq instead of crashing
in :meth:`AlignedSegment.get_aligned_pairs(with_seq=True)
<.AlignedSegment.get_aligned_pairs>`. (1226, reported by Isaac Vock)

* Fix multiarch macOS CI builds by removing brewed liblzma. (1205, reported
by Till Hartmann)

* Fix :attr:`.VariantRecordSample.alleles` type hint. (1179, reported by
David Seifert)

New functionality:

* Add optional :meth:`HTSFile.seek(..., whence) <.HTSFile.seek>` parameter
and clarify which functions use libc.SEEK_SET vs io.SEEK_SET.
(1185, requested by luyulin)

* File handling improvements in samtools & bcftools commands. (should improve
1193 and 1195, reported by Rob Bierman and Sam Chorlton)

* Improve :class:`.FastxFile` performance. (PR 1227, thanks to Fabian Klötzl
and Valentyn Bezshapkin)

* Improve the accuracy of type hints for :class:`.AlignmentFile` iteration.
(1184, PR 1189, reported by PikalaxALT)

Documentation improvements:

* Clarify that :meth:`.AlignedSegment.get_aligned_pairs` results are 0-based.
(1180, reported by Nick Semenkovich)

* Clarify :meth:`.AlignedSegment.get_reference_positions` documentation.
(836, 838, reported by Liang Ou and Nick Stoler)

* Clarify that installation via pip usually uses a wheel, and that configuring
the build via $HTSLIB_CONFIGURE_OPTIONS etc only applies when installing from
an sdist. (1086, reported by Layne Sadler)

A message from pysam's founder, Andreas Heger:

As many of you will have noticed, John Marshall has been effectively
maintaining pysam and supporting users over the last few years.
I, Andreas, am very grateful for the countless hours he has contributed.
Unfortunately, I will not be able to contribute much in the near and
intermediate future. To keep pysam going, John has kindly agreed to
continue maintaining and supporting pysam as the principal developer
of pysam. I am very happy to know that pysam is in good hands and want
to thank again John and the wider pysam community for their suggestions,
bug reports, code contributions and general support.

Thank you Andreas for all your work over the years and the solid foundations
that pysam enjoys and the useful functionality it provides.

==============

.. rubric:: 2 April 2023

This release wraps htslib/samtools/bcftools version 1.17.

Pysam is now compatible with Python 3.11. We have removed Python 2.x
support. Pysam is tested with Python versions 3.6 to 3.11.

* [1175] VariantHeader.new_record: set start/stop before alleles
* [1173] Add multiple build improvements in htscodecs on multi-arch macOS
* [1148] Ignore CIGAR-less reads in find_introns.
* [1172] Add new `samtools cram-size` and `samtools reset` commands
* [1169] Fix CRAM index-related crash when using the musl C standard library.
* [1168] Add a minimal pyproject.toml for PEP517.
* [1158] Fix type hints and add FastqProxy type hints.
* [1147] Py3.11 compatibility, get shared object suffix from EXT_SUFFIX.
* [1143] Add mypy symbols for samtools and bcftools.
* [1155] Fix pysam.index() when using recent `samtools index` options.
* [1151] Test suite py3.11 compatibility, work around failing test case.
* [1149] MacOS universal build compatibility.
* [1146] Fix build when CFLAGS/etc environment variables are set.

==============

.. rubric:: 29 October 2022

This release wraps htslib/bcftools version 1.16 and samtools version 1.16.1.

* [1113] Full compatibility with setuptools v62.1.0's build directory name changes
* [1121] Build-time symbol check portability improved
* [1122] Fix setting sample genotype using .alleles property
* [1128] Fix test suite failure when using a libdeflate-enabled samtools

Many additional type hints have been provided by the community,
thanks!