Skip to main content
`Ctrl`+`K`

The `relax` keyword argument controls the handling of non-standard FITS WCS keywords.

Note that the default value of `relax` is `True` for reading (to accept all non standard keywords), and `False` for writing (to write out only standard keywords), in accordance with Postel’s prescription:

> “Be liberal in what you accept, and conservative in what you send.”

# Header-reading relaxation constants

`WCS`, `Wcsprm` and `find_all_wcs` have a relax argument, which may be either `True`, `False` or an `int`.

- If `True`, (default), all non-standard WCS extensions recognized by the parser will be handled.

- If `False`, none of the extensions (even those in the errata) will be handled. Non-conformant keywords will be handled in the same way as non-WCS keywords in the header, i.e. by simply ignoring them.

- If an `int`, is is a bit field to provide fine-grained control over what non-standard WCS keywords to accept. The flag bits are subject to change in future and should be set by using the constants beginning with `WCSHDR_` in the `astropy.wcs` module.

  For example, to accept `CD00i00j` and `PC00i00j` use:

      relax = astropy.wcs.WCSHDR_CD00i00j | astropy.wcs.WCSHDR_PC00i00j

  The parser always treats `EPOCH` as subordinate to `EQUINOXa` if both are present, and `VSOURCEa` is always subordinate to `ZSOURCEa`.

  Likewise, `VELREF` is subordinate to the formalism of WCS Paper III.

The flag bits are:

- `WCSHDR_none`: Don’t accept any extensions (not even those in the errata). Treat non-conformant keywords in the same way as non-WCS keywords in the header, i.e. simply ignore them. (This is equivalent to passing `False`)

- `WCSHDR_all`: Accept all extensions recognized by the parser. (This is equivalent to the default behavior or passing `True`).

- `WCSHDR_reject`: Reject non-standard keyrecords (that are not otherwise explicitly accepted by one of the flags below). A warning will be displayed by default.

  This flag may be used to signal the presence of non-standard keywords, otherwise they are simply passed over as though they did not exist in the header. It is mainly intended for testing conformance of a FITS header to the WCS standard.

  Keyrecords may be non-standard in several ways:

  - The keyword may be syntactically valid but with keyvalue of incorrect type or invalid syntax, or the keycomment may be malformed.

  - The keyword may strongly resemble a WCS keyword but not, in fact, be one because it does not conform to the standard. For example, `CRPIX01` looks like a `CRPIXja` keyword, but in fact the leading zero on the axis number violates the basic FITS standard. Likewise, `LONPOLE2` is not a valid `LONPOLEa` keyword in the WCS standard, and indeed there is nothing the parser can sensibly do with it.

  - Use of the keyword may be deprecated by the standard. Such will be rejected if not explicitly accepted via one of the flags below.

- `WCSHDR_CROTAia`: Accept `CROTAia`, `iCROTna`, `TCROTna`

- `WCSHDR_EPOCHa`: Accept `EPOCHa`.

- `WCSHDR_VELREFa`: Accept `VELREFa`.

  > The constructor always recognizes the AIPS-convention keywords, `CROTAn`, `EPOCH`, and `VELREF` for the primary representation `(a = ' ')` but alternates are non-standard.

  > The constructor accepts `EPOCHa` and `VELREFa` only if `WCSHDR_AUXIMG` is also enabled.

- `WCSHDR_CD00i00j`: Accept `CD00i00j`.

- `WCSHDR_PC00i00j`: Accept `PC00i00j`.

- `WCSHDR_PROJPn`: Accept `PROJPn`.

  > These appeared in early drafts of WCS Paper I+II (before they were split) and are equivalent to `CDi_ja`, `PCi_ja`, and `PVi_ma` for the primary representation `(a = ' ')`. `PROJPn` is equivalent to `PVi_ma` with `m` = `n` <= 9, and is associated exclusively with the latitude axis.

- `WCSHDR_CD0i_0ja`: Accept `CD0i_0ja` (wcspih()).

- `WCSHDR_PC0i_0ja`: Accept `PC0i_0ja` (wcspih()).

- `WCSHDR_PV0i_0ma`: Accept `PV0i_0ja` (wcspih()).

- `WCSHDR_PS0i_0ma`: Accept `PS0i_0ja` (wcspih()).

  > Allow the numerical index to have a leading zero in doubly-parameterized keywords, for example, `PC01_01`. WCS Paper I (Sects 2.1.2 & 2.1.4) explicitly disallows leading zeroes. The FITS 3.0 standard document (Sect. 4.1.2.1) states that the index in singly-parameterized keywords (e.g. `CTYPEia`) “shall not have leading zeroes”, and later in Sect. 8.1 that “leading zeroes must not be used” on `PVi_ma` and `PSi_ma`. However, by an oversight, it is silent on `PCi_ja` and `CDi_ja`.

  > Only available if built with wcslib 5.0 or later.

- `WCSHDR_RADECSYS`: Accept `RADECSYS`. This appeared in early drafts of WCS Paper I+II and was subsequently replaced by `RADESYSa`. The constructor accepts `RADECSYS` only if `WCSHDR_AUXIMG` is also enabled.

- `WCSHDR_VSOURCE`: Accept `VSOURCEa` or `VSOUna`. This appeared in early drafts of WCS Paper III and was subsequently dropped in favor of `ZSOURCEa` and `ZSOUna`. The constructor accepts `VSOURCEa` only if `WCSHDR_AUXIMG` is also enabled.

- `WCSHDR_DOBSn`: Allow `DOBSn`, the column-specific analogue of `DATE-OBS`. By an oversight this was never formally defined in the standard.

- `WCSHDR_LONGKEY`: Accept long forms of the alternate binary table and pixel list WCS keywords, i.e. with “a” non- blank. Specifically:

      jCRPXna  TCRPXna  :  jCRPXn  jCRPna  TCRPXn  TCRPna  CRPIXja
         -     TPCn_ka  :    -     ijPCna    -     TPn_ka  PCi_ja
         -     TCDn_ka  :    -     ijCDna    -     TCn_ka  CDi_ja
      iCDLTna  TCDLTna  :  iCDLTn  iCDEna  TCDLTn  TCDEna  CDELTia
      iCUNIna  TCUNIna  :  iCUNIn  iCUNna  TCUNIn  TCUNna  CUNITia
      iCTYPna  TCTYPna  :  iCTYPn  iCTYna  TCTYPn  TCTYna  CTYPEia
      iCRVLna  TCRVLna  :  iCRVLn  iCRVna  TCRVLn  TCRVna  CRVALia
      iPVn_ma  TPVn_ma  :    -     iVn_ma    -     TVn_ma  PVi_ma
      iPSn_ma  TPSn_ma  :    -     iSn_ma    -     TSn_ma  PSi_ma

  where the primary and standard alternate forms together with the image-header equivalent are shown rightwards of the colon.

  The long form of these keywords could be described as quasi-standard. `TPCn_ka`, `iPVn_ma`, and `TPVn_ma` appeared by mistake in the examples in WCS Paper II and subsequently these and also `TCDn_ka`, `iPSn_ma` and `TPSn_ma` were legitimized by the errata to the WCS papers.

  Strictly speaking, the other long forms are non-standard and in fact have never appeared in any draft of the WCS papers nor in the errata. However, as natural extensions of the primary form they are unlikely to be written with any other intention. Thus it should be safe to accept them provided, of course, that the resulting keyword does not exceed the 8-character limit.

  If `WCSHDR_CNAMn` is enabled then also accept:

      iCNAMna  TCNAMna  :   ---   iCNAna    ---   TCNAna  CNAMEia
      iCRDEna  TCRDEna  :   ---   iCRDna    ---   TCRDna  CRDERia
      iCSYEna  TCSYEna  :   ---   iCSYna    ---   TCSYna  CSYERia

  Note that `CNAMEia`, `CRDERia`, `CSYERia`, and their variants are not used by `astropy.wcs` but are stored as auxiliary information.

- `WCSHDR_CNAMn`: Accept `iCNAMn`, `iCRDEn`, `iCSYEn`, `TCNAMn`, `TCRDEn`, and `TCSYEn`, i.e. with `a` blank. While non-standard, these are the analogues of `iCTYPn`, `TCTYPn`, etc.

- `WCSHDR_AUXIMG`: Allow the image-header form of an auxiliary WCS keyword with representation-wide scope to provide a default value for all images. This default may be overridden by the column-specific form of the keyword.

  For example, a keyword like `EQUINOXa` would apply to all image arrays in a binary table, or all pixel list columns with alternate representation `a` unless overridden by `EQUIna`.

  Specifically the keywords are:

      LATPOLEa  for LATPna
      LONPOLEa  for LONPna
      RESTFREQ  for RFRQna
      RESTFRQa  for RFRQna
      RESTWAVa  for RWAVna

  whose keyvalues are actually used by WCSLIB, and also keywords that provide auxiliary information that is simply stored in the wcsprm struct:

      EPOCH         -       ... (No column-specific form.)
      EPOCHa        -       ... Only if WCSHDR_EPOCHa is set.
      EQUINOXa  for EQUIna
      RADESYSa  for RADEna
      RADECSYS  for RADEna  ... Only if WCSHDR_RADECSYS is set.
      SPECSYSa  for SPECna
      SSYSOBSa  for SOBSna
      SSYSSRCa  for SSRCna
      VELOSYSa  for VSYSna
      VELANGLa  for VANGna
      VELREF        -       ... (No column-specific form.)
      VELREFa       -       ... Only if WCSHDR_VELREFa is set.
      VSOURCEa  for VSOUna  ... Only if WCSHDR_VSOURCE is set.
      WCSNAMEa  for WCSNna  ... Or TWCSna (see below).
      ZSOURCEa  for ZSOUna

      DATE-AVG  for DAVGn
      DATE-OBS  for DOBSn
      MJD-AVG   for MJDAn
      MJD-OBS   for MJDOBn
      OBSGEO-X  for OBSGXn
      OBSGEO-Y  for OBSGYn
      OBSGEO-Z  for OBSGZn

  where the image-header keywords on the left provide default values for the column specific keywords on the right.

  Keywords in the last group, such as `MJD-OBS`, apply to all alternate representations, so `MJD-OBS` would provide a default value for all images in the header.

  This auxiliary inheritance mechanism applies to binary table image arrays and pixel lists alike. Most of these keywords have no default value, the exceptions being `LONPOLEa` and `LATPOLEa`, and also `RADESYSa` and `EQUINOXa` which provide defaults for each other. Thus the only potential difficulty in using `WCSHDR_AUXIMG` is that of erroneously inheriting one of these four keywords.

  Unlike `WCSHDR_ALLIMG`, the existence of one (or all) of these auxiliary WCS image header keywords will not by itself cause a `Wcsprm` object to be created for alternate representation `a`. This is because they do not provide sufficient information to create a non-trivial coordinate representation when used in conjunction with the default values of those keywords, such as `CTYPEia`, that are parameterized by axis number.

- `WCSHDR_ALLIMG`: Allow the image-header form of all image header WCS keywords to provide a default value for all image arrays in a binary table (n.b. not pixel list). This default may be overridden by the column-specific form of the keyword.

  For example, a keyword like `CRPIXja` would apply to all image arrays in a binary table with alternate representation `a` unless overridden by `jCRPna`.

  Specifically the keywords are those listed above for `WCSHDR_AUXIMG` plus:

      WCSAXESa  for WCAXna

  which defines the coordinate dimensionality, and the following keywords which are parameterized by axis number:

      CRPIXja   for jCRPna
      PCi_ja    for ijPCna
      CDi_ja    for ijCDna
      CDELTia   for iCDEna
      CROTAi    for iCROTn
      CROTAia        -      ... Only if WCSHDR_CROTAia is set.
      CUNITia   for iCUNna
      CTYPEia   for iCTYna
      CRVALia   for iCRVna
      PVi_ma    for iVn_ma
      PSi_ma    for iSn_ma

      CNAMEia   for iCNAna
      CRDERia   for iCRDna
      CSYERia   for iCSYna

  where the image-header keywords on the left provide default values for the column specific keywords on the right.

  This full inheritance mechanism only applies to binary table image arrays, not pixel lists, because in the latter case there is no well-defined association between coordinate axis number and column number.

  Note that `CNAMEia`, `CRDERia`, `CSYERia`, and their variants are not used by pywcs but are stored in the `Wcsprm` object as auxiliary information.

  Note especially that at least one `Wcsprm` object will be returned for each `a` found in one of the image header keywords listed above:

  > - If the image header keywords for `a` are not inherited by a binary table, then the struct will not be associated with any particular table column number and it is up to the user to provide an association.

  > - If the image header keywords for `a` are inherited by a binary table image array, then those keywords are considered to be “exhausted” and do not result in a separate `Wcsprm` object.

# Header-writing relaxation constants

`to_header` and `to_header_string` has a relax argument which may be either `True`, `False` or an `int`.

- If `True`, write all recognized extensions.

- If `False` (default), write all extensions that are considered to be safe and recommended, equivalent to `WCSHDO_safe` (described below).

- If an `int`, is is a bit field to provide fine-grained control over what non-standard WCS keywords to accept. The flag bits are subject to change in future and should be set by using the constants beginning with `WCSHDO_` in the `astropy.wcs` module.

The flag bits are:

- `WCSHDO_none`: Don’t use any extensions.

- `WCSHDO_all`: Write all recognized extensions, equivalent to setting each flag bit.

- `WCSHDO_safe`: Write all extensions that are considered to be safe and recommended.

- `WCSHDO_DOBSn`: Write `DOBSn`, the column-specific analogue of `DATE-OBS` for use in binary tables and pixel lists. WCS Paper III introduced `DATE-AVG` and `DAVGn` but by an oversight `DOBSn` was never formally defined by the standard. The alternative to using `DOBSn` is to write `DATE-OBS` which applies to the whole table. This usage is considered to be safe and is recommended.

- `WCSHDO_TPCn_ka`: WCS Paper I defined

  - `TPn_ka` and `TCn_ka` for pixel lists

    but WCS Paper II uses `TPCn_ka` in one example and subsequently the errata for the WCS papers legitimized the use of

  - `TPCn_ka` and `TCDn_ka` for pixel lists

    provided that the keyword does not exceed eight characters. This usage is considered to be safe and is recommended because of the non-mnemonic terseness of the shorter forms.

- `WCSHDO_PVn_ma`: WCS Paper I defined

  - `iVn_ma` and `iSn_ma` for bintables and

  - `TVn_ma` and `TSn_ma` for pixel lists

    but WCS Paper II uses `iPVn_ma` and `TPVn_ma` in the examples and subsequently the errata for the WCS papers legitimized the use of

  - `iPVn_ma` and `iPSn_ma` for bintables and

  - `TPVn_ma` and `TPSn_ma` for pixel lists

    provided that the keyword does not exceed eight characters. This usage is considered to be safe and is recommended because of the non-mnemonic terseness of the shorter forms.

- `WCSHDO_CRPXna`: For historical reasons WCS Paper I defined

  - `jCRPXn`, `iCDLTn`, `iCUNIn`, `iCTYPn`, and `iCRVLn` for bintables and

  - `TCRPXn`, `TCDLTn`, `TCUNIn`, `TCTYPn`, and `TCRVLn` for pixel lists

    for use without an alternate version specifier. However, because of the eight-character keyword constraint, in order to accommodate column numbers greater than 99 WCS Paper I also defined

  - `jCRPna`, `iCDEna`, `iCUNna`, `iCTYna` and `iCRVna` for bintables and

  - `TCRPna`, `TCDEna`, `TCUNna`, `TCTYna` and `TCRVna` for pixel lists

    for use with an alternate version specifier (the `a`). Like the `PC`, `CD`, `PV`, and `PS` keywords there is a tendency to confuse these two forms for column numbers up to 99. It is very unlikely that any parser would reject keywords in the first set with a non-blank alternate version specifier so this usage is considered to be safe and is recommended.

- `WCSHDO_CNAMna`: WCS Papers I and III defined

  - `iCNAna`, `iCRDna`, and `iCSYna` for bintables and

  - `TCNAna`, `TCRDna`, and `TCSYna` for pixel lists

    By analogy with the above, the long forms would be

  - `iCNAMna`, `iCRDEna`, and `iCSYEna` for bintables and

  - `TCNAMna`, `TCRDEna`, and `TCSYEna` for pixel lists

    Note that these keywords provide auxiliary information only, none of them are needed to compute world coordinates. This usage is potentially unsafe and is not recommended at this time.

- `WCSHDO_WCSNna`: Write `WCSNna` instead of `TWCSna` for pixel lists. While the constructor treats `WCSNna` and `TWCSna` as equivalent, other parsers may not. Consequently, this usage is potentially unsafe and is not recommended at this time.

- `WCSHDO_SIP`: Write out Simple Imaging Polynomial (SIP) keywords.

- `WCSHDO_P12`, `WCSHDO_P13`, `WCSHDO_P14`, `WCSHDO_P15`, `WCSHDO_P16`, `WCSHDO_P17`, `WCSHDO_EFMT`

  These constants control the precision of the WCS keywords returned by `to_header`.

  - `WCSHDO_P12` : Use “%20.12G” format for all floating-point keyvalues (12 significant digits)

  - `WCSHDO_P13` : Use “%21.13G” format for all floating-point keyvalues (13 significant digits)

  - `WCSHDO_P14` : Use “%22.14G” format for all floating-point keyvalues (14 significant digits)

  - `WCSHDO_P15` : Use “%23.15G” format for all floating-point keyvalues (15 significant digits)

  - `WCSHDO_P16` : Use “%24.16G” format for all floating-point keyvalues (16 significant digits)

  - `WCSHDO_P17` : Use “%25.17G” format for all floating-point keyvalues (17 significant digits)

  - `WCSHDO_EFMT` : Use “%E” format instead of the default “%G” format above