<commit_before>.. _whatsnew-5.2:

**************************
What's New in Astropy 5.2?
**************************

Overview
========

Astropy 5.2 is a major release that adds significant new functionality since
the 5.1 release.

In particular, this release includes:

* :ref:`whatsnew-5.2-quantity-dtype`
* :ref:`whatsnew-5.2-cosmology`
* :ref:`whatsnew-5.2-coordinates`
* :ref:`whatsnew-5.2-io-ascii-fixed-width`
* :ref:`whatsnew-5.2-fits`
* :ref:`whatsnew-5.2-visualization-wcsaxes-helpers`


.. _whatsnew-5.2-quantity-dtype:

``Quantity`` data types
=======================

The default dtype argument for ``Quantity`` has been changed, so that one can
now explicitly give ``dtype=None`` to get the same behaviour as :mod:`numpy`.
Without an explicit argument, any integer values are still upcast to floating
point, since that makes more sense for physical quantities.


.. _whatsnew-5.2-cosmology:

Updates to :mod:`astropy.cosmology`
===================================

A new comparison function has been added --
:func:`astropy.cosmology.cosmology_equal` -- that mirrors its numpy counterparts
but allows for the arguments to be converted to a |Cosmology| and to compare flat
cosmologies with their non-flat equivalents.

    >>> from astropy.cosmology import cosmology_equal
    >>> from astropy.cosmology import FlatLambdaCDM, LambdaCDM
    >>> cosmo1 = FlatLambdaCDM(70, 0.3)
    >>> cosmo2 = LambdaCDM(70, 0.3, 0.7)
    >>> cosmology_equal(cosmo1.to_format("mapping"), cosmo2,
    ...                 format=("mapping", None), allow_equivalent=True)
    True


.. _whatsnew-5.2-coordinates:

Topocentric ITRS Frame
======================

A topocentric ITRS frame has been added that makes dealing with near-Earth objects
easier and more intuitive.::

    >>> from astropy.coordinates import EarthLocation, AltAz, ITRS
    >>> from astropy.time import Time
    >>> from astropy import units as u

    >>> t = Time('J2010')
    >>> obj = EarthLocation(-1*u.deg, 52*u.deg, height=10.*u.km)
    >>> home = EarthLocation(-1*u.deg, 52*u.deg, height=0.*u.km)

    >>> # Direction of object from GEOCENTER
    >>> itrs_geo = obj.get_itrs(t).cartesian

    >>> # now get the Geocentric ITRS position of observatory
    >>> obsrepr = home.get_itrs(t).cartesian

    >>> # topocentric ITRS position of a straight overhead object
    >>> itrs_repr = itrs_geo - obsrepr

    >>> # create an ITRS object that appears straight overhead for a TOPOCENTRIC OBSERVER
    >>> itrs_topo = ITRS(itrs_repr, obstime=t, location=home)

    >>> # convert to AltAz
    >>> aa = itrs_topo.transform_to(AltAz(obstime=t, location=home))


.. _whatsnew-5.2-io-ascii-fixed-width:

Enhanced Fixed Width ASCII Tables
=================================

It is now possible to read and write a fixed width ASCII table that includes
additional header rows specifying any or all of the column ``dtype``, ``unit``,
``format``, and ``description``. This is available in the ``fixed_width`` and
``fixed_width_two_line`` formats via the new ``header_rows`` keyword argument::

    >>> from astropy.io import ascii
    >>> from astropy.table.table_helpers import simple_table
    >>> dat = simple_table(size=3, cols=4)
    >>> dat["b"].info.unit = "m"
    >>> dat["d"].info.unit = "m/s"
    >>> dat["b"].info.format = ".2f"
    >>> ascii.write(
    ...     dat,
    ...     format="fixed_width_two_line",
    ...     header_rows=["name", "unit", "format"]
    ... )
    a    b c     d
         m   m / s
       .2f
    - ---- - -----
    1 1.00 c     4
    2 2.00 d     5
    3 3.00 e     6


.. _whatsnew-5.2-fits:

Accessing cloud-hosted FITS files
=================================

A ``use_fsspec`` argument has been added to `astropy.io.fits.open` which
enables users to seamlessly extract data from FITS files stored on a web server
or in the cloud without downloading the entire file to local storage.
This feature uses a new optional dependency, `fsspec`_, which supports a range
of remote and distributed storage backends including Amazon and Google Cloud Storage.
For example, you can now access a Hubble Space Telescope image located in
Hubble's public Amazon S3 bucket as follows:

.. doctest-requires:: fsspec

    >>> from astropy.io import fits
    >>> uri = "s3://stpubdata/hst/public/j8pu/j8pu0y010/j8pu0y010_drc.fits"
    >>> with fits.open(uri, fsspec_kwargs={"anon": True}) as hdul:  # doctest: +REMOTE_DATA
    ...
    ...     # Download a single header
    ...     header = hdul[1].header
    ...
    ...     # Download a single image
    ...     mydata = hdul[1].data
    ...
    ...     # Download a small cutout
    ...     cutout = hdul[1].section[10:20, 30:50]

Note that the example above obtains a cutout image using the `~astropy.io.fits.ImageHDU.section`
attribute rather than the traditional `~astropy.io.fits.ImageHDU.data` attribute.
The use of ``.section`` ensures that only the necessary parts of the FITS
image are transferred from the server, rather than downloading the entire data
array. This trick can significantly speed up your code if you require small
subsets of large FITS files located on slow (remote) storage systems.
See :ref:`fits_io_cloud` for additional information on working with
FITS files in this way.

.. _whatsnew-5.2-visualization-wcsaxes-helpers:

Drawing the instrument beam and a physical scale bar on celestial images
========================================================================

Two functions have been added to `~astropy.visualization.wcsaxes`: `~astropy.visualization.wcsaxes.add_beam()` and
`~astropy.visualization.wcsaxes.add_scalebar()`. These functions allow to draw the shape of the instrument beam (e.g.for radio
observations) and a physical scale bar on celestial images:

.. doctest-requires:: fsspec matplotlib

    >>> from astropy.io import fits
    >>> from astropy.wcs import WCS
    >>> from astropy import units as u
    >>> from astropy.visualization.wcsaxes import add_beam, add_scalebar
    >>> import matplotlib.pyplot as plt
    >>> uri = "https://cdsarc.cds.unistra.fr/ftp/J/A+A/610/A24/fits/as209_sc_flagged_cont.image.pbcor_uniform.fits"
    >>> with fits.open(uri, fsspec_kwargs={"anon": True}) as hdul:  # doctest: +REMOTE_DATA +IGNORE_WARNINGS +IGNORE_OUTPUT
    ...
    ...    header = hdul[0].header
    ...    wcs = WCS(header, naxis=(1,2))
    ...    data = hdul[0].data.squeeze()
    ...
    ...    ax = plt.subplot(projection=wcs, xlim=(442, 582), ylim=(442, 582))
    ...    ax.imshow(data)
    ...
    ...    # Draw the beam shape (from the header)
    ...    add_beam(ax, header=header, frame=True)
    ...
    ...    # Draw a scale bar corresponding to 100 au at a distance of 126 pc
    ...    add_scalebar(ax, 100./126. * u.arcsec, label="100 au", color="white")

Full change log
===============

To see a detailed list of all changes in version v5.2, including changes in
API, please see the :ref:`changelog`.

Renamed/removed functionality
=============================
<commit_msg>Add What's New entry for tilde-path expansion<commit_after>.. _whatsnew-5.2:

**************************
What's New in Astropy 5.2?
**************************

Overview
========

Astropy 5.2 is a major release that adds significant new functionality since
the 5.1 release.

In particular, this release includes:

* :ref:`whatsnew-5.2-quantity-dtype`
* :ref:`whatsnew-5.2-cosmology`
* :ref:`whatsnew-5.2-coordinates`
* :ref:`whatsnew-5.2-io-ascii-fixed-width`
* :ref:`whatsnew-5.2-fits`
* :ref:`whatsnew-5.2-visualization-wcsaxes-helpers`
* :ref:`whatsnew-5.2-tilde-paths`


.. _whatsnew-5.2-quantity-dtype:

``Quantity`` data types
=======================

The default dtype argument for ``Quantity`` has been changed, so that one can
now explicitly give ``dtype=None`` to get the same behaviour as :mod:`numpy`.
Without an explicit argument, any integer values are still upcast to floating
point, since that makes more sense for physical quantities.


.. _whatsnew-5.2-cosmology:

Updates to :mod:`astropy.cosmology`
===================================

A new comparison function has been added --
:func:`astropy.cosmology.cosmology_equal` -- that mirrors its numpy counterparts
but allows for the arguments to be converted to a |Cosmology| and to compare flat
cosmologies with their non-flat equivalents.

    >>> from astropy.cosmology import cosmology_equal
    >>> from astropy.cosmology import FlatLambdaCDM, LambdaCDM
    >>> cosmo1 = FlatLambdaCDM(70, 0.3)
    >>> cosmo2 = LambdaCDM(70, 0.3, 0.7)
    >>> cosmology_equal(cosmo1.to_format("mapping"), cosmo2,
    ...                 format=("mapping", None), allow_equivalent=True)
    True


.. _whatsnew-5.2-coordinates:

Topocentric ITRS Frame
======================

A topocentric ITRS frame has been added that makes dealing with near-Earth objects
easier and more intuitive.::

    >>> from astropy.coordinates import EarthLocation, AltAz, ITRS
    >>> from astropy.time import Time
    >>> from astropy import units as u

    >>> t = Time('J2010')
    >>> obj = EarthLocation(-1*u.deg, 52*u.deg, height=10.*u.km)
    >>> home = EarthLocation(-1*u.deg, 52*u.deg, height=0.*u.km)

    >>> # Direction of object from GEOCENTER
    >>> itrs_geo = obj.get_itrs(t).cartesian

    >>> # now get the Geocentric ITRS position of observatory
    >>> obsrepr = home.get_itrs(t).cartesian

    >>> # topocentric ITRS position of a straight overhead object
    >>> itrs_repr = itrs_geo - obsrepr

    >>> # create an ITRS object that appears straight overhead for a TOPOCENTRIC OBSERVER
    >>> itrs_topo = ITRS(itrs_repr, obstime=t, location=home)

    >>> # convert to AltAz
    >>> aa = itrs_topo.transform_to(AltAz(obstime=t, location=home))


.. _whatsnew-5.2-io-ascii-fixed-width:

Enhanced Fixed Width ASCII Tables
=================================

It is now possible to read and write a fixed width ASCII table that includes
additional header rows specifying any or all of the column ``dtype``, ``unit``,
``format``, and ``description``. This is available in the ``fixed_width`` and
``fixed_width_two_line`` formats via the new ``header_rows`` keyword argument::

    >>> from astropy.io import ascii
    >>> from astropy.table.table_helpers import simple_table
    >>> dat = simple_table(size=3, cols=4)
    >>> dat["b"].info.unit = "m"
    >>> dat["d"].info.unit = "m/s"
    >>> dat["b"].info.format = ".2f"
    >>> ascii.write(
    ...     dat,
    ...     format="fixed_width_two_line",
    ...     header_rows=["name", "unit", "format"]
    ... )
    a    b c     d
         m   m / s
       .2f
    - ---- - -----
    1 1.00 c     4
    2 2.00 d     5
    3 3.00 e     6


.. _whatsnew-5.2-fits:

Accessing cloud-hosted FITS files
=================================

A ``use_fsspec`` argument has been added to `astropy.io.fits.open` which
enables users to seamlessly extract data from FITS files stored on a web server
or in the cloud without downloading the entire file to local storage.
This feature uses a new optional dependency, `fsspec`_, which supports a range
of remote and distributed storage backends including Amazon and Google Cloud Storage.
For example, you can now access a Hubble Space Telescope image located in
Hubble's public Amazon S3 bucket as follows:

.. doctest-requires:: fsspec

    >>> from astropy.io import fits
    >>> uri = "s3://stpubdata/hst/public/j8pu/j8pu0y010/j8pu0y010_drc.fits"
    >>> with fits.open(uri, fsspec_kwargs={"anon": True}) as hdul:  # doctest: +REMOTE_DATA
    ...
    ...     # Download a single header
    ...     header = hdul[1].header
    ...
    ...     # Download a single image
    ...     mydata = hdul[1].data
    ...
    ...     # Download a small cutout
    ...     cutout = hdul[1].section[10:20, 30:50]

Note that the example above obtains a cutout image using the `~astropy.io.fits.ImageHDU.section`
attribute rather than the traditional `~astropy.io.fits.ImageHDU.data` attribute.
The use of ``.section`` ensures that only the necessary parts of the FITS
image are transferred from the server, rather than downloading the entire data
array. This trick can significantly speed up your code if you require small
subsets of large FITS files located on slow (remote) storage systems.
See :ref:`fits_io_cloud` for additional information on working with
FITS files in this way.

.. _whatsnew-5.2-visualization-wcsaxes-helpers:

Drawing the instrument beam and a physical scale bar on celestial images
========================================================================

Two functions have been added to `~astropy.visualization.wcsaxes`: `~astropy.visualization.wcsaxes.add_beam()` and
`~astropy.visualization.wcsaxes.add_scalebar()`. These functions allow to draw the shape of the instrument beam (e.g.for radio
observations) and a physical scale bar on celestial images:

.. doctest-requires:: fsspec matplotlib

    >>> from astropy.io import fits
    >>> from astropy.wcs import WCS
    >>> from astropy import units as u
    >>> from astropy.visualization.wcsaxes import add_beam, add_scalebar
    >>> import matplotlib.pyplot as plt
    >>> uri = "https://cdsarc.cds.unistra.fr/ftp/J/A+A/610/A24/fits/as209_sc_flagged_cont.image.pbcor_uniform.fits"
    >>> with fits.open(uri, fsspec_kwargs={"anon": True}) as hdul:  # doctest: +REMOTE_DATA +IGNORE_WARNINGS +IGNORE_OUTPUT
    ...
    ...    header = hdul[0].header
    ...    wcs = WCS(header, naxis=(1,2))
    ...    data = hdul[0].data.squeeze()
    ...
    ...    ax = plt.subplot(projection=wcs, xlim=(442, 582), ylim=(442, 582))
    ...    ax.imshow(data)
    ...
    ...    # Draw the beam shape (from the header)
    ...    add_beam(ax, header=header, frame=True)
    ...
    ...    # Draw a scale bar corresponding to 100 au at a distance of 126 pc
    ...    add_scalebar(ax, 100./126. * u.arcsec, label="100 au", color="white")

.. _whatsnew-5.2-tilde-paths:

Support for tilde-prefixed paths
================================

This release finishes adding support for tilde-prefixed paths, which began in
5.1. These are paths of the form ``~/data/file.fits`` or
``~<username>/data/file.fits``. The single tilde refers to the current user's
home directory, while a tilde followed by a valid username refers to that
user's home directory (e.g. ``/home/<username>`` on Linux or
``/Users/<username>`` on macOS). This syntax is common in command-line oriented
applications, especially on Unix-based systems. It serves as a convenient
shortcut, and it also allows code to be shared and run by multiple people
without having to update file paths if each person keeps data in the same
directory structure relative to their home directory.

This support has been added throughout the ``astropy.io`` module. This feature
is also supported within the I/O functionality of `astropy.table` and the
FITS-file functionality in `astropy.nddata`.


Full change log
===============

To see a detailed list of all changes in version v5.2, including changes in
API, please see the :ref:`changelog`.

Renamed/removed functionality
=============================

{'fraction_non_alphanumeric': 0.1586381504430675, 'fraction_numerical': 0.01945499367046439, 'mean_word_length': 3.5238095238095237, 'pattern_counts': {'":': 4, '<': 6, '<?xml version=': 0, '>': 234, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 10, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1419295', 'n_tokens_mistral': 4956, 'n_tokens_neox': 4601, 'n_words': 1511}