The AstroData constructor constructs an in-memory representation of a dataset. If given a filename it uses pyfits to open the dataset, reads the header and detects applicable types. Binary data, such as pixel data, is left on disk until referenced.
Parameters: |
|
---|
Property: The data property can only be used for single-HDU AstroData instances, such as those returned during iteration. To set the data member, use ad.data = newdata, where newdata must be a numpy array. To get the data member, use npdata = ad.data.
The “data” member returns appropriate HDU’s data member(s) specifically for the case in which the AstroData instance has ONE HDU (in addition to the PHU). This allows a single-extension AstroData, such as AstroData generates through iteration, to be used as though it simply is just the one extension. One is dealing with single extension AstroData instances when iterating over the AstroData extensions and when picking out an extension by integer or tuple indexing. Eg.,
- for ad in dataset[SCI]:
- # ad is a single-HDU index
- ad.data = newdata
Returns: | data array associated with the single extension |
---|---|
Return type: | <ndarray> |
Raises: | Errors.SingleHDUMemberExcept |
Property: Returns a dictionary of all registered metadata descriptor functions defined on the instance.
Eg.,
{descriptor_function_name : descriptor value (dv)}
Returns: | dict of descriptor functions |
---|---|
Return type: | <dict> |
Property: ‘filename’ is monitored so that the mode can be changed from ‘readonly’ when ‘filename’ is changed.
Property: Returns the header member for Single-HDU AstroData instances.
The header property can only be used for single-HDU AstroData instances, such as those returned during iteration. It is a property attribute which uses get_header(..) and set_header(..) to access the header member with the “=” syntax. To set the header member, use ad.header = newheader, where newheader must be a pyfits.Header object. To get the header member, use hduheader = ad.header.
Returns: | header |
---|---|
Return type: | pyfits.Header |
Raises: | Errors.SingleHDUMemberExcept |
Property: Returns header member(s) for all extension (except PHU).
Returns: | list of pyfits.Header instances |
---|---|
Return type: | <list> |
Property: Returns a list of header-data units on the instance.
Returns: | The AstroData’s HDUList as returned by pyfits.open() |
---|---|
Return type: | <pyfits.HDUList> |
Property: Returns the instance’s primary HDU.
Returns: | The instance “phu” |
---|---|
Return type: | <PrimaryHDU> |
Property: Returns the composite list of AstroData classifications. I.e. the instance’s qualified type and status classifications.
Returns: | a list of types and status strings |
---|---|
Return type: | <list> |
AstroData instances behave as list-like objects and therefore pythonic slicing operations may be performed on instances of this class. This method provides support for list slicing with the “[]” syntax. Slicing is used to create AstroData objects associated with “subdata” of the parent AstroData object, that is, consisting of an HDUList made up of some subset of the parent MEF.
E.g.,
datasetA = AstroData(dataset=”datasetMEF.fits”)
datasetB = datasetA[‘SCI’]
datasetC = datasetA[2]
datasetD = datasetA[(“SCI”,1)]
etc.
In this case, after the operations, datasetB is an AstroData object associated with the same MEF, sharing some of the the same actual HDUs in memory as datasetA. The object in datasetB will behave as if the SCI extensions are its only members, and it does in fact have its own pyfits.HDUList. Note that ‘datasetA’ and ‘datasetB’ share the PHU and also the data structures of the HDUs they have in common, so that a change to ‘datasetA[(‘SCI’,1)].data’ will change the ‘datasetB[(‘SCI’,1)].data’ member and vice versa. They are in fact both references to the same numpy array in memory. The ‘HDUList’ is a different list, however, that references common HDUs. If a subdata related ‘AstroData’ object is written to disk, the resulting MEF will contain only the extensions in the subdata’s ‘HDUList’.
Note: Integer extensions start at 0 for the data-containing extensions, not at the PHU as with pyfits. This is important: ‘ad[0]’ is the first content extension, in a traditional MEF perspective, the extension AFTER the PHU; it is not the PHU! In AstroData instances, the PHU is purely a header, and not counted as an extension in the way that headers generally are not counted as their own elements in the array they contain meta-data for. The PHU can be accessed via the ‘phu’ member.
Parameters: | ext (<str>, <int>, or <tuple>) – Integer index, an index tuple (EXTNAME, EXTVER), or EXTNAME name. If an int or tuple, the single extension identified is wrapped with an AstroData instance, and single-extension members of the AstroData object can be used. A string ‘EXTNAME’ results in all extensions with the given EXTNAME wrapped by the new instance. |
---|---|
Returns: | AstroData instance associated with the subset of data. |
Return type: | <AstroData> |
Raises: | KeyError, IndexError |
Appends header-data units (HDUs) to the AstroData instance.
Parameters: |
|
---|
Method will close the ‘HDUList’ on this instance.
The count_exts() function returns the number of extensions matching the passed <extname> (as stored in the HDUs “EXTNAME” header).
Parameters: | extname (<str>) – the name of the extension, equivalent to the value associated with the “EXTNAME” key in the extension header. |
---|---|
Returns: | number of <extname> extensions |
Return type: | <int> |
Takes an extension index, either an integer or (EXTNAME, EXTVER) tuple, and returns the index location of the extension. If hduref is set to True, then the index returned is relative to the HDUList (0=PHU, 1=First non-PHU extension). If hduref is False (the default) then the index returned is relative to the AstroData numbering convention, where index=0 is the first extension in the MEF file.
The get_key_value() function is used to get the value associated with a given key in the data-header unit of a single-HDU AstroData instance (such as returned by iteration).
Note: | Single extension AstroData objects are those with only a single header-data unit besides the PHU. They may exist if a single extension file is loaded, but in general are produced by indexing or iteration instructions, Eg.:
The variable “sead” above is ensured to hold a single extension AstroData object, and can be used more convieniently. |
---|---|
Parameters: | key (<str> header keyword) – name of header keyword to set |
Returns: | header keyword value |
Return type: | <int>, or <float>, or <str> |
Raises: | SingleHDUMemberExcept |
Prints to stdout information about the phu and extensions found in the current instance.
Insert a header-data unit (HDUs) into the AstroData instance.
Parameters: |
|
---|
Method wraps a source dataset, which can be in memory as another AstroData or pyfits HDUList, or on disk, given as the string filename.
NOTE: In general, users should not use ‘open’ directly, but pass the filename to the AstroData constructor. The constructor uses open(..) however. Users should use the constructor, which may perform extra operations.
Parameters: |
|
---|
The phu_get_key_value(..) function returns the value associated with the given key within the primary header unit of the dataset. The value is returned as a string (storage format) and must be converted as necessary by the caller.
Parameters: | key (<str>) – name of header value to retrieve |
---|---|
Returns: | keyword value as string or None if not present. |
Return type: | <str> |
Add or update a keyword in the PHU of the AstroData object with a specific value and, optionally, a comment
Parameters: |
|
---|
Parameters: | index (<int>, or <tuple> (EXTNAME,EXTVER)) – the extension index, either an int or (EXTNAME, EXTVER) pair before which the extension is to be inserted. Note: the first data extension is [0], you cannot insert before the PHU. Index always refers to Astrodata Numbering system, 0 = HDU |
---|
The rename_ext(..) function is used in order to rename an HDU with a new EXTNAME and EXTVER identifier. Merely changing the EXTNAME and EXTVER values in the extensions pyfits.Header is not sufficient. Though the values change in the pyfits.Header object, there are special HDU class members which are not updated.
Warning: | This function manipulates private (or somewhat private) HDU members, specifically ‘name’ and ‘_extver’. STSCI has been informed of the issue and has made a special HDU function for performing the renaming. When generally available, this new function will be used instead of manipulating the HDU’s properties directly, and this function will call the new pyfits.HDUList(..) function. |
---|---|
Note: | Works only on single extension instances. |
Parameters: |
|
The set_key_value() function is used to set the value (and optionally the comment) associated with a given key in the data-header of a single-HDU AstroData instance. The value argument will be converted to string, so it must have a string operator member function or be passed in as string.
Note: | Single extension AstroData objects are those with only a single header-data unit besides the PHU. They may exist if a single extension file is loaded, but in general are produced by indexing or iteration instructions.Eg.:
The variable “sead” above is ensured to hold a single extension AstroData object, and can be used more convieniently. |
---|---|
Parameters: |
|
Returns the set of ‘status’ classifications, which are those that tend to change during the reduction of a dataset based on the amount of processing, e.g. RAW vs PREPARED. Strictly, a ‘status’ type is any type defined in or below the status part of the ‘classification’ directory within the configuration package. For example, in the Gemini type configuration this means any type definition files in or below the ‘astrodata_Gemini/ADCONFIG/classification/status’ directory.
Parameters: | prune (<bool>) – flag which controls ‘pruning’ the returned type list so that only the leaf node type for a given set of related status types is returned. |
---|---|
Returns: | list of classification names |
Return type: | <list> of strings |
Method adds the key ‘ORIGNAME’ to PHU of an astrodata object containing the filename when object was instantiated (without any directory info, ie. the basename).
If key has all ready been added (ie. has undergone processing where store_original_name was performed before), then the value original filename is just returned. If the key is there, but does not match the original filename of the object, then the original name is returned, NOT the value in the PHU. The value in the PHU can always be found using ad.phu_get_key_value(‘ORIGNAME’).
Returns a list of type classifications. It is possible to ‘prune’ the list so that only leaf nodes are returned, which is useful when leaf nodes take precedence such as for descriptors.
Note: types consist of a hierarchical tree of dataset types. This latter tree maps roughly to instrument-modes, with instrument types branching from the general observatory type, (e.g. ‘GEMINI’).
Currently the distinction betwen status and type is not used by the system (e.g. in type-specific default recipe assignments) and is provided as a service for higher level code, e.g. primitives and scripts which make use of the distinction.
Parameters: | prune (<bool>) – flag which controls ‘pruning’ the returned type list so that only the leaf node type for a given set of related types is returned. |
---|---|
Returns: | list of classification names |
Return type: | <list> of strings |
The write method acts similarly to the ‘pyfits HDUList.writeto(..)’ function if a filename is given, or like ‘pyfits.HDUList.update(..)’ if no name is given, using whatever the current name is set to. When a name is given, this becomes the new name of the AstroData object and will be used on subsequent calls to write for which a filename is not provided. If the clobber flag is False (the default) then ‘write(..)’ throws an exception if the file already exists.
Parameters: |
|
---|