Ligo.skymap

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

- Run unit tests under Python 3.10.

- Update the `BAYESTAR interface definition document`_ to state that online CBC
pipelines should now include their PSD files in the initial ``coinc.xml``
upload, and should not upload a separate ``psd.xml.gz`` file.

``bayestar-localize-lvalert`` will now download ``psd.xml.gz`` (and log a
warning) only if the PSD was not present in the ``coinc.xml`` file.

.. _`BAYESTAR interface definition document`: https://lscsoft.docs.ligo.org/ligo.skymap/interface.html

- Several enhancements and bug fixes in ``bayestar-inject``:

- Swap component masses if necessary so that mass1 >= mass2 always.

- Rename the ``--min-snr`` option to ``--snr-threshold`` for consistency with
the same option for ``bayestar-realize-coincs`. The old ``--min-snr``
spelling is deprecated and will be
removed in a future release.

- Add the ``--min-triggers`` option to ``bayestar-inject`` to control the
minimum number of triggers to form a coincidence, for consistency with
``bayestar-realize-coincs``.

- Add the ``--distribution-samples`` option to load samples for the intrinsic
mass and spin distribution from an external file.

- Linux wheels are now built against cfitsio 4.1.0. See
https://github.com/lpsinger/ligo.skymap/issues/12.

- Add the ``request_disk`` flag when submitting ``bayestar-localize-coincs``
jobs to HTCondor. This is now required on LIGO Data Grid clusters.

- Fix compatibility with Astropy 5.1.

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

- Skip Numpy 1.22.0 because of an issue with Astropy table aggregation.
See `astropy12706`_.

.. _`astropy12706`: https://github.com/astropy/astropy/issues/12706

- Skip lalsuite 7.2 due to an upstream regression. See `lalsuite!1757`_.

.. _`lalsuite!1757`: https://git.ligo.org/lscsoft/lalsuite/-/merge_requests/1757

- Work around a regression in Numpy 1.22.0 that broke building third party
packages using the limited Python C API. See `numpy20818`_.

.. _`numpy20818`: https://github.com/numpy/numpy/pull/20818

- Update to python-ligo-lw >= 1.8.0.

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

- 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.