Tutorial

This tutorial demonstrates a common workflow for inspecting and correcting a FITS header using clfits.

Scenario

Imagine you have a FITS file, my_image.fits, from an observation. You suspect the object name is incorrect in one of the extensions and you need to verify and fix it.

Step 1: View the Primary Header

First, let’s look at the primary header to get an overview of the file.

clfits view my_image.fits

This will print the main header, which might contain information about the instrument and observation date.

Step 2: Discover and View Extensions

FITS files often contain multiple extensions, or Header Data Units (HDUs). Let’s say we know our data has a table extension named EVENTS. We can view its header directly:

clfits view my_image.fits --hdu "EVENTS"

If you don’t know the name, you can also use its index (the first extension is at index 1):

clfits view my_image.fits --hdu 1

Step 3: Search for a Keyword

You remember the object name keyword is something like OBJECT or OBJ_NAME. You can search for it in the EVENTS header:

clfits search my_image.fits --hdu "EVENTS" --key "OBJ*"

Let’s say this returns the following, confirming the keyword is OBJECT:

OBJECT  = 'NGC 41'           / Target object name

Step 4: Correct the Keyword Value

You’ve confirmed the object name is wrong; it should be ‘NGC 42’. You can correct it with the set command:

clfits set my_image.fits --hdu "EVENTS" OBJECT "NGC 42" --comment "Corrected object name per logs"

The tool will confirm the change was successful.

Step 5: Export the Corrected Header

Finally, you want to save a record of the corrected header. You can export it to a YAML file for easy reading:

clfits export my_image.fits --hdu "EVENTS" --output corrected_header.yml

Now you have a human-readable corrected_header.yml file documenting the state of the header after your fix. This entire workflow is scriptable, making clfits a powerful tool for data processing pipelines.