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.
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.
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
>>> data = ascii.read("sources.dat")
>>> 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='&')
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}
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.
| Format | Write | Description |
|---|---|---|
| aastex | Yes | AASTex: AASTeX deluxetable used for AAS journals |
| basic | Yes | Basic: Basic table with custom delimiters |
| cds | Cds: CDS format table | |
| commented_header | Yes | CommentedHeader: Column names in a commented line |
| csv | Yes | Csv: Basic table with comma-separated values |
| daophot | Daophot: IRAF DAOphot format table | |
| fixed_width | Yes | FixedWidth: Fixed width |
| fixed_width_no_header | Yes | FixedWidthNoHeader: Fixed width with no header |
| 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 |
| no_header | Yes | NoHeader: Basic table with no headers |
| rdb | Yes | Rdb: Tab-separated with a type definition header line |
| sextractor | SExtractor: SExtractor format table | |
| tab | Yes | Tab: Basic table with tab-separated values |
The details of using astropy.io.ascii are provided in the following sections:
An extensible ASCII table reader and writer.
| 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]) | 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. |
| AASTex(**kwargs) | Write and read AASTeX tables. |
| AllType | Subclass of all other data types. |
| BaseData() | Base table data reader. |
| BaseHeader() | Base table header reader |
| BaseInputter | Get the lines from the table input and return a list of lines. |
| BaseOutputter | Output table as a dict of column objects keyed on column name. |
| BaseReader() | Class providing methods to read and write an ASCII table using the specified header, data, inputter, and outputter instances. |
| BaseSplitter | Base splitter that uses python’s split method to do the work. |
| Basic() | Read a character-delimited table with a single header line at the top followed by data lines to the end of the table. |
| Cds([readme]) | Read a CDS format table. |
| Column(name) | Table column. |
| CommentedHeader() | Read a file where the column names are given in a line that begins with the header comment character. |
| ContinuationLinesInputter | Inputter where lines ending in continuation_char are joined with the subsequent line. |
| Csv() | Read a CSV (comma-separated-values) file. |
| Daophot() | Read a DAOphot file. |
| DefaultSplitter() | Default class to split strings into columns using python csv. |
| FixedWidth([col_starts, col_ends, ...]) | Read or write a fixed width table with a single header line that defines column names and positions. |
| FixedWidthData() | Base table data reader. |
| FixedWidthHeader() | Fixed width table header reader. |
| FixedWidthNoHeader([col_starts, col_ends, ...]) | Read or write a fixed width table which has no header line. |
| FixedWidthSplitter | Split line based on fixed start and end positions for each col in self.cols. |
| FixedWidthTwoLine([position_line, ...]) | Read or write a fixed width table which has two header lines. |
| FloatType | Describes floating-point data. |
| HTML([htmldict]) | Read and write HTML tables. |
| InconsistentTableError | Indicates that an input table is inconsistent in some way. |
| IntType | Describes integer data. |
| Ipac([definition, DBMS]) | Read or write an IPAC format table. |
| Latex([ignore_latex_commands, latexdict, ...]) | Write and read LaTeX tables. |
| NoHeader() | Read a table with no header line. |
| NoType | Superclass for StrType and NumType classes. |
| NumType | Indicates that a column consists of numerical data. |
| Rdb() | Read a tab-separated file with an extra line after the column definition line. |
| SExtractor() | Read a SExtractor file. |
| StrType | Indicates that a column consists of text data. |
| Tab() | Read a tab-separated file. |
| TableOutputter | Output the table as an astropy.table.Table object. |
| WhitespaceSplitter() |
digraph inheritance23153a92a7 { rankdir=LR; size="8.0, 12.0"; "AASTex" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.AASTex.html#astropy.io.ascii.AASTex",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Write and read AASTeX tables.",height=0.25,shape=box,fontsize=10]; "Latex" -> "AASTex" [arrowsize=0.5,style="setlinewidth(0.5)"]; "AllType" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.AllType.html#astropy.io.ascii.AllType",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Subclass of all other data types.",height=0.25,shape=box,fontsize=10]; "StrType" -> "AllType" [arrowsize=0.5,style="setlinewidth(0.5)"]; "FloatType" -> "AllType" [arrowsize=0.5,style="setlinewidth(0.5)"]; "IntType" -> "AllType" [arrowsize=0.5,style="setlinewidth(0.5)"]; "BaseData" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.BaseData.html#astropy.io.ascii.BaseData",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Base table data reader.",height=0.25,shape=box,fontsize=10]; "BaseHeader" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.BaseHeader.html#astropy.io.ascii.BaseHeader",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Base table header reader",height=0.25,shape=box,fontsize=10]; "BaseInputter" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.BaseInputter.html#astropy.io.ascii.BaseInputter",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Get the lines from the table input and return a list of lines. The input",height=0.25,shape=box,fontsize=10]; "BaseOutputter" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.BaseOutputter.html#astropy.io.ascii.BaseOutputter",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Output table as a dict of column objects keyed on column name. The",height=0.25,shape=box,fontsize=10]; "BaseReader" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.BaseReader.html#astropy.io.ascii.BaseReader",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Class providing methods to read and write an ASCII table using the specified",height=0.25,shape=box,fontsize=10]; "BaseSplitter" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.BaseSplitter.html#astropy.io.ascii.BaseSplitter",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Base splitter that uses python's split method to do the work.",height=0.25,shape=box,fontsize=10]; "Basic" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.Basic.html#astropy.io.ascii.Basic",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Read a character-delimited table with a single header line at the top",height=0.25,shape=box,fontsize=10]; "BaseReader" -> "Basic" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Cds" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.Cds.html#astropy.io.ascii.Cds",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Read a CDS format table. See http://vizier.u-strasbg.fr/doc/catstd.htx.",height=0.25,shape=box,fontsize=10]; "BaseReader" -> "Cds" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Column" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.Column.html#astropy.io.ascii.Column",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Table column.",height=0.25,shape=box,fontsize=10]; "CommentedHeader" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.CommentedHeader.html#astropy.io.ascii.CommentedHeader",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Read a file where the column names are given in a line that begins with",height=0.25,shape=box,fontsize=10]; "BaseReader" -> "CommentedHeader" [arrowsize=0.5,style="setlinewidth(0.5)"]; "ContinuationLinesInputter" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.ContinuationLinesInputter.html#astropy.io.ascii.ContinuationLinesInputter",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Inputter where lines ending in ``continuation_char`` are joined",height=0.25,shape=box,fontsize=10]; "BaseInputter" -> "ContinuationLinesInputter" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Csv" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.Csv.html#astropy.io.ascii.Csv",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Read a CSV (comma-separated-values) file.",height=0.25,shape=box,fontsize=10]; "Basic" -> "Csv" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Daophot" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.Daophot.html#astropy.io.ascii.Daophot",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Read a DAOphot file.",height=0.25,shape=box,fontsize=10]; "BaseReader" -> "Daophot" [arrowsize=0.5,style="setlinewidth(0.5)"]; "DefaultSplitter" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.DefaultSplitter.html#astropy.io.ascii.DefaultSplitter",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Default class to split strings into columns using python csv. The class",height=0.25,shape=box,fontsize=10]; "BaseSplitter" -> "DefaultSplitter" [arrowsize=0.5,style="setlinewidth(0.5)"]; "FixedWidth" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.FixedWidth.html#astropy.io.ascii.FixedWidth",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Read or write a fixed width table with a single header line that defines column",height=0.25,shape=box,fontsize=10]; "BaseReader" -> "FixedWidth" [arrowsize=0.5,style="setlinewidth(0.5)"]; "FixedWidthData" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.FixedWidthData.html#astropy.io.ascii.FixedWidthData",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Base table data reader.",height=0.25,shape=box,fontsize=10]; "BaseData" -> "FixedWidthData" [arrowsize=0.5,style="setlinewidth(0.5)"]; "FixedWidthHeader" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.FixedWidthHeader.html#astropy.io.ascii.FixedWidthHeader",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Fixed width table header reader.",height=0.25,shape=box,fontsize=10]; "BaseHeader" -> "FixedWidthHeader" [arrowsize=0.5,style="setlinewidth(0.5)"]; "FixedWidthNoHeader" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.FixedWidthNoHeader.html#astropy.io.ascii.FixedWidthNoHeader",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Read or write a fixed width table which has no header line. Column",height=0.25,shape=box,fontsize=10]; "FixedWidth" -> "FixedWidthNoHeader" [arrowsize=0.5,style="setlinewidth(0.5)"]; "FixedWidthSplitter" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.FixedWidthSplitter.html#astropy.io.ascii.FixedWidthSplitter",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Split line based on fixed start and end positions for each ``col`` in",height=0.25,shape=box,fontsize=10]; "BaseSplitter" -> "FixedWidthSplitter" [arrowsize=0.5,style="setlinewidth(0.5)"]; "FixedWidthTwoLine" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.FixedWidthTwoLine.html#astropy.io.ascii.FixedWidthTwoLine",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Read or write a fixed width table which has two header lines. The first",height=0.25,shape=box,fontsize=10]; "FixedWidth" -> "FixedWidthTwoLine" [arrowsize=0.5,style="setlinewidth(0.5)"]; "FloatType" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.FloatType.html#astropy.io.ascii.FloatType",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Describes floating-point data.",height=0.25,shape=box,fontsize=10]; "NumType" -> "FloatType" [arrowsize=0.5,style="setlinewidth(0.5)"]; "HTML" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.HTML.html#astropy.io.ascii.HTML",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Read and write HTML tables.",height=0.25,shape=box,fontsize=10]; "BaseReader" -> "HTML" [arrowsize=0.5,style="setlinewidth(0.5)"]; "InconsistentTableError" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.InconsistentTableError.html#astropy.io.ascii.InconsistentTableError",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Indicates that an input table is inconsistent in some way.",height=0.25,shape=box,fontsize=10]; "IntType" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.IntType.html#astropy.io.ascii.IntType",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Describes integer data.",height=0.25,shape=box,fontsize=10]; "NumType" -> "IntType" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Ipac" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.Ipac.html#astropy.io.ascii.Ipac",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Read or write an IPAC format table. See",height=0.25,shape=box,fontsize=10]; "FixedWidth" -> "Ipac" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Latex" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.Latex.html#astropy.io.ascii.Latex",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Write and read LaTeX tables.",height=0.25,shape=box,fontsize=10]; "BaseReader" -> "Latex" [arrowsize=0.5,style="setlinewidth(0.5)"]; "NoHeader" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.NoHeader.html#astropy.io.ascii.NoHeader",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Read a table with no header line. Columns are autonamed using",height=0.25,shape=box,fontsize=10]; "Basic" -> "NoHeader" [arrowsize=0.5,style="setlinewidth(0.5)"]; "NoType" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.NoType.html#astropy.io.ascii.NoType",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Superclass for ``StrType`` and ``NumType`` classes.",height=0.25,shape=box,fontsize=10]; "NumType" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.NumType.html#astropy.io.ascii.NumType",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Indicates that a column consists of numerical data.",height=0.25,shape=box,fontsize=10]; "NoType" -> "NumType" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Rdb" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.Rdb.html#astropy.io.ascii.Rdb",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Read a tab-separated file with an extra line after the column definition",height=0.25,shape=box,fontsize=10]; "Tab" -> "Rdb" [arrowsize=0.5,style="setlinewidth(0.5)"]; "SExtractor" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.SExtractor.html#astropy.io.ascii.SExtractor",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Read a SExtractor file.",height=0.25,shape=box,fontsize=10]; "BaseReader" -> "SExtractor" [arrowsize=0.5,style="setlinewidth(0.5)"]; "StrType" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.StrType.html#astropy.io.ascii.StrType",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Indicates that a column consists of text data.",height=0.25,shape=box,fontsize=10]; "NoType" -> "StrType" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Tab" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.Tab.html#astropy.io.ascii.Tab",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Read a tab-separated file. Unlike the :class:`Basic` reader, whitespace is",height=0.25,shape=box,fontsize=10]; "Basic" -> "Tab" [arrowsize=0.5,style="setlinewidth(0.5)"]; "TableOutputter" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.TableOutputter.html#astropy.io.ascii.TableOutputter",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="Output the table as an astropy.table.Table object.",height=0.25,shape=box,fontsize=10]; "BaseOutputter" -> "TableOutputter" [arrowsize=0.5,style="setlinewidth(0.5)"]; "WhitespaceSplitter" [style="setlinewidth(0.5)",URL="../../api/astropy.io.ascii.WhitespaceSplitter.html#astropy.io.ascii.WhitespaceSplitter",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",height=0.25,shape=box,fontsize=10]; "DefaultSplitter" -> "WhitespaceSplitter" [arrowsize=0.5,style="setlinewidth(0.5)"]; }