PrimaryHDU
¶
-
class
astropy.io.fits.
PrimaryHDU
(data=None, header=None, do_not_scale_image_data=False, ignore_blank=False, uint=True, scale_back=None)[source] [edit on github]¶ Bases:
astropy.io.fits.hdu.image._ImageBaseHDU
FITS primary HDU class.
Construct a primary HDU.
Parameters: - data : array or DELAYED, optional
The data in the HDU.
- header : Header instance, optional
The header to be used (as a template). If
header
isNone
, a minimal header will be provided.- do_not_scale_image_data : bool, optional
If
True
, image data is not scaled using BSCALE/BZERO values when read. (default: False)- ignore_blank : bool, optional
If
True
, the BLANK header keyword will be ignored if present. Otherwise, pixels equal to this value will be replaced with NaNs. (default: False)- uint : bool, optional
Interpret signed integer data where
BZERO
is the central value andBSCALE == 1
as unsigned integer data. For example,int16
data withBZERO = 32768
andBSCALE = 1
would be treated asuint16
data. (default: True)- scale_back : bool, optional
If
True
, when saving changes to a file that contained scaled image data, restore the data to the original type and reapply the original BSCALE/BZERO values. This could lead to loss of accuracy if scaling back to integer values after performing floating point operations on the data. Pseudo-unsigned integers are automatically rescaled unless scale_back is explicitly set toFalse
. (default: None)
-
add_checksum
(when=None, override_datasum=False, checksum_keyword='CHECKSUM', datasum_keyword='DATASUM') [edit on github]¶ Add the
CHECKSUM
andDATASUM
cards to this HDU with the values set to the checksum calculated for the HDU and the data respectively. The addition of theDATASUM
card may be overridden.Parameters: - when : str, optional
comment string for the cards; by default the comments will represent the time when the checksum was calculated
- override_datasum : bool, optional
add the
CHECKSUM
card only- checksum_keyword : str, optional
The name of the header keyword to store the checksum value in; this is typically ‘CHECKSUM’ per convention, but there exist use cases in which a different keyword should be used
- datasum_keyword : str, optional
See
checksum_keyword
Notes
For testing purposes, first call
add_datasum
with awhen
argument, then calladd_checksum
with awhen
argument andoverride_datasum
set toTrue
. This will provide consistent comments for both cards and enable the generation of aCHECKSUM
card with a consistent value.
-
add_datasum
(when=None, datasum_keyword='DATASUM') [edit on github]¶ Add the
DATASUM
card to this HDU with the value set to the checksum calculated for the data.Parameters: - when : str, optional
Comment string for the card that by default represents the time when the checksum was calculated
- datasum_keyword : str, optional
The name of the header keyword to store the datasum value in; this is typically ‘DATASUM’ per convention, but there exist use cases in which a different keyword should be used
Returns: - checksum : int
The calculated datasum
Notes
For testing purposes, provide a
when
argument to enable the comment value in the card to remain consistent. This will enable the generation of aCHECKSUM
card with a consistent value.
-
copy
() [edit on github]¶ Make a copy of the HDU, both header and data are copied.
-
data
¶ Image/array data as a
ndarray
.Please remember that the order of axes on an Numpy array are opposite of the order specified in the FITS file. For example for a 2D image the “rows” or y-axis are the first dimension, and the “columns” or x-axis are the second dimension.
If the data is scaled using the BZERO and BSCALE parameters, this attribute returns the data scaled to its physical values unless the file was opened with
do_not_scale_image_data=True
.
-
filebytes
() [edit on github]¶ Calculates and returns the number of bytes that this HDU will write to a file.
-
fileinfo
() [edit on github]¶ Returns a dictionary detailing information about the locations of this HDU within any associated file. The values are only valid after a read or write of the associated file with no intervening changes to the
HDUList
.Returns: - dict or None
The dictionary details information about the locations of this HDU within an associated file. Returns
None
when the HDU is not associated with a file.Dictionary contents:
Key Value file File object associated with the HDU filemode Mode in which the file was opened (readonly, copyonwrite, update, append, ostream) hdrLoc Starting byte location of header in file datLoc Starting byte location of data block in file datSpan Data size including padding
-
classmethod
fromstring
(data, checksum=False, ignore_missing_end=False, **kwargs) [edit on github]¶ Creates a new HDU object of the appropriate type from a string containing the HDU’s entire header and, optionally, its data.
Note: When creating a new HDU from a string without a backing file object, the data of that HDU may be read-only. It depends on whether the underlying string was an immutable Python str/bytes object, or some kind of read-write memory buffer such as a
memoryview
.Parameters: - data : str, bytearray, memoryview, ndarray
A byte string containing the HDU’s header and data.
- checksum : bool, optional
Check the HDU’s checksum and/or datasum.
- ignore_missing_end : bool, optional
Ignore a missing end card in the header data. Note that without the end card the end of the header may be ambiguous and resulted in a corrupt HDU. In this case the assumption is that the first 2880 block that does not begin with valid FITS header data is the beginning of the data.
- kwargs : optional
May consist of additional keyword arguments specific to an HDU type–these correspond to keywords recognized by the constructors of different HDU classes such as
PrimaryHDU
,ImageHDU
, orBinTableHDU
. Any unrecognized keyword arguments are simply ignored.
-
classmethod
match_header
(header)[source] [edit on github]¶ _ImageBaseHDU is sort of an abstract class for HDUs containing image data (as opposed to table data) and should never be used directly.
-
classmethod
readfrom
(fileobj, checksum=False, ignore_missing_end=False, **kwargs) [edit on github]¶ Read the HDU from a file. Normally an HDU should be opened with
open()
which reads the entire HDU list in a FITS file. But this method is still provided for symmetry withwriteto()
.Parameters: - fileobj : file object or file-like object
Input FITS file. The file’s seek pointer is assumed to be at the beginning of the HDU.
- checksum : bool
If
True
, verifies that bothDATASUM
andCHECKSUM
card values (when present in the HDU header) match the header and data of all HDU’s in the file.- ignore_missing_end : bool
Do not issue an exception when opening a file that is missing an
END
card in the last header.
-
req_cards
(keyword, pos, test, fix_value, option, errlist) [edit on github]¶ Check the existence, location, and value of a required
Card
.Parameters: - keyword : str
The keyword to validate
- pos : int, callable
If an
int
, this specifies the exact location this card should have in the header. Remember that Python is zero-indexed, so this meanspos=0
requires the card to be the first card in the header. If given a callable, it should take one argument–the actual position of the keyword–and returnTrue
orFalse
. This can be used for custom evaluation. For example ifpos=lambda idx: idx > 10
this will check that the keyword’s index is greater than 10.- test : callable
This should be a callable (generally a function) that is passed the value of the given keyword and returns
True
orFalse
. This can be used to validate the value associated with the given keyword.- fix_value : str, int, float, complex, bool, None
A valid value for a FITS keyword to to use if the given
test
fails to replace an invalid value. In other words, this provides a default value to use as a replacement if the keyword’s current value is invalid. IfNone
, there is no replacement value and the keyword is unfixable.- option : str
Output verification option. Must be one of
"fix"
,"silentfix"
,"ignore"
,"warn"
, or"exception"
. May also be any combination of"fix"
or"silentfix"
with"+ignore"
,+warn
, or+exception" (e.g. ``"fix+warn"
). See Verification options for more info.- errlist : list
A list of validation errors already found in the FITS file; this is used primarily for the validation system to collect errors across multiple HDUs and multiple calls to
req_cards
.
Notes
If
pos=None
, the card can be anywhere in the header. If the card does not exist, the new card will have thefix_value
as its value when created. Also check the card’s value by using thetest
argument.
-
run_option
(option='warn', err_text='', fix_text='Fixed.', fix=None, fixable=True) [edit on github]¶ Execute the verification with selected option.
-
scale
(type=None, option='old', bscale=None, bzero=None) [edit on github]¶ Scale image data by using
BSCALE
/BZERO
.Call to this method will scale
data
and update the keywords ofBSCALE
andBZERO
in the HDU’s header. This method should only be used right before writing to the output file, as the data will be scaled and is therefore not very usable after the call.Parameters: - type : str, optional
destination data type, use a string representing a numpy dtype name, (e.g.
'uint8'
,'int16'
,'float32'
etc.). If isNone
, use the current data type.- option : str, optional
How to scale the data:
"old"
uses the originalBSCALE
andBZERO
values from when the data was read/created (defaulting to 1 and 0 if they don’t exist). For integer data only,"minmax"
uses the minimum and maximum of the data to scale. User-specifiedbscale
/bzero
values always take precedence.- bscale, bzero : int, optional
User-specified
BSCALE
andBZERO
values
-
section
¶ Access a section of the image array without loading the entire array into memory. The
Section
object returned by this attribute is not meant to be used directly by itself. Rather, slices of the section return the appropriate slice of the data, and loads only that section into memory.Sections are mostly obsoleted by memmap support, but should still be used to deal with very large scaled images. See the Data Sections section of the Astropy documentation for more details.
-
shape
¶ Shape of the image array–should be equivalent to
self.data.shape
.
-
size
¶ Size (in bytes) of the data portion of the HDU.
-
update_header
()[source] [edit on github]¶ Update the header keywords to agree with the data.
-
verify
(option='warn') [edit on github]¶ Verify all values in the instance.
Parameters: - option : str
Output verification option. Must be one of
"fix"
,"silentfix"
,"ignore"
,"warn"
, or"exception"
. May also be any combination of"fix"
or"silentfix"
with"+ignore"
,+warn
, or+exception" (e.g. ``"fix+warn"
). See Verification options for more info.
-
verify_checksum
() [edit on github]¶ Verify that the value in the
CHECKSUM
keyword matches the value calculated for the current HDU CHECKSUM.Returns: - valid : int
- 0 - failure
- 1 - success
- 2 - no
CHECKSUM
keyword present
-
verify_datasum
() [edit on github]¶ Verify that the value in the
DATASUM
keyword matches the value calculated for theDATASUM
of the current HDU data.Returns: - valid : int
- 0 - failure
- 1 - success
- 2 - no
DATASUM
keyword present
-
writeto
(name, output_verify='exception', overwrite=False, checksum=False) [edit on github]¶ Write the HDU to a new file. This is a convenience method to provide a user easier output interface if only one HDU needs to be written to a file.
Parameters: - name : file path, file object or file-like object
Output FITS file. If the file object is already opened, it must be opened in a writeable mode.
- output_verify : str
Output verification option. Must be one of
"fix"
,"silentfix"
,"ignore"
,"warn"
, or"exception"
. May also be any combination of"fix"
or"silentfix"
with"+ignore"
,+warn
, or+exception" (e.g. ``"fix+warn"
). See Verification options for more info.- overwrite : bool, optional
If
True
, overwrite the output file if it exists. Raises anOSError
ifFalse
and the output file exists. Default isFalse
.Changed in version 1.3:
overwrite
replaces the deprecatedclobber
argument.- checksum : bool
When
True
adds bothDATASUM
andCHECKSUM
cards to the header of the HDU when written to the file.