MEXAMINE(1)

📦 version 6.1, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💅 mExamine(1) — the sky-coverage tea, served hot

okay so bestie, say hi to mExamine(1) from the Montage crew ✨ she's the one you call when you need the deets on what patch of sky your FITS image is actually covering. Let's get into it 🫶

🌸 NAME 🌸

mExamine — Information about the sky coverage of a FITS image

✨ SYNOPSIS ✨

mExamine [-d][-p ra dec radius] image.fits

🦋 DESCRIPTION 🦋

mExamine hands you back the info about the sky coverage of a FITS image (she's assuming the WCS keywords are chillin' in the header, as they should be 💅) and, if you want it, she'll also slide you some pixel statistics for a region inside that image. no cap.

🎀 OPTIONS 🎀

  • -p ra dec radius — gives you the whole rundown on a region — central pixel value, min and max values and where they live, all of it. the coords and the radius are in degrees, unless you slap a "p" suffix on them, in which case they're in pixels. iykyk.
  • -a ra dec — runs a simple aperture photometry fit at a location. 🚨 heads up: you literally cannot use this at the same time as the -p option up there. also it plays by the same "p" suffix rule. periodt.
  • -d — turns on debugging. she gets chatty. 🔥

🌈 ARGUMENTS 🌈

  • image.fits — the FITS file you wanna examine. if your file has multiple HDUs, you can tack that onto the file name, like "m51.fits[2]". and if an HDU is a datacube, you can pick a plane, like "m51.fits[2][256]". even if there's only one HDU, you still have to specify it if you wanna name a cube plane — so "m51.fits[0][512]". 👑
ngl, this syntax might need quotes around the file name string, otherwise your shell will get confused and start drama. 🙈

💖 RESULT 💖

if everything slays, you get this back:

  • proj — Image projection
  • csys — Coordinate system
  • equinox — Coordinate system equinox
  • naxis — Number of axes in the file
  • naxis1 — Image width (in pixels)
  • naxis2 — Image height
  • naxis3 — Data cube depth (only if NAXIS > 2)
  • naxis4 — Data cube fourth dimension (only if NAXIS > 3)
  • crval1 — WCS reference coordinate for first axis
  • crval2 — WCS reference coordinate for second axis
  • crpix1 — Pixel value for reference coordinate
  • crpix2
  • cdelt1 — Pixel scale (degrees)
  • cdelt2
  • crota2 — Rotation of image (E of N)
  • lonc — Sky coordinate of image center
  • latc
  • ximgsize — Image size (degrees)
  • yimgsize
  • rotequ — Rotation of image in Equatorial (J2000)
  • rac — Equatorial (J2000) coordinates of image center
  • decc
  • ra1 — Equatorial coordinates of four image corners
  • dec1
  • ra2
  • dec2
  • ra3
  • dec3
  • ra4
  • dec4

and optionally 🍓

  • radius — Radius of pixel region (degrees)
  • radpix — Radius in pixels
  • npixel — Number of pixels in region
  • nnull — Number of null pixels
  • aveflux — Average flux for region
  • rmsflux — RMS of region fluxes
  • fluxref — Flux for reference location
  • sigmaref — RMS of fluxes
  • xref — Pixel coordinates of reference location
  • yref
  • raref — Equatorial (J2000) coordinated of reference location
  • decref
  • fluxmin — Same for pixel with minimum flux
  • sigmamin
  • xmin
  • ymin
  • ramin
  • decmin
  • fluxmax — Same for pixel with maximum flux
  • sigmamax
  • xmax
  • ymax
  • ramax
  • decmax
🚨 okay important: if you specify a region that is all blank, then npixel will be zero, nnull will be the total number of pixel examined, and every single flux-related parameter will be zero. not a vibe, but that's the deal.

💀 MESSAGES 💀

  • ERROR No ra, dec, radius location given or file name missing
  • ERROR File name missing
  • ERROR Cannot open FITS file test.fits
  • ERROR Cannot find WCS keys in FITS file test.fits
  • ERROR WCS initialization failed.
  • ERROR Location off the image.
  • ERROR Error reading FITS data.

👑 EXAMPLES 👑

mExamine -p 202.5 47.0 0.01 aJ_asky_980527n0240232.fits

and she said:

[struct stat="OK", proj="SIN", csys="EQUJ", equinox=2000.0,
naxis1=512, naxis2=1024, crval1=202.5213942, crval2=47.1131924,
crpix1=256.5, crpix2=512.5, cdelt1=0.0002778, cdelt2=0.0002778,
crota2=0.0034, lonc=202.5213942, latc=47.1134702,
ximgsize=0.142222, yimgsize=0.142222, rotequ=0.0034,
rac=202.5213942, decc=47.1131924, ra1=202.6260252,
dec1=46.9706487, ra2=202.4171950, dec2=46.9706407,
ra3=202.4166112, dec3=47.2553630, ra4=202.6265617,
dec4=47.2553710, radius=0.0100000, radpix=36.00, npixel=5476,
nnull=0, aveflux=136.807, rmsflux=0.853615, fluxref=137.3,
sigmaref=0.578143, xref=309, yref=105, raref=202.5000208,
decref=46.9999951, fluxmin=135.042, sigmamin=-2.06764, xmin=328,
ymin=77, ramin=202.4922870, decmin=46.9922153, fluxmax=152.299,
sigmamax=18.1493, xmax=307, ymax=117, ramax=202.5008338,
decmax=47.0033286]

like, she ATE. 💅

🧚 BUGS 🧚

okay so the drizzle algorithm has been implemented but has not been tested in this release. so… no cap, proceed accordingly 😭

if a header template contains carriage returns (i.e., it was created or modified on a Windows machine), the cfitsio library will be unable to read it properly, which results in this error:

[struct stat="ERROR", status=207, msg="illegal character in keyword"]

also, for the background correction algorithms it's best if the area described in the header template completely encloses all of the input images in their entirety. if parts of input images get "chopped off" by the header template, the background correction will be affected. we recommend you use an expanded header for the reprojection and background modeling steps, and then return to the originally desired header size for the final coaddition. the default background matching assumes there are no non-linear background variations in the individual images (and therefore in the overlap differences). if there's any uncertainty about that, it is safer to turn on the "level only" background matching — that's the -l flag in mBgModel. 🌸

2001-2015 California Institute of Technology, Pasadena, California

if your research uses Montage, please include the following acknowledgement: "This research made use of Montage. It is funded by the National Science Foundation under Grant Number ACI-1440620, and was previously funded by the National Aeronautics and Space Administration's Earth Science Technology Office, Computation Technologies Project, under Cooperative Agreement Number NCC5-626 between NASA and the California Institute of Technology."

the Montage distribution includes an adaptation of the MOPEX algorithm developed at the Spitzer Science Center.

and that's the whole thing bestie 🫶 this is Montage 5, from Dec 2016 — now go examine those skies, main character 💖✨

📦 where this page comes from