ASDF WCS Schemas

0.5.0 · active · verified Thu Apr 16

The `asdf-wcs-schemas` library provides ASDF (Advanced Scientific Data Format) schemas specifically designed for validating World Coordinate System (WCS) tags. It is a crucial component within the broader ASDF ecosystem, particularly for astronomical data, and is typically consumed as a dependency by higher-level packages like `gwcs`. The current version is 0.5.0, and its release cadence is tied to updates in the ASDF Standard and related scientific data formats.

Common errors

```
jsonschema.exceptions.SchemaError: The metaschema specified by $schema was not found. Using the latest draft to validate, but this will raise an error in the future.
```
cause Incompatibility between the `asdf` library's schema resolution mechanism and newer versions of the `jsonschema` validation library (e.g., `jsonschema` 4.10.0 and above with older `asdf` versions).

fix Upgrade your `asdf` library to a version compatible with your `jsonschema` version, or explicitly pin `jsonschema` to a known compatible version (e.g., `<4.10.0`) if an `asdf` upgrade is not immediately feasible. Consult the `asdf` changelog for `jsonschema` compatibility notes.
```
AttributeError: 'list' object has no attribute 'get'
```
cause This error can occur during ASDF file validation when using incompatible versions of `asdf` and `jsonschema`, particularly seen with `jsonschema` 4.10.0 and above. It indicates that the validation process is attempting to call `.get()` on a list where a dictionary-like object (a schema definition) is expected.

fix This issue is typically resolved by upgrading the `asdf` package to a version that properly handles the changes in `jsonschema`'s API. Ensure `asdf` and `jsonschema` dependencies are updated.

Warnings

gotcha Users should generally not install `asdf-wcs-schemas` directly. It is a schema-only package intended to be a dependency of other libraries, primarily `gwcs`. Installing `gwcs` will automatically pull in the correct version of `asdf-wcs-schemas`.
Fix: Install `gwcs` (or another ASDF extension that leverages WCS schemas) instead of `asdf-wcs-schemas` directly: `pip install gwcs`.
breaking Older ASDF versions (e.g., prior to 2.6.0) might have included WCS schemas that were later deprecated and moved to the `gwcs` package. This can lead to validation issues or unexpected behavior if `asdf`, `gwcs`, and `asdf-wcs-schemas` versions are not compatible or if an old ASDF file is read with a new `gwcs` setup.
Fix: Always ensure `asdf`, `gwcs`, and `asdf-wcs-schemas` are kept up-to-date and compatible. Refer to the `gwcs` documentation for recommended dependency versions. Check the `asdf` changelog for details on schema deprecations and moves.
gotcha ASDF files rely on correct schema and manifest versions. Using incorrect or outdated tags/manifests for WCS objects can lead to validation failures or improper deserialization, even if the underlying `asdf-wcs-schemas` package is present.
Fix: When creating or modifying ASDF files with WCS objects, ensure that the ASDF tags and manifest versions referenced in the file (e.g., `tag:stsci.edu:asdf/wcs/wcs-1.0.0`) are consistent with the `gwcs` library version being used for serialization. Always use the tags provided by `gwcs` rather than direct schema file references where possible.

Install

pip install asdf-wcs-schemas Direct installation
pip install gwcs Recommended (installs as dependency)

Quickstart

This quickstart demonstrates how to create and serialize a `gwcs` WCS object into an ASDF file. The `asdf-wcs-schemas` package is implicitly utilized by the `asdf` library during the write and read operations to validate the structure of the WCS data. This package is not intended for direct Python imports for user-level functionality, but rather provides the underlying schema definitions.

import asdf
from gwcs import wcs
from astropy.modeling import models
from astropy import units as u
from gwcs.coordinate_frames import Frame2D, CelestialFrame
from astropy.coordinates import ICRS
import os

# Create a simple WCS object using gwcs
detector_frame = Frame2D(name="detector", axes_names=("x", "y"))
celestial_frame = CelestialFrame(reference_frame=ICRS(), name='icrs', unit=(u.deg, u.deg))

transform = models.Scale(0.1 * u.deg) & models.Scale(0.1 * u.deg)

my_wcs_object = wcs.WCS(transform, input_frame=detector_frame, output_frame=celestial_frame)

tree = {"my_wcs_data": my_wcs_object}

# Save the WCS object to an ASDF file
file_path = "example_wcs.asdf"
with asdf.AsdfFile(tree) as af:
    af.write_to(file_path)

print(f"WCS object saved to {file_path}")

# Read the ASDF file back. The WCS schemas are implicitly used for validation.
with asdf.open(file_path) as af:
    loaded_wcs = af.tree["my_wcs_data"]
    print("Loaded WCS object:")
    print(loaded_wcs)

# Clean up the created file
os.remove(file_path)

view raw JSON →