.. _sphx_glr_auto_examples_io_fits-tables.py:


=====================================================================
Accessing data stored as a table in a multi-extension FITS (MEF) file
=====================================================================

FITS files can often contain large amount of multi-dimensional data and
tables. This example opens a FITS file with information
from Chandra's HETG-S instrument.

The example uses `astropy.utils.data` to download multi-extension FITS (MEF)
file, `astropy.io.fits` to investigate the header, and
`astropy.table.Table` to explore the data.

-------------------

*By: Lia Corrales, Adrian Price-Whelan, and Kelle Cruz*

*License: BSD*

-------------------


Use `astropy.utils.data` subpackage to download the FITS file used in this
example. Also import `~astropy.table.Table` from the `astropy.table` subpackage
and `astropy.io.fits`


.. code-block:: python


    from astropy.utils.data import download_file
    from astropy.table import Table
    from astropy.io import fits







Download a FITS file


.. code-block:: python


    event_filename = download_file('http://data.astropy.org/tutorials/FITS-tables/chandra_events.fits',
                                   cache=True)





.. rst-class:: sphx-glr-script-out

 Out::

      Downloading http://data.astropy.org/tutorials/FITS-tables/chandra_events.fits [Done]


Display information about the contents of the FITS file.


.. code-block:: python


    fits.info(event_filename)





.. rst-class:: sphx-glr-script-out

 Out::

      Filename: /home/docs/.astropy/cache/download/py2/906ea1e642b1cb91dfa26ef2a2a935ba
    No.    Name         Type      Cards   Dimensions   Format
    0    PRIMARY     PrimaryHDU      32   ()              
    1    EVENTS      BinTableHDU    937   51850R x 26C   [1D, 1J, 1E, 1E, 1I, 1I, 1I, 1I, 1E, 1E, 1E, 1E, 1I, 1J, 1I, 1E, 1I, 1I, 1I, 1I, 1E, 1E, 1I, 1I, 1I, 32X]   
    2    GTI         BinTableHDU     28   1R x 2C      [1D, 1D]   
    3    GTI         BinTableHDU     28   1R x 2C      [1D, 1D]   
    4    GTI         BinTableHDU     28   1R x 2C      [1D, 1D]   
    5    GTI         BinTableHDU     28   1R x 2C      [1D, 1D]   
    6    REGION      BinTableHDU    264   3R x 9C      [1I, 16A, 1E, 1E, 2E, 1E, 16A, 1I, 1I]


Extension 1, EVENTS, is a Table that contains information about each X-ray
photon that hit Chandra's HETG-S detector.

Use `~astropy.table.Table` to read the table


.. code-block:: python


    events = Table.read(event_filename, hdu=1)







Print the column names of the Events Table.


.. code-block:: python


    print(events.columns)





.. rst-class:: sphx-glr-script-out

 Out::

      <TableColumns names=('time','expno','tg_r','tg_d','chipx','chipy','tdetx','tdety','detx','dety','x','y','ccd_id','pha','pi','energy','grade','fltgrade','node_id','tg_m','tg_lam','tg_mlam','tg_srcid','tg_part','tg_smap','status')>


If a column contains unit information, it will have an associated
`astropy.units` object.


.. code-block:: python


    print(events['energy'].unit)





.. rst-class:: sphx-glr-script-out

 Out::

      eV


Print the data stored in the Energy column.


.. code-block:: python


    print(events['energy'])




.. rst-class:: sphx-glr-script-out

 Out::

      energy
       eV  
    -------
    5567.74
    4567.13
    5397.79
    4964.62
     4600.1
    1873.79
    5399.74
    7463.69
    3636.53
    3578.51
        ...
    2105.02
    2039.68
    2435.06
    2494.82
    5204.24
    1625.02
    3549.63
    5152.93
    2807.87
    3086.63
    Length = 51850 rows


**Total running time of the script:**
(0 minutes 1.568 seconds)



.. container:: sphx-glr-download

    **Download Python source code:** :download:`fits-tables.py <fits-tables.py>`


.. container:: sphx-glr-download

    **Download IPython notebook:** :download:`fits-tables.ipynb <fits-tables.ipynb>`