DataFile

class ndmapper.data.DataFile(filename=None, data=None, meta=None, mode=None, strip=False, prefix=None, suffix=None, dirname=None, labels=None)

Bases: object

A class representing a data-file-like object, including a filename and/or a list of associated NDData instances, along with any ancillary data such as a primary header, binary tables that describe the file as a whole and aren’t part of the NDData structure itself or processing history.

This class can simply store a collection of associated NDData instances in memory or it can simply store a filename, eg. for use with IRAF tasks that do disk-based I/O, or it can do both, handling any loading & saving. In principle this abstraction allows mixing Python code operating on NDData fairly seamlessly with steps that do disk I/O (eg. IRAF tasks, as long as expectations regarding metadata are compatible), as well as providing a convenient file-like way of organizing an NDData collection.

Parameters:

filename : str or FileName, optional

The filename on disk of the dataset(s) to be represented.

data : NDData or list of NDData or DataFile or None, optional

NDData instance(s) for the dataset(s) to be represented, or an existing DataFile instance (in which case the result will be a new DataFile referring to the same NDData instance(s) as the original [this will be changed so they are separate instances referring to the same data, allowing lazy loading to be mapped differently, eg. after one file is saved, to avoid surprises]).

If “filename” refers to an existing file and “data” is None, the data will be mapped lazily from that file (data=[] can be used to avoid this if the intention is to replace any existing data). Otherwise, the user-specified data will be used instead.

meta : dict-like, optional

A meta-data dictionary / header describing the file as a whole (rather than any individual nddata object), replacing any existing meta-data if the file already exists on disk.

mode : str, optional

‘read’ (default), ‘new’, ‘update’ or ‘overwrite’ Specifies whether the file should exist on disk already and be used to initialize this DataFile (if a filename is provided) and whether it can later be written to disk. Although ndmapper does not hold file handles open with a fixed access mode, these options enforce the user’s declared intention, to avoid mishaps (such as inadvertently overwriting input files or failures when working in the wrong directory). With ‘read’ and ‘update’, the specified file must already exist, with ‘new’, it must not exist and with ‘overwrite’, any existing file is ignored and will be replaced when writing to disk. The ‘data’ and ‘filename’ parameters always override whatever would otherwise be read from disk. When no filename is given, the default is ‘new’ instead of ‘read’.

strip : bool, optional

Remove any existing prefix and suffixes from the supplied filename (prior to adding any specified prefix & suffix)?

prefix : str or None, optional

Prefix string to add before the base filename.

suffix : str or None, optional

Suffix string to add after the base filename (including any initial separator).

dirname : str or None, optional

Directory name to add to the filename (replacing any existing dir).

labels : str or dict of str

Naming of each NDData component array in the corresponding file on disk, overriding the package default values in config[‘labels’]. Where a string is given, it overrides only the label of the main data array (ie. config[‘labels’][‘data’]).

Attributes

filename	(FileName or None) A filename-parsing object representing the path on disk.
mode	(str) File access mode (see parameters). This initially reflects the corresponding parameter value / default and can change implicitly in certain circumstances when loading, saving or changing the filename.
meta	(dict-like) The header/meta-data associated with the file as a whole (eg. the primary FITS header) rather than an individual nddata instance.
cals	(dict of str) A dictionary of associated processed calibrations, mapping calibration types (eg. ‘bias’) to DataFile instances that can be (or have been) used by the corresponding calibration steps. This attribute is currently not persistent when saving to disk, so any calibrations must be associated explicitly on reloading, if needed.
The NDData instance(s) associated with the DataFile are accessed by
iterating over or subscripting it like a list.

Attributes Summary

cals
filename
log
meta
mode
next_ident	Return the next integer identifier greater than any existing integer identifier(s) or None if one or more existing identifier is undefined.
unloaded

Methods Summary

add(operand, **kwargs)
append(item)
bitwise_and(operand, **kwargs)
bitwise_or(operand, **kwargs)
bitwise_xor(operand, **kwargs)
divide(operand, **kwargs)
extend(items)
invert(**kwargs)
multiply(operand, **kwargs)
next()
reload()	Re-load NDData instances & shared meta-data from the associated file on disk (eg.
renumber([idents])	Re-number/name the (ident attributes of) member NDData instances, either with user-supplied values or sequentially.
save()	Save NDData instances & common meta-data to the associated file, creating it if it doesn’t already exist.
subtract(operand, **kwargs)

Attributes Documentation

cals

filename

log = ''

meta

mode

next_ident

Return the next integer identifier greater than any existing integer identifier(s) or None if one or more existing identifier is undefined.

unloaded

Methods Documentation

add(operand, **kwargs)

append(item)

bitwise_and(operand, **kwargs)

bitwise_or(operand, **kwargs)

bitwise_xor(operand, **kwargs)

divide(operand, **kwargs)

extend(items)

invert(**kwargs)

multiply(operand, **kwargs)

next()

reload()

Re-load NDData instances & shared meta-data from the associated file on disk (eg. to synchronize the DataFile instance with any changes made by external programs such as IRAF).

When instantiating a new DataFile object, it is unnecessary to run reload() afterwards if the associated file already exists; it will be read automatically.

Note that data arrays are not actually copied into memory here; they are re-mapped and still lazily-loaded once referenced (if applicable).

renumber(idents=None)

Re-number/name the (ident attributes of) member NDData instances, either with user-supplied values or sequentially.

Parameters:

idents : list of int, optional

The identifiers to use, if not numbering sequentially from 1. The intention is also to allow a list of str later (see NDLater).

save()

Save NDData instances & common meta-data to the associated file, creating it if it doesn’t already exist.

subtract(operand, **kwargs)