pts.storedtable.io Namespace Reference

Input/output functions for files in the SKIRT stored table and stored column format. More...

Functions
def	arrayFromFile (fd, shape)
	This helper function reads a sequence of doubles from the specified (open) file to a numpy array with the given shape. More...
def	arrayToFile (fd, a)
	This helper function writes the specified numpy array to the given (open) file as a sequence of doubles in the required order (first index varies most rapidly). More...
def	intFromFile (fd)
	This helper function reads an 8-byte little-endian unsigned integer from the specified (open) file and returns the corresponding integer value. More...
def	intToFile (fd, n)
	This helper function writes the specified unsigned integer value to the given (open) file as a little-endian 8-byte sequence. More...
def	listStoredColumnsInfo (columnsFilePath)
	This function lists relevant metadata about the specified SKIRT stored columns file. More...
def	listStoredTableInfo (tableFilePath)
	This function lists relevant metadata about the specified SKIRT stored table file. More...
def	readStoredColumns (columnsFilePath)
	This function reads the specified SKIRT stored columns file and returns a dictionary with the following structure: More...
def	readStoredTable (tableFilePath)
	This function reads the specified SKIRT stored table file and returns a dictionary with the following structure: More...
def	stringFromFile (fd)
	This helper function reads an 8-byte name or unit string from the specified (open) file and returns the resulting variable-sized string after stripping trailing white space. More...
def	stringToFile (fd, s)
	This helper function writes the specified name or unit string to the given (open) file as an 8-byte sequence, after checking that the string adheres to the proper requirements. More...
def	writeStoredColumns (outFilePath, columnNames, columnUnits, values)
	This function writes the specified data and metadata to a disk file in SKIRT stored columns format. More...
def	writeStoredTable (outFilePath, axisNames, axisUnits, axisScales, axisGrids, quantityNames, quantityUnits, quantityScales, quantityValues)
	This function writes the specified data and metadata to a disk file in SKIRT stored table format. More...

Detailed Description

Input/output functions for files in the SKIRT stored table and stored column format.

The functions in this module allow reading and writing data and metadata from and to a disk file in SKIRT stored table format or in SKIRT stored column format.

SKIRT stored table format

The SKIRT stored table file format is intended for tabulating one or more physical quantities as a function of on one or more independent variables. It has been designed for representing built-in SKIRT resources but it can be used for multi-dimensional tables in other contexts.

A SKIRT stored table file contains binary data with a straightforward layout. The file is essentially a sequence of 8-byte data items. A data item can have one of three types:

• string: 1 to 8 printable and non-whitespace 7-bit ASCII characters, padded with spaces if needed.
• unsigned integer: 64-bit integer in little-endian byte order
• floating point: 64-bit double (IEEE 754) in little-endian byte order

The overall layout is as follows:

• SKIRT name/version tag
• Endianness tag
• numAxes
• axisName (x numAxes)
• axisUnit (x numAxes)
• axisScale (x numAxes)
• [ numPoints axisPoint (x numPoints) ] (x numAxes)
• numQuantities
• quantityName (x numQuantities)
• quantityUnit (x numQuantities)
• quantityScale (x numQuantities)
• value (x numQuantities x numPoints1 x ... x numPointsN)
• end-of-file tag

The values are ordered so that the quantity values for a particular point are next to each other, the first axis index varies most rapidly, and the last axis index varies least rapidly.

SKIRT stored columns format

The SKIRT stored columns file format stores a set of data columns and is intended as a faster replacement for large regular text column data files, without the benefit of being human readable. The format does not support non-leaf rows, so it cannot be used for adaptive mesh data.

A SKIRT stored columns file contains binary data with a straightforward layout. It can contain the same type of data items as described for stored tables above. The layout is similar but not identical to stored tables:

• SKIRT name/version tag
• Endianness tag
• 0 (to differentiate from stored table format, which stores the nr of axes here)
• numRows
• numColumns
• columnName (x numColumns)
• columnUnit (x numColumns)
• value (x numColumns x numRows)
• end-of-file tag

The values are ordered so that the column values for a particular row are next to each other.

Function Documentation

arrayFromFile()

def pts.storedtable.io.arrayFromFile	(		fd,
			shape
	)

This helper function reads a sequence of doubles from the specified (open) file to a numpy array with the given shape.

The doubles should appear in the file in the required order (first index varies most rapidly).

arrayToFile()

def pts.storedtable.io.arrayToFile	(		fd,
			a
	)

This helper function writes the specified numpy array to the given (open) file as a sequence of doubles in the required order (first index varies most rapidly).

intFromFile()

def pts.storedtable.io.intFromFile

(

fd

)

This helper function reads an 8-byte little-endian unsigned integer from the specified (open) file and returns the corresponding integer value.

intToFile()

def pts.storedtable.io.intToFile	(		fd,
			n
	)

This helper function writes the specified unsigned integer value to the given (open) file as a little-endian 8-byte sequence.

listStoredColumnsInfo()

def pts.storedtable.io.listStoredColumnsInfo

(

columnsFilePath

)

This function lists relevant metadata about the specified SKIRT stored columns file.

The printed information includes the names and units and ranges for each of the columns and the number of rows. The stored columns file path is interpreted as described for the pts.utils.absPath() function.

listStoredTableInfo()

def pts.storedtable.io.listStoredTableInfo

(

tableFilePath

)

This function lists relevant metadata about the specified SKIRT stored table file.

The printed information includes the names, units and ranges for each of the axes, and the names and units for each of the quantities. The table file path is interpreted as described for the pts.utils.absPath() function.

readStoredColumns()

def pts.storedtable.io.readStoredColumns

(

columnsFilePath

)

This function reads the specified SKIRT stored columns file and returns a dictionary with the following structure:

• columnNames: list of column names, in order of occurrence
• columnUnits: list of corresponding units
• for each column name: array with values (one per row) as an astropy quantity with the appropriate unit The stored columns file path is interpreted as described for the pts.utils.absPath() function.

readStoredTable()

def pts.storedtable.io.readStoredTable

(

tableFilePath

)

This function reads the specified SKIRT stored table file and returns a dictionary with the following structure:

• axisNames: list of axis names, in order of occurrence
• axisUnits: list of corresponding units
• axisScales: list of corresponding scales
• quantityNames: list of quantity names, in order of occurrence
• quantityUnits: list of corresponding units
• quantityScales: list of corresponding scales
• for each axis name: array with grid points as an astropy quantity with the appropriate unit
• for each quantity name: array with values as an astropy quantity with the appropriate unit The table file path is interpreted as described for the pts.utils.absPath() function.

stringFromFile()

def pts.storedtable.io.stringFromFile

(

fd

)

This helper function reads an 8-byte name or unit string from the specified (open) file and returns the resulting variable-sized string after stripping trailing white space.

stringToFile()

def pts.storedtable.io.stringToFile	(		fd,
			s
	)

This helper function writes the specified name or unit string to the given (open) file as an 8-byte sequence, after checking that the string adheres to the proper requirements.

writeStoredColumns()

def pts.storedtable.io.writeStoredColumns	(		outFilePath,
			columnNames,
			columnUnits,
			values
	)

This function writes the specified data and metadata to a disk file in SKIRT stored columns format.

Note

This low-level function does not support astropy quantities; it expects plain numpy arrays with values presented in the proper units (i.e. as declared by the unit strings).

The function expects the following arguments:

• outFilePath: the output file's absolute or relative path, including filename and '.scol' extension
• columnNames: a sequence of column name strings
• columnUnits: a sequence of column unit strings (should match supported SKIRT import units)
• values: a single 2D numpy array with shape (numColumns, numRows) or a sequence of numColumns 1D numpy arrays with length numRows specifying the values for each column in the correct units

A name or unit string must contain 1 to 8 printable and non-whitespace 7-bit ASCII characters. There must be at least one column; the number of rows may be zero. The output columns file path is interpreted as described for the pts.utils.absPath() function.

writeStoredTable()

def pts.storedtable.io.writeStoredTable	(		outFilePath,
			axisNames,
			axisUnits,
			axisScales,
			axisGrids,
			quantityNames,
			quantityUnits,
			quantityScales,
			quantityValues
	)

This function writes the specified data and metadata to a disk file in SKIRT stored table format.

Note

This low-level function does not support astropy quantities; it expects plain numpy arrays with values presented in the proper units (i.e. as declared by the unit strings).

The function expects the following arguments:

• outFilePath: the output file's absolute or relative path, including filename and '.stab' extension
• axisNames: a sequence of axis name strings
• axisUnits: a sequence of axis unit strings (should match internal SKIRT units, i.e. usually SI units)
• axisScales: a sequence of axis scale strings ('lin' or 'log') controlling interpolation behavior
• axisGrids: a sequence of numpy arrays specifying the grid points for each axis in the correct units
• quantityNames: a sequence of quantity name strings
• quantityUnits: a sequence of quantity unit strings (should match internal SKIRT units, i.e. usually SI units)
• quantityScales: a sequence of quantity scale strings ('lin' or 'log') controlling interpolation behavior
• quantityValues: a sequence of numpy arrays specifying the values for each quantity in the correct units; each array has indices in the same order and with the same range as the specified axes

The sequences must be nonempty and have the same number of items within each group (axis and quantity). A name or unit string must contain 1 to 8 printable and non-whitespace 7-bit ASCII characters. The output table file path is interpreted as described for the pts.utils.absPath() function.