# ASCII Tables (astropy.io.ascii)¶

## Introduction¶

astropy.io.ascii provides methods for reading and writing a wide range of ASCII data table formats via built-in Extension Reader classes. The emphasis is on flexibility and ease of use, although readers can optionally use a less flexible C/Cython engine for reading and writing for improved performance.

The following shows a few of the ASCII formats that are available, while the section on Supported formats contains the full list.

The astropy.io.ascii package is built on a modular and extensible class structure with independent Base class elements so that new formats can be easily accommodated.

Note

It is also possible to use the functionality from astropy.io.ascii through a higher-level interface in the astropy.table package. See Unified file read/write interface for more details.

## Getting Started¶

The majority of commonly encountered ASCII tables can be easily read with the read() function. Assume you have a file named sources.dat with the following contents:

obsid redshift  X      Y     object
3102  0.32      4167  4085   Q1250+568-A
877   0.22      4378  3892   "Source 82"


This table can be read with the following:

>>> from astropy.io import ascii
>>> print data
obsid redshift  X    Y      object
----- -------- ---- ---- -----------
3102     0.32 4167 4085 Q1250+568-A
877     0.22 4378 3892   Source 82


The first argument to the read() function can be the name of a file, a string representation of a table, or a list of table lines. By default read() will try to guess the table format by trying all the supported formats. If this does not work (for unusually formatted tables) then one needs give astropy.io.ascii additional hints about the format, for example:

>>> lines = ['objID                   & osrcid            & xsrcid       ',
...          '----------------------- & ----------------- & -------------',
...          '              277955213 & S000.7044P00.7513 & XS04861B6_005',
...          '              889974380 & S002.9051P14.7003 & XS03957B7_004']
>>> data = ascii.read(lines, data_start=2, delimiter='&')
>>> print(data)
objID         osrcid          xsrcid
--------- ----------------- -------------
277955213 S000.7044P00.7513 XS04861B6_005
889974380 S002.9051P14.7003 XS03957B7_004


If the format of a file is known (e.g. it is a fixed width table or an IPAC table), then it is more efficient and reliable to provide a value for the format argument from one of the values in the supported formats. For example:

>>> data = ascii.read(lines, format='fixed_width_two_line', delimiter='&')


For simpler formats such as CSV, read() will automatically try reading with the Cython/C parsing engine, which is significantly faster than the ordinary Python implementation (described in Fast ASCII I/O). If the fast engine fails, read() will fall back on the Python reader by default. The argument fast_reader can be specified to control this behavior. For example, to disable the fast engine:

>>> data = ascii.read(lines, format='csv', fast_reader=False)


### Writing Tables¶

The write() function provides a way to write a data table as a formatted ASCII table. For example the following writes a table as a simple space-delimited file:

>>> import numpy as np
>>> from astropy.table import Table
>>> x = np.array([1, 2, 3])
>>> y = x ** 2
>>> data = Table([x, y], names=['x', 'y'])
>>> ascii.write(data, 'values.dat')


The values.dat file will then contain:

x y
1 1
2 4
3 9


All of the input Reader formats supported by astropy.io.ascii for reading are also supported for writing. This provides a great deal of flexibility in the format for writing. The example below writes the data as a LaTeX table, using the option to send the output to sys.stdout instead of a file:

>>> import sys
>>> ascii.write(data, sys.stdout, format='latex')
\begin{table}
\begin{tabular}{cc}
x & y \\
1 & 1 \\
2 & 4 \\
3 & 9 \\
\end{tabular}
\end{table}


There is also a faster Cython engine for writing simple formats, which is enabled by default for these formats (see Fast ASCII I/O). To disable this engine, use the parameter fast_writer:

>>> ascii.write(data, 'values.csv', format='csv', fast_writer=False)


## Supported formats¶

A full list of the supported format values and corresponding format types for ASCII tables is given below. The Write column indicates which formats support write functionality, and the Fast column indicates which formats are compatible with the fast Cython/C engine for reading and writing.

Format Write Fast Description
aastex Yes   AASTex: AASTeX deluxetable used for AAS journals
basic Yes Yes Basic: Basic table with custom delimiters
cds     Cds: CDS format table
csv Yes Yes Csv: Basic table with comma-separated values
daophot     Daophot: IRAF DAOphot format table
fixed_width Yes   FixedWidth: Fixed width
fixed_width_two_line Yes   FixedWidthTwoLine: Fixed width with second header line
html Yes   HTML: HTML format table
ipac Yes   Ipac: IPAC format table
latex Yes   Latex: LaTeX table
rdb Yes Yes Rdb: Tab-separated with a type definition header line
sextractor     SExtractor: SExtractor format table
tab Yes Yes Tab: Basic table with tab-separated values

## Using astropy.io.ascii¶

The details of using astropy.io.ascii are provided in the following sections:

## Reference/API¶

### astropy.io.ascii Module¶

An extensible ASCII table reader and writer.

#### Functions¶

 convert_numpy(numpy_type) Return a tuple (converter_func, converter_type). get_reader([Reader, Inputter, Outputter]) Initialize a table reader allowing for common customizations. get_writer([Writer, fast_writer]) Initialize a table writer allowing for common customizations. read(table[, guess]) Read the input table and return the table. set_guess(guess) Set the default value of the guess parameter for read() write(table[, output, format, Writer, ...]) Write the input table to filename.