unpack_data

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.

Parameters:

  • 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.

Returns:

The data set object.

Return type:

instance

Raises:

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

See also

get_data

Return the data set by identifier.

load_arrays

Create a data set from array values.

load_data

Load a data set from a file.

set_data

Set a data set.

unpack_arrays

Create a sherpa data object from arrays of data.

Notes

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.

Examples

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)