sherpa.ui.unpack_data(filename, ncols=2, colkeys=None, dstype=<class 'sherpa.data.Data1D'>, sep=' ', comment='#', require_floats=True)

Create a sherpa data object from an ASCII file.

This function is used to read in columns from an ASCII file and convert them to a Sherpa data object.

  • filename (str) – The name of the ASCII file to read in.

  • ncols (int, optional) – The number of columns to read in (the first ncols columns in the file).

  • colkeys (array of str, optional) – An array of the column name to read in. The default is None.

  • dstype (data class to use, optional) – What type of data is to be used. Supported values include Data1D (the default), Data1DInt, Data2D, and Data2DInt.

  • sep (str, optional) – The separator character. The default is ' '.

  • comment (str, optional) – The comment character. The default is '#'.

  • require_floats (bool, optional) – If True (the default), non-numeric data values will raise a ValueError.


The data set object.

Return type:



ValueError – If a column value can not be converted into a numeric value and the require_floats parameter is True.

See also


Return the data set by identifier.


Create a data set from array values.


Load a data set from a file.


Set a data set.


Create a sherpa data object from arrays of data.


The file reading is performed by sherpa.io.get_ascii_data, which reads in each line from the file, strips out any unsupported characters (replacing them by the sep argument), skips empty lines, and then identifies whether it is a comment or data line.

The list of unsupported characters are: tab, new line, carriage return, comma, semi-colon, colon, space, and “|”.

The last comment line before the data is used to define the column names, splitting the line by the sep argument. If there are no comment lines then the columns are named starting at col1, col2, increasing up to the number of columns.

Data lines are separated into columns - splitting by the sep comment - and then converted to NumPy arrays. If the require_floats argument is True then the column will be converted to the sherpa.utils.SherpaFloat type, with an error raised if this fails.

An error is raised if the number of columns per row is not constant.

If the colkeys argument is used then a case-sensitive match is used to determine what columns to return.


Create a data object from the first two columns of the file “src.dat” and use it to create a Sherpa data set called “src”:

>>> dat = unpack_data('src.dat')
>>> set_data('src', dat)

Read in the first three columns - the independent axis (x), the dependent variable (y), and the error on y:

>>> dat = unpack_data('src.dat', ncols=3)

Read in the X and Y columns from the file. The last line before the data must contain the column names:

>>> dat = unpack_data('src.dat', colkeys=['X', 'Y'])

Read in a histogram:

>>> cols = ['XLO', 'XHI', 'Y']
>>> idat = unpack_data('hist.dat', colkeys=cols,
...                    dstype=ui.Data1DInt)