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.

.. code-block:: bash

   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:

.. code-block:: bash

   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):

.. code-block:: bash

   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:

.. code-block:: bash

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

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

.. code-block:: text

   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:

.. code-block:: bash

   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:

.. code-block:: bash

   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.