utils: I/O utilities

I/O utility functions

silx.io.utils.save1D(fname, x, y, xlabel=None, ylabels=None, filetype=None, fmt='%.7g', csvdelim=';', newline='\n', header='', footer='', comments='#', autoheader=False)

Saves any number of curves to various formats: Specfile, CSV, txt or npy. All curves must have the same number of points and share the same x values.

Parameters:

• fname – Output file path, or file handle open in write mode. If fname is a path, file is opened in w mode. Existing file with a same name will be overwritten.
• x – 1D-Array (or list) of abscissa values.
• y – 2D-array (or list of lists) of ordinates values. First index is the curve index, second index is the sample index. The length of the second dimension (number of samples) must be equal to len(x). y can be a 1D-array in case there is only one curve to be saved.
• filetype – Filetype: "spec", "csv", "txt", "ndarray". If None, filetype is detected from file name extension (.dat, .csv, .txt, .npy).
• xlabel – Abscissa label
• ylabels – List of y labels
• fmt – Format string for data. You can specify a short format string that defines a single format for both x and y values, or a list of two different format strings (e.g. ["%d", "%.7g"]). Default is "%.7g". This parameter does not apply to the npy format.
• csvdelim – String or character separating columns in txt and CSV formats. The user is responsible for ensuring that this delimiter is not used in data labels when writing a CSV file.
• newline – String or character separating lines/records in txt format (default is line break character \n).
• header – String that will be written at the beginning of the file in txt format.
• footer – String that will be written at the end of the file in txt format.
• comments – String that will be prepended to the header and footer strings, to mark them as comments. Default: #.
• autoheader – In CSV or txt, True causes the first header line to be written as a standard CSV header line with column labels separated by the specified CSV delimiter.

When saving to Specfile format, each curve is saved as a separate scan with two data columns (x and y).

CSV and txt formats are similar, except that the txt format allows user defined header and footer text blocks, whereas the CSV format has only a single header line with columns labels separated by field delimiters and no footer. The txt format also allows defining a record separator different from a line break.

The npy format is written with numpy.save and can be read back with numpy.load. If xlabel and ylabels are undefined, data is saved as a regular 2D numpy.ndarray (contatenation of x and y). If both xlabel and ylabels are defined, the data is saved as a numpy.recarray after being transposed and having labels assigned to columns.

silx.io.utils.savetxt(fname, X, fmt='%.7g', delimiter=';', newline='\n', header='', footer='', comments='#')

numpy.savetxt backport of header and footer arguments from numpy=1.7.0.

See numpy.savetxt help: http://docs.scipy.org/doc/numpy-1.10.0/reference/generated/numpy.savetxt.html

silx.io.utils.savespec(specfile, x, y, xlabel='X', ylabel='Y', fmt='%.7g', scan_number=1, mode='w', write_file_header=True, close_file=False)

Saves one curve to a SpecFile.

The curve is saved as a scan with two data columns. To save multiple curves to a single SpecFile, call this function for each curve by providing the same file handle each time.

Parameters:

• specfile – Output SpecFile name, or file handle open in write or append mode. If a file name is provided, a new file is open in write mode (existing file with the same name will be lost)
• x – 1D-Array (or list) of abscissa values
• y – 1D-array (or list) of ordinates values
• xlabel – Abscissa label (default "X")
• ylabel – Ordinate label
• fmt – Format string for data. You can specify a short format string that defines a single format for both x and y values, or a list of two different format strings (e.g. ["%d", "%.7g"]). Default is "%.7g".
• scan_number – Scan number (default 1).
• mode – Mode for opening file: w (default), a, r+, w+, a+. This parameter is only relevant if specfile is a path.
• write_file_header – If True, write a file header before writing the scan (#F and #D line).
• close_file – If True, close the file after saving curve.

Returns:

None if close_file is True, else return the file handle.

silx.io.utils.h5ls(h5group, lvl=0)

Return a simple string representation of a HDF5 tree structure.

Parameters:

• h5group – Any h5py.Group or h5py.File instance, or a HDF5 file name
• lvl – Number of tabulations added to the group. lvl is incremented as we recursively process sub-groups.

Returns:

String representation of an HDF5 tree structure

Group names and dataset representation are printed preceded by a number of tabulations corresponding to their depth in the tree structure. Datasets are represented as h5py.Dataset objects.

Example:

>>> print(h5ls("Downloads/sample.h5"))
+fields
    +fieldB
        <HDF5 dataset "z": shape (256, 256), type "<f4">
    +fieldE
        <HDF5 dataset "x": shape (256, 256), type "<f4">
        <HDF5 dataset "y": shape (256, 256), type "<f4">

Note

This function requires h5py to be installed.

silx.io.utils.open(filename)

Open a file as an h5py-like object.

Format supported: - h5 files, if h5py module is installed - SPEC files exposed as a NeXus layout - raster files exposed as a NeXus layout (if fabio is installed) - Numpy files (‘npy’ and ‘npz’ files)

The filename can be trailled an HDF5 path using the separator ::. In this case the object returned is a proxy to the target node, implementing the close function and supporting with context.

The file is opened in read-only mode.

Parameters:filename (str) – A filename which can containt an HDF5 path by using :: separator. Raises:IOError if the file can’t be loaded or path can’t be found Return type:h5py-like node

silx.io.utils.load(*args, **kwargs)

Load a file as an h5py.File-like object.

Format supported: - h5 files, if h5py module is installed - Spec files if SpecFile module is installed

Deprecated since version 0.4: Use open(), or silx.io.open(). Will be removed in Silx 0.5.

Parameters:filename (str) – A filename Raises:IOError if the file can’t be loaded as an h5py.File like object Return type:h5py.File

silx.io.utils.get_h5py_class(obj)

Returns the h5py class from an object.

If it is an h5py object or an h5py-like object, an h5py class is returned. If the object is not an h5py-like object, None is returned.

Parameters:obj – An object Returns:An h5py object

silx.io.utils.is_file(obj)

True is the object is an h5py.File-like object.

Parameters:obj – An object

silx.io.utils.is_group(obj)

True if the object is a h5py.Group-like object.

Parameters:obj – An object

silx.io.utils.is_dataset(obj)

True if the object is a h5py.Dataset-like object.

Parameters:obj – An object

silx.io.utils.is_softlink(obj)

True if the object is a h5py.SoftLink-like object.

Parameters:obj – An object