Ligo.skymap

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

- Rename ``master`` branch to ``main``.

- Add a ``max-distance`` option to ``bayestar-inject``.

- Increase verbosity of LAL error reporting so that the user gets more
information for invalid waveform arguments.

- Wheels for macOS are now built against macOS 10.15 (Catalina) using GCC 11.

- Require Python >= 3.8 due Astropy and Numpy deprecation policy.
See `APE 18`_ and `NEP 29`_.

.. _`APE 18`: https://github.com/astropy/astropy-APEs/blob/main/APE18.rst
.. _`NEP 29`: https://numpy.org/neps/nep-0029-deprecation_policy.html

- In ``bayestar_inject``, use the method ``vectorize_redshift_method`` instead
of ``vectorize_if_needed`` from ``astropy.cosmology.utils``, because the
latter was deprecated in Astropy 5.0 (see `astropy12176`_).

.. _`astropy12176`: https://github.com/astropy/astropy/pull/12176

- Require astropy >= 5.0.

- Require python-ligo-lw <= 1.7.1 because of an API breaking change that will
occur in the next version of python-ligo-lw. Support for new versions of
python-ligo-lw will be added in an upcoming release. See `ligo.skymap30`_.

.. _`ligo.skymap30`: https://git.ligo.org/lscsoft/ligo.skymap/-/issues/30

- Add support for all-sky projections in Galactic coordinates activated by
creating Matplotlib axes with the keyword arguments like
``projection='galactic degrees mollweide'``.

- Add the ``mark_inset_circle`` and ``connect_inset_circle`` methods to
``AutoScaledWCSAxes`` in order to support circular insets (loupes).

- Determine input filetypes by reading the file header in Python rather than
relying on a shell utility.

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

- Word-wrap the Python and command line arguments that are recorded in the
``HISTORY`` cards. This makes the arguments more legible, because Astropy's
built-in FITS card wrapping behavior does not consider word breaks. It also
works around a FITS validation regression in Astropy 4.2.1
(see `astropy11486`_).

.. _`astropy11486`: https://github.com/astropy/astropy/issues/11486

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

- Teach the ``astro zoom`` and ``astro globe`` projections to accept sky
coordinates in any Astropy representation, including Cartesian coordinates.

- Enable SNR time series by default in ``bayestar-realize-coincs``.

- Update the required version of Matplotlib to >= 3.4.0, since it includes the
bug fix for `matplotlib18832`_.

- Update the required version of Astropy to >= 4.0.2 and != 4.2. Astropy 4.1
now works with Matplotlib >= 3.4.0, but Astropy 4.2 introduced a bug
affecting Numpy and sky coordinates that will be fixed in Astropy 4.2.1
(see `astropy11133`_).

.. _`astropy11133`: https://github.com/astropy/astropy/pull/11133

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

- This is the first release of ligo.skymap that is tested under and officially
supports Python 3.9. (We were mostly waiting for LALSuite to be built for
Python 3.9).

- Drop support for Python 3.6 because it is no longer supported by many other
scientific Python packages like Matplotlib and Numpy.

- Update the required version of Astropy to >= 4.0.2 and < 4.1. Astropy 4.0.2
includes a bug fix for cache handling on cluster filesystems (see
`astropy9970`_). Astropy 4.1 caused some issues with Matplotlib projection
classes as a result of changes in hashing behavior of
``astropy.coordinates.SkyCoord`` (see `matplotlib18832`_), which should be
fixed in Matplotlib 3.4.0.

.. _`astropy9970`: https://github.com/astropy/astropy/issues/9970
.. _`matplotlib18832`: https://github.com/matplotlib/matplotlib/issues/18832

- Update the required version of LALSuite to >= 6.82 to work around an
incompatibility between Numpy >= 1.20.0 and older versions of LALSuite
(see `lalsuite414`_).

.. _`lalsuite414`: https://git.ligo.org/lscsoft/lalsuite/-/issues/414

- Importing ligo.skymap no longer causes the
``astropy.coordinates.EarthLocation`` site registry to be populated with the
locations of gravitational-wave observatories, because these sites are now
included in Astropy's own data repository (see `astropy-data89`_).

.. _`astropy-data89`: https://github.com/astropy/astropy-data/pull/89

- In the command line help for ``bayestar-localize-coincs`` and in the
``COMMENT`` card in the output FITS file, explain that the integer value in
the ``OBJECT`` card in the FITS header is a row ID that refers to a
coinc_event table row in the input LIGO-LW document.

- Add the ``--rescale-loglikelihood`` command line argument to expose
BAYESTAR's log likelihood factor that accounts for excess technical sources
of noise from the matched filter pipeline.

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

- Add ``--f-high`` option to ``bayestar-realize-coincs`` in order to simulate
early warning triggers.

- In sky maps produced by ``bayestar-localize-coincs``, the FITS headers now
contain ``OBJECT`` identifiers that are integer event IDs (such as ``1``)
rather than strings (such as ``coinc_event:coinc_event_id:1``).

- The ``ligo-skymap-stats`` tool now recognizes FITS headers with either
integer or string ``OBJECT`` identifiers.

- Use Astropy rather than LAL for GPS to UTC time conversion in FITS headers so
that LALSuite is not a requirement for reading and writing FITS files.

- Refactor ``ligo-skymap-stats`` to unify its multiprocessing and progress bar
implementation with other command line tools.

- Update the compiler version that is used to build Linux wheels to icc
19.1.2.254 from Intel Parallel Studio XE 2020u2.

- Port the Python C extension to the limited stable Python API so that one
binary wheel works for all supported Python versions for any given operating
system. See `PEP 384 <https://www.python.org/dev/peps/pep-0384/>`_.

- Eliminate global static variables from the Python C extension to enable
compatibility with Python subinterpreters. See
`PEP 3121 <https://www.python.org/dev/peps/pep-3121/>`_.

- Improve the numerical stability of the method
:meth:`ligo.skymap.distance.conditional_ppf` by reparametrizing the equation
that is being solved. This method, which calculates the inverse of the
distance CDF, works by solving the equation :math:`f(x) - p = 0` for
:math:`x`, where :math:`f(x)` is the distance CDF, and :math:`p` is the
desired probability.

The reparametrized equation is :math:`log(1 - f(x)) - log(1 - p) = 0` if
:math:`p > 1/2` and :math:`log(f(x)) - log(p) = 0` otherwise. This
reparametrization is effective because it improves the dynamic range in the
tails of the distribution. This same reparametrization had already proven
effective in the related method :meth:`ligo.skymap.distance.marginal_ppf`.

This change also fixes some rare corner cases where
:meth:`~ligo.skymap.distance.marginal_ppf` returned silly values becauses it
uses :meth:`~ligo.skymap.distance.conditional_ppf` internally to create its
own initial guess. One example was the median distance for the binary neutron
star candidate S191205ah. Before this patch, the result was negative and
invalid::

>>> from ligo.skymap.distance import marginal_ppf
>>> from ligo.skymap.moc import uniq2pixarea
>>> from ligo.skymap.io import read_sky_map
>>> url = 'https://gracedb.ligo.org/apiweb/superevents/S191205ah/files/bayestar.multiorder.fits'
>>> s = read_sky_map(url, moc=True)
>>> marginal_ppf(0.5, s['PROBDENSITY'] * uniq2pixarea(s['UNIQ']),
... s['DISTMU'], s['DISTSIGMA'], s['DISTNORM'])
/Users/lpsinger/src/ligo.skymap/ligo/skymap/util/numpy.py:46: RuntimeWarning: invalid value encountered in marginal_ppf
return func(*args, **kwargs)
-223357.8508233767

After this patch, the result is positive and sensible::

>>> marginal_ppf(0.5, s['PROBDENSITY'] * uniq2pixarea(s['UNIQ']),
... s['DISTMU'], s['DISTSIGMA'], s['DISTNORM'])
362.7485740018039

- Increase the range of validity of the solver used in
:meth:`ligo.skymap.distance.moments_to_parameters` for low-probability pixels
that are very prior dominated. Sky maps that have many such pixels could have
credible volumes repoted as infinity. The incidence of such cases should now
be decreased.

- Correct the alignment of Numpy record arrays passed to
:func:`ligo.skymap.moc.rasterize` in order to avoid possibly undefined
behavior that was detected by UBSan.

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

- Normalize column names when an ASCII file is passed to
``ligo-skymap-from-samples``.

- Migrate LIGO-LW XML support from the ``glue.ligolw`` module to the newer and
better maintained ``ligo.lw`` module.

- Teach BAYESTAR to accept either string row IDs (such as
``sngl_inspiral:event_id:1``) or integer row IDs (such as ``1``).

- The parallel ``map()`` implementation that is used by a number of the
package's command line tools will now yield results in order as quickly as
they arrive, rather than sorting all of the results at the end. This should
provide a very modest speedup in some command line tools.