FitsRawFormatterBase¶

class lsst.obs.base.FitsRawFormatterBase(*args, **kwargs)¶

Bases: lsst.obs.base.formatters.fitsExposure.FitsImageFormatterBase

Abstract base class for reading and writing raw data to and from FITS files.

Attributes Summary

`dataId`	Return Data ID associated with this formatter (`DataCoordinate`).
`extension`
`fileDescriptor`	File descriptor associated with this formatter (`FileDescriptor`).
`filterDefinitions`	`FilterDefinitions`, defining the filters for this instrument.
`metadata`	The metadata read from this file.
`observationInfo`	The `ObservationInfo` extracted from this file’s metadata (`ObservationInfo`, read-only).
`supportedExtensions`	Set of all extensions supported by this formatter.
`supportedWriteParameters`	Parameters understood by this formatter that can be used to control how a dataset is serialized.
`translatorClass`	`MetadataTranslator` to translate metadata header to `ObservationInfo`.
`unsupportedParameters`	Support all parameters.
`wcsFlipX`	Control whether the WCS is flipped in the X-direction (`bool`)
`writeParameters`	Parameters to use when writing out datasets.
`writeRecipes`	Detailed write Recipes indexed by recipe name.

Methods Summary

`can_read_bytes`()	Indicate if this formatter can format from bytes.
`fromBytes`(serializedDataset[, component])	Read serialized data into a Dataset or its component.
`fromMetadata`(metadata[, obsInfo, …])	Construct a possibly-limited formatter from known metadata.
`getDetector`(id)	Return the detector that acquired this raw exposure.
`getImageCompressionSettings`(recipeName)	Retrieve the relevant compression settings for this recipe.
`isOnSky`()	Boolean to determine if the exposure is thought to be on the sky.
`makeFilter`()	Construct a Filter from metadata.
`makeFilterLabel`()	Construct a FilterLabel from metadata.
`makeRawSkyWcsFromBoresight`(boresight, …)	Class method to make a raw sky WCS from boresight and detector.
`makeUpdatedLocation`(location)	Return a new `Location` updated with this formatter’s extension.
`makeVisitInfo`()	Construct a VisitInfo from metadata.
`makeWcs`(visitInfo, detector)	Create a SkyWcs from information about the exposure.
`name`()	Return the fully qualified name of the formatter.
`predictPath`()	Return the path that would be returned by write.
`read`([component])	Read data from a file.
`readComponent`(component[, parameters])	Read a component held by the Exposure.
`readFull`([parameters])	Read the full Exposure object.
`readImage`()	Read just the image component of the Exposure.
`readMask`()	Read just the mask component of the Exposure.
`readMetadata`()	Read all header metadata directly into a PropertyList.
`readRawHeaderWcs`([parameters])	Read the SkyWcs stored in the un-modified raw FITS WCS header keys.
`readVariance`()	Read just the variance component of the Exposure.
`segregateParameters`([parameters])	Segregate the supplied parameters.
`stripMetadata`()	Remove metadata entries that are parsed into components.
`toBytes`(inMemoryDataset)	Serialize the Dataset to bytes based on formatter.
`validateExtension`(location)	Check the extension of the provided location for compatibility.
`validateWriteRecipes`(recipes)	Validate supplied recipes for this formatter.
`write`(inMemoryDataset)	Write a Python object to a file.

Attributes Documentation

dataId¶: Return Data ID associated with this formatter (DataCoordinate).

extension = '.fits'¶

fileDescriptor¶

File descriptor associated with this formatter (FileDescriptor).

Read-only property.

filterDefinitions¶: FilterDefinitions, defining the filters for this instrument.

metadata¶: The metadata read from this file. It will be stripped as components are extracted from it (lsst.daf.base.PropertyList).

observationInfo¶: The ObservationInfo extracted from this file’s metadata (ObservationInfo, read-only).

supportedExtensions: ClassVar[AbstractSet[str]] = frozenset({'.fit', '.fits', '.fits.fz', '.fits.gz', '.fz'})¶

Set of all extensions supported by this formatter.

Only expected to be populated by Formatters that write files. Any extension assigned to the extension property will be automatically included in the list of supported extensions.

supportedWriteParameters: ClassVar[Optional[AbstractSet[str]]] = frozenset({'recipe'})¶: Parameters understood by this formatter that can be used to control how a dataset is serialized. None indicates that no parameters are supported.

translatorClass¶: MetadataTranslator to translate metadata header to ObservationInfo.

unsupportedParameters: ClassVar[Optional[AbstractSet[str]]] = {}¶: Support all parameters.

wcsFlipX = False¶: Control whether the WCS is flipped in the X-direction (bool)

writeParameters¶: Parameters to use when writing out datasets.

writeRecipes¶: Detailed write Recipes indexed by recipe name.

Methods Documentation

classmethod can_read_bytes() → bool ¶

Indicate if this formatter can format from bytes.

Returns

canbool: True if the fromBytes method is implemented.

fromBytes(serializedDataset: bytes, component: Optional[str] = None) → object ¶

Read serialized data into a Dataset or its component.

Parameters

serializedDatasetbytes: Bytes object to unserialize.
componentstr, optional: Component to read from the Dataset. Only used if the StorageClass for reading differed from the StorageClass used to write the file.

Returns

inMemoryDatasetobject: The requested data as a Python object. The type of object is controlled by the specific formatter.

classmethod fromMetadata(metadata, obsInfo=None, storageClass=None, location=None)¶

Construct a possibly-limited formatter from known metadata.

Parameters

metadatalsst.daf.base.PropertyList: Raw header metadata, with any fixes (see astro_metadata_translator.fix_header) applied but nothing stripped.
obsInfoastro_metadata_translator.ObservationInfo, optional: Structured information already extracted from metadata. If not provided, will be read from metadata on first use.
storageClasslsst.daf.butler.StorageClass, optional: StorageClass for this file. If not provided, the formatter will only support makeWcs, makeVisitInfo, makeFilter, and other operations that operate purely on metadata and not the actual file.
locationlsst.daf.butler.Location, optional.: Location of the file. If not provided, the formatter will only support makeWcs, makeVisitInfo, makeFilter, and other operations that operate purely on metadata and not the actual file.

Returns

formatterFitsRawFormatterBase: An instance of cls.

abstract getDetector(id)¶

Return the detector that acquired this raw exposure.

Parameters

idint: The identifying number of the detector to get.

Returns

detectorDetector: The detector associated with that id.

getImageCompressionSettings(recipeName)¶

Retrieve the relevant compression settings for this recipe.

Parameters

recipeNamestr: Label associated with the collection of compression parameters to select.

Returns

settingsdict: The selected settings.

isOnSky()¶

Boolean to determine if the exposure is thought to be on the sky.

Returns

onSkybool: Returns True if the observation looks like it was taken on the sky. Returns False if this observation looks like a calibration observation.

Notes

If there is tracking RA/Dec information associated with the observation it is assumed that the observation is on sky. Currently the observation type is not checked.

makeFilter()¶

Construct a Filter from metadata.

Returns

filterFilter: Object that identifies the filter for this image.

Raises

NotFoundError: Raised if the physical filter was not registered via defineFilter.

Deprecated since version v22: Replaced with makeFilterLabel. Will be removed after v22.

makeFilterLabel()¶

Construct a FilterLabel from metadata.

Returns

filterFilterLabel: Object that identifies the filter for this image.

classmethod makeRawSkyWcsFromBoresight(boresight, orientation, detector)¶

Class method to make a raw sky WCS from boresight and detector.

Parameters

boresightlsst.geom.SpherePoint: The ICRS boresight RA/Dec
orientationlsst.geom.Angle: The rotation angle of the focal plane on the sky.
detectorlsst.afw.cameraGeom.Detector: Where to get the camera geomtry from.

Returns

skyWcsSkyWcs: Reversible mapping from pixel coordinates to sky coordinates.

makeUpdatedLocation(location: lsst.daf.butler.Location) → lsst.daf.butler.Location¶

Return a new Location updated with this formatter’s extension.

Parameters

locationLocation: The location to update.

Returns

updatedLocation: A new Location with a new file extension applied.

Raises

NotImplementedError: Raised if there is no extension attribute associated with this formatter.

Notes

This method is available to all Formatters but might not be implemented by all formatters. It requires that a formatter set an extension attribute containing the file extension used when writing files. If extension is None the supplied file will not be updated. Not all formatters write files so this is not defined in the base class.

makeVisitInfo()¶

Construct a VisitInfo from metadata.

Returns

visitInfoVisitInfo: Structured metadata about the observation.

makeWcs(visitInfo, detector)¶

Create a SkyWcs from information about the exposure.

If VisitInfo is not None, use it and the detector to create a SkyWcs, otherwise return the metadata-based SkyWcs (always created, so that the relevant metadata keywords are stripped).

Parameters

visitInfoVisitInfo: The information about the telescope boresight and camera orientation angle for this exposure.
detectorDetector: The detector used to acquire this exposure.

Returns

skyWcsSkyWcs: Reversible mapping from pixel coordinates to sky coordinates.

Raises

InitialSkyWcsError: Raised if there is an error generating the SkyWcs, chained from the lower-level exception if available.

classmethod name() → str ¶

Return the fully qualified name of the formatter.

Returns

namestr: Fully-qualified name of formatter class.

predictPath() → str ¶

Return the path that would be returned by write.

Does not write any data file.

Uses the FileDescriptor associated with the instance.

Returns

pathstr: Path within datastore that would be associated with the location stored in this Formatter.

read(component=None)¶

Read data from a file.

Parameters

componentstr, optional: Component to read from the file. Only used if the StorageClass for reading differed from the StorageClass used to write the file.

Returns

inMemoryDatasetobject: The requested data as a Python object. The type of object is controlled by the specific formatter.

Raises

ValueError: Component requested but this file does not seem to be a concrete composite.
KeyError: Raised when parameters passed with fileDescriptor are not supported.

readComponent(component, parameters=None)¶

Read a component held by the Exposure.

Parameters

componentstr, optional: Component to read from the file.
parametersdict, optional: If specified, a dictionary of slicing parameters that overrides those in fileDescriptor.

Returns

objcomponent-dependent: In-memory component object.

Raises

KeyError: Raised if the requested component cannot be handled.

readFull(parameters=None)¶

Read the full Exposure object.

Parameters

parametersdict, optional: If specified, a dictionary of slicing parameters that overrides those in the fileDescriptor attribute.

Returns

exposureExposure: Complete in-memory exposure.

readImage()¶

Read just the image component of the Exposure.

Returns

imageImage: In-memory image component.

readMask()¶

Read just the mask component of the Exposure.

May return None (as the default implementation does) to indicate that there is no mask information to be extracted (at least not trivially) from the raw data. This will prohibit direct reading of just the mask, and set the mask of the full Exposure to zeros.

Returns

maskMask: In-memory mask component.

readMetadata()¶

Read all header metadata directly into a PropertyList.

Returns

metadataPropertyList: Header metadata.

readRawHeaderWcs(parameters=None)¶: Read the SkyWcs stored in the un-modified raw FITS WCS header keys.

readVariance()¶

Read just the variance component of the Exposure.

May return None (as the default implementation does) to indicate that there is no variance information to be extracted (at least not trivially) from the raw data. This will prohibit direct reading of just the variance, and set the variance of the full Exposure to zeros.

Returns

imageImage: In-memory variance component.

segregateParameters(parameters: Optional[Dict[str, Any]] = None) → Tuple[Dict, Dict]¶

Segregate the supplied parameters.

This splits the parameters into those understood by the formatter and those not understood by the formatter.

Any unsupported parameters are assumed to be usable by associated assemblers.

Parameters

parametersdict, optional: Parameters with values that have been supplied by the caller and which might be relevant for the formatter. If None parameters will be read from the registered FileDescriptor.

Returns

supporteddict: Those parameters supported by this formatter.
unsupporteddict: Those parameters not supported by this formatter.

stripMetadata()¶: Remove metadata entries that are parsed into components.

toBytes(inMemoryDataset: Any) → bytes ¶

Serialize the Dataset to bytes based on formatter.

Parameters

inMemoryDatasetobject: The Python object to serialize.

Returns

serializedDatasetbytes: Bytes representing the serialized dataset.

classmethod validateExtension(location: lsst.daf.butler.Location) → None ¶

Check the extension of the provided location for compatibility.

Parameters

locationLocation: Location from which to extract a file extension.

Raises

NotImplementedError: Raised if file extensions are a concept not understood by this formatter.
ValueError: Raised if the formatter does not understand this extension.

Notes

This method is available to all Formatters but might not be implemented by all formatters. It requires that a formatter set an extension attribute containing the file extension used when writing files. If extension is None only the set of supported extensions will be examined.

classmethod validateWriteRecipes(recipes)¶

Validate supplied recipes for this formatter.

The recipes are supplemented with default values where appropriate.

TODO: replace this custom validation code with Cerberus (DM-11846)

Parameters

recipesdict: Recipes to validate. Can be empty dict or None.

Returns

validateddict: Validated recipes. Returns what was given if there are no recipes listed.

Raises

RuntimeError: Raised if validation fails.

write(inMemoryDataset)¶

Write a Python object to a file.

Parameters

inMemoryDatasetobject: The Python object to store.

Returns

pathstr: The URI where the primary file is stored.

Navigation

FitsRawFormatterBase¶