Astro:...:Header(3pm)

💖 NAME 💖

so bestie, welcome to the manual page for Astro::FITS::Header, straight outta the User Contributed Perl Documentation, section 3pm 🫶

Astro::FITS::Header — an Object Orientated interface to FITS HDUs. that's it, that's the whole vibe ✨

---

🌸 SYNOPSIS 🌸

  $header = new Astro::FITS::Header( Cards => \@array );

---

🦋 DESCRIPTION 🦋

okay so picture this: a FITS header block, right? all its little cards and keywords. this module keeps all of that info inside one single object 👑

you build it by handing over a hash where one of the values is an array reference. that array should contain a list of FITS header cards as input. that's the whole deal 💅

---

🎀 METHODS 🎀

🌟 Constructor 🌟

💫 new 💫

Create a new instance from an array of FITS header cards.

      $item = new Astro::FITS::Header( Cards => \@header );

returns a reference to a Header object. and here's the cute part — if you pass in no cards at all, you still get the (required) first SIMPLE card for free 🎁 like a lil welcome gift, no cap.

---

🔥 Accessor Methods 🔥

⭐ tiereturnsref ⭐

Indicates whether the tied object should return multiple values as a single string joined by newline characters (false) or whether it should return a reference to an array containing all the values.

Only affects the tied interface. just the tied one, okurrr.

      tie %keywords, "Astro::FITS::Header", $header, tiereturnsref => 1;
      $ref = $keywords{COMMENT};

Defaults to returning a single string in all cases (for backwards compatibility). so if you say nothing, you get the string, bestie.

🧚 subhdrs 🧚

Set or return the subheaders for a Header object. Arguments must be given as Astro::FITS::Header objects.

    $header->subhdrs(@hdrs);
    @hdrs = $header->subhdrs;

This method should be used when you have additional header components that should be associated with the primary header but they are not associated with a particular name, just an ordering. like, no name tag, just vibes and a queue position 💅

FITS headers that are associated with a name can be stored directly in the header using an Astro::FITS::Header::Item of type 'HEADER'.

🌈 item 🌈

Returns a FITS::Header:Item object referenced by index, undef if it does not exist.

   $item = $header->item($index);

👑 get_wcs 👑

Returns a Starlink::AST FrameSet object representing the WCS of the FITS Header.

   $ast = $header->get_wcs();

🍓 keyword 🍓

Returns keyword referenced by index, undef if it does not exist.

   $keyword = $header->keyword($index);

✨ itembyname ✨

Returns an array of Header::Items for the requested keyword if called in list context, or the first matching Header::Item if called in scalar context. Returns undef if the keyword does not exist. The keyword may be a regular expression created with the qr operator. slay.

   @items = $header->itembyname($keyword);
   $item = $header->itembyname($keyword);

💜 itembytype 💜

Returns an array of Header::Items for the requested type if called in list context, or the first matching Header::Item if called in scalar context. See Astro::FITS::Header::Item for a list of allowed types.

   @items = $header->itembytype( "COMMENT" );
   @items = $header->itembytype( "HEADER" );
   $item = $header->itembytype( "INT" );

🦄 index 🦄

Returns an array of indices for the requested keyword if called in list context, or an empty array if it does not exist. The keyword may be a regular expression created with the qr operator.

   @index = $header->index($keyword);

If called in scalar context it returns the first item in the array, or undef if the keyword does not exist.

   $index = $header->index($keyword);

🌸 value 🌸

Returns an array of values for the requested keyword if called in list context, or an empty array if it does not exist. The keyword may be a regular expression created with the qr operator.

   @value = $header->value($keyword);

If called in scalar context it returns the first item in the array, or undef if the keyword does not exist.

🎀 comment 🎀

Returns an array of comments for the requested keyword if called in list context, or an empty array if it does not exist. The keyword may be a regular expression created with the qr operator.

   @comment = $header->comment($keyword);

If called in scalar context it returns the first item in the array, or undef if the keyword does not exist.

   $comment = $header->comment($keyword);

💥 insert 💥

Inserts a FITS header card object at position $index

   $header->insert($index, $item);

⚠️ okay important lore: the object $item is not copied. multiple inserts of the same object mean that future modifications to the one instance of the inserted object will modify all inserted copies. it's giving shared custody, fr fr 😭

The insert position can be negative.

🔁 replace 🔁

Replace FITS header card at index $index with card $item

   $card = $header->replace($index, $item);

returns the replaced card.

🗑️ remove 🗑️

Removes a FITS header card object at position $index

   $card = $header->remove($index);

returns the removed card. bye bestie 👋

💫 replacebyname 💫

Replace FITS header cards with keyword $keyword with card $item

   $card = $header->replacebyname($keyword, $item);

returns the replaced card. The keyword may be a regular expression created with the qr operator.

🫧 removebyname 🫧

Removes a FITS header card object by name

 @card = $header->removebyname($keyword);

returns the removed cards. The keyword may be a regular expression created with the qr operator.

✂️ splice ✂️

Implements a standard splice operation for FITS headers

   @cards = $header->splice($offset [,$length [, @list]]);
   $last_card = $header->splice($offset [,$length [, @list]]);

Removes the FITS header cards from the header designated by $offset and $length, and replaces them with @list (if specified) which must be an array of FITS::Header::Item objects. Returns the cards removed. If offset is negative, counts from the end of the FITS header. so retro 🕰️

🃏 cards 🃏

Return the object contents as an array of FITS cards.

  @array = $header->cards;

📏 sizeof 📏

Returns the highest index in use in the FITS header. To get the total number of header items, add 1. (math girlies rise up 🧮)

  $number = $header->sizeof;

🌟 allitems 🌟

Returns the header as an array of FITS::Header:Item objects.

   @items = $header->allitems();

---

💅 General Methods 💅

🛠️ configure 🛠️

Configures the object, takes an array of FITS header cards, an array of Astro::FITS::Header::Item objects or a simple hash as input. If you feed in nothing at all, it uses a default array containing just the SIMPLE card required at the top of all FITS files. icon behaviour honestly 🎁

  $header->configure( Cards => \@array );
  $header->configure( Items => \@array );
  $header->configure( Hash => \%hash );

Does nothing if the array is not supplied. If the hash scheme is used and the hash contains the special key of SUBHEADERS pointing to an array of hashes, these will be read as proper sub headers. All other references in the hash will be ignored. Note that the default key order will be retained in the object created via the hash. 🔑

🔀 merge_primary 🔀

Given the current header and a set of Astro::FITS::Header objects, return a merged FITS header (with the cards that have the same value and comment across all headers) along with, for each input, header objects containing all the header items that differ (including, by default, keys that are not present in all headers). Only the primary headers are merged, subheaders are ignored. no subheader drama, periodt.

    ($clone) = $headerr->merge_primary();
    ($same, @different) = $header->merge_primary( $fits1, $fits2, ...);
    ($same, @different) = $header->merge_primary( \%options, $fits1, $fits2 );

@different can be empty if all headers match (but see the force_return_diffs option) but if any headers are different there will always be the same number of headers in @different as supplied to the function (including the reference header). A clone of the input header (stripped of any subheaders) is returned if no comparison headers are supplied. so clean ✨

In scalar context, just returns the merged header.

    $merged = $header->merge_primary( @hdrs );

The options hash is itself optional. It contains the following keys:

• merge_unique — if an item is identical across multiple headers and only exists in those headers, propagate to the merged header rather than storing it in the difference headers.
• force_return_diffs — return an empty difference object per input header even if there are no diffs.

🧊 freeze 🧊

Method to return a blessed reference to the object so that we can store this object on disk using the Data::Dumper module. freezing her for the archives ❄️

📎 append 📎

Append or update a card.

  $header->append( $card );

This method can take either an Astro::FITS::Header::Item object, an Astro::FITS::Header object, or a reference to an array of Astro::FITS::Header::Item objects.

In all cases, if the given Astro::FITS::Header::Item keyword exists in the header, then the value will be overwritten with the one passed to the method. Otherwise, the card will be appended to the end of the header.

Nothing is returned. (she gives nothing and that's the point 💅)

---

🎢 Operator Overloading 🎢

These operators are overloaded:

• "" — When the object is used in a string context the FITS header block is returned as a single string.

---

🙈 Private methods 🙈

These methods are for internal use only. not for you, bestie, look away 🙈

🔒 _rebuild_lookup 🔒

Private function used to rebuild the lookup table after modifying the header block, its easier to do it this way than go through and add one to the indices of all header cards following the modified card. iykyk 🔧

💖 TIED INTERFACE 💖

okay bestie, so this is the part where it gets fun. The FITS::Header object can also be tied to a hash. yes. like a whole hash. it's giving magic, it's giving slay. 🪄

use Astro::FITS::Header;

$header = new Astro::FITS::Header( Cards => \@array );
tie %hash, "Astro::FITS::Header", $header

$value = $hash{$keyword};
$hash{$keyword} = $value;

print "keyword $keyword is present" if exists $hash{$keyword};

foreach my $key (keys %hash) {
   print "$key = $hash{$key}\n";
}

like look at that. you just... use it like a hash. iconic behavior honestly. 💅

---

🌸 Basic hash translation 🌸

the header value type? determined on-the-fly by parsing whatever you feed it. anything that parses as a number or a logical gets converted to that before it lands in a card (but hold on, there's a "see below" moment, keep reading bestie).

per-card comment fields are accessible through the tied interface — just use a key name of key_COMMENT. why does this work? because _COMMENT is generally too long to be confused with a normal key name. so no collisions, we love that for us. 🎀

$comment = $hdr{CRPIX1_COMMENT};

that returns the comment chillin' with the CRPIX1 header item. and you can change the comment the exact same way:

$hdr{CRPIX1_COMMENT} = "An axis";

you can also modify the comment by slash-delimiting it while you set the associated keyword:

$hdr{CRPIX1} = "34 / Set this field manually";

now — if you want an actual literal slash character in your string field, you must escape it with a backslash. and if you're inside double quotes you gotta use a double backslash. no cap, that's just how it is:

$hdr{SLASHSTR} = 'foo\/bar / field contains "foo/bar"';

keywords are CaSE-inNSEnSiTIvE, unlike normal hash keywords. internally all keywords get translated to upper case, per the FITS standard. so don't come at me with your lowercase nonsense, it's getting uppercased regardless. ✨

and aside from the SIMPLE and END keywords — which are automagically placed at the beginning and end of the header respectively — keywords are included in the header in the order received. so you get a modicum of control over card order. but real talk: if you actually care what order they're in, you probably don't want the tied interface. just saying. 🙈

---

💬 Comment cards 💬

comment cards are a whole special case because they have no normal value, and their comment field is treated as the hash value. the keywords COMMENT and HISTORY are magic and refer to comment cards. nearly every other keyword creates normal valued cards. (see "SIMPLE and END cards" below, bestie, it's important.)

---

📜 Multi-card values 📜

multiline string values get broken up — one card per line in the string. extra-long string values are handled gracefully: they get split among multiple cards, with a backslash at the end of each card image. and they're transparently reassembled when you access the data, so there's a strong analogy between multiline string values and multiple cards. the way that works is honestly so clean. 🦋

in general, appending to hash entries that look like strings does what you think it should. in particular, comment cards have a newline appended automatically on FETCH, so that:

$hash{HISTORY} .= "Added multi-line string support";

adds a new HISTORY comment card, while:

$hash{TELESCOP} .= " dome B";

only modifies an existing TELESCOP card. see the difference? cute right.

you can make multi-line values by feeding in newline-delimited strings, or by assigning from an array ref. and if you ask for a tag that has a multiline value, it's always expanded to a multiline string, even if you fed in an array ref to start with. that's by design, bestie — multiline string expansion often acts as though you're getting just the first value back out, because perl string-to-number conversion stops at the first newline. so watch this:

$hash{CDELT1} = [3,4,5];
print $hash{CDELT1} + 99,"\n$hash{CDELT1}";

that prints 102\n3\n4\n5, and then:

$hash{CDELT1}++;
print $hash{CDELT1};

prints 4. yeah. i know. 😭

in short? most of the time you get what you want. but you can always fall back on the non-tied interface by calling methods like so:

((tied $hash)->method())

and if you'd prefer multi-valued items to automagically become array refs, you can get that behavior using the tiereturnsref method:

tie %keywords, "Astro::FITS::Header", $header, tiereturnsref => 1;

when tiereturnsref is true, multi-valued items get returned via a reference to an array (ties do not respect calling context, rude but okay). note that if this is configured, you'll have to test each return value to see whether it's returning a real value or a reference to an array — if you're not sure whether there will be more than one card with a duplicate name. so stay alert bestie. 👑

---

🔥 Type forcing 🔥

because perl uses behind-the-scenes typing, there's an ambiguity between strings and numeric and/or logical values. sometimes you want to create a STRING card whose value could parse as a number or as a logical value, and perl — being perl — kindly parses it into a number for you. 💀

to force string evaluation, feed in a trivial array ref:

$hash{NUMSTR} = 123;     # generates an INT card containing 123.
$hash{NUMSTR} = "123";   # generates an INT card containing 123.
$hash{NUMSTR} = ["123"]; # generates a STRING card containing "123".
$hash{NUMSTR} = [123];   # generates a STRING card containing "123".

$hash{ALPHA} = "T";      # generates a LOGICAL card containing T.
$hash{ALPHA} = ["T"];    # generates a STRING card containing "T".

calls to keys() or each() will, by default, return the keywords in the order in which they appear in the header. periodt.

---

🪆 Sub-headers 🪆

when the key refers to a subheader entry (ie an item of type HEADER), a hash reference is returned. and if a hash reference is stored in a value, it gets converted to a Astro::FITS::Header object. recursion slay.

if the special key SUBHEADERS is used, it returns the array of subheaders (as stored using the subhdrs method), each of which will be tied to a hash. subheaders can be stored using normal array operations. easy. 🌈

---

⭐ SIMPLE and END cards ⭐

no FITS interface would be complete without special cases, right? 🎀

when you assign to SIMPLE or END, the tied interface ensures that they are first or last, respectively, in the deck — as the FITS standard requires. other cards get inserted in between the first and last elements, in the order that you define them.

the SIMPLE card is forced to FITS LOGICAL (boolean) type. the FITS standard forbids you from setting it to F, but you can if you want — we're not the FITS police. 🚨 (jk we're literally not)

the END card is forced to a null type, so any value you assign to it will fall on the floor. 💀 if present in the deck, the END keyword always contains the value " ", which is both more-or-less invisible when printed and also true — so you can test the return value to see if an END card is present. sneaky but useful.

SIMPLE and END come pre-defined from the constructor. so if for some nefarious reason you want to remove them, you must explicitly do so with delete or the appropriate method call from the object interface. no shortcuts, bestie.

---

🌟 SEE ALSO 🌟

• "Astro::FITS::Header::Item"
• "Starlink::AST"
• "Astro::FITS::Header::CFITSIO"
• "Astro::FITS::Header::Item::NDF"

---

👑 COPYRIGHT 👑

Copyright (C) 2007-2011 Science and Technology Facilties Council.

Copyright (C) 2001-2007 Particle Physics and Astronomy Research Council and portions Copyright (C) 2002 Southwest Research Institute. All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA

---

💜 AUTHORS 💜

• Alasdair Allan <aa@astro.ex.ac.uk>
• Tim Jenness <t.jenness@jach.hawaii.edu>
• Craig DeForest <deforest@boulder.swri.edu>
• Jim Lewis <jrl@ast.cam.ac.uk>
• Brad Cavanagh <b.cavanagh@jach.hawaii.edu>

---

and that's the whole vibe bestie, we made it to the end 🫶 this lil page is from perl v5.36.0, dated 2023-04-21, and it's the Astro:...:Header(3pm) page from the User Contributed Perl Documentation. go forth and tie your hashes, you absolute icon. 💅✨🌸