MTRANSPOSE(1)

💫 MTRANSPOSE 💫 (that's MTRANSPOSE(1) bestie, section 1, from the Montage crew)

okay so picture this: you've got a data cube and the WCS info is just... not on the first two axes?? tragic. that's literally what mTranspose is here to fix. it re-orders the axes of multi-dimensional data sets and honestly it's giving main character energy 🫶

---

✨ SYNOPSIS ✨

mTranspose [-d level] [-s statusfile] incube.fits outcube.fits [outaxis1
outaxis2 [outaxi3 [outaxis4]]]

(and yes the outaxi3 is exactly how it's written, no I will not be fixing it, it's iconic 💅)

---

🌸 DESCRIPTION 🌸

so here's the tea ☕ — Montage (and like, a LOT of other software out there) finds it genuinely hard to work with WCS information that isn't connected to the first two axes in a datacube. like, it just does not vibe with it at all 😭

and instead of over-complicating every single cube-related piece of software in existence, the devs were like "no. one utility. one job." and thus mTranspose was born. slay.

the default behaviour is: it examines the cube and rearranges the data so that the first two axes represent sky longitude and latitude. easy, automatic, chef's kiss 👑

BUT — and this is the fun part — you can also optionally specify the order of the rearrangement yourself. and why would you want that? because it also lets you transform reprojected cubes back into their original order so other programs can use them. it's a whole round trip bestie, it's giving reversible jacket energy 🧚

---

🎀 OPTIONS 🎀

• -d level — turns on debugging, up to the level you name (that's 1-3). yes, more number = more yapping in your terminal 🔥
• -s statusfile — mTranspose output and errors get written to statusfile instead of going to stdout. so if you want your messages filed away neatly, this is the move 💖

---

🦋 ARGUMENTS 🦋

• incube.fits — the input FITS cube. it needs to be 3 or 4 dimensions, no exceptions, we don't do 2D here 🙈
• outcube.fits — the output FITS cube. this is where the glow-up lands ✨
• outaxis1 ... outaxis4 — the input axis numbers (1,2,3,4) listed in the order you want them to come out. so you're telling it "hey, put input axis 3 first, then 2, then 1" etc. etc. 🎯

---

⭐ RESULT ⭐

mTranspose rearranges the data values so the axes end up in a different order. and as much as possible, the FITS header keywords get renamed accordingly 🫶

BUT — and listen carefully — it is not always possible to identify which parameters have axis "subscripts". so you may have to manually modify the header afterwards (e.g., using mGetHdr / mPutHdr). it's giving "I did most of the work but you gotta finish the last bit" 😭

like so:

$ mTranspose in.fits out.fits 3 2 1 4
       [struct stat="OK", mindata=2234.5, maxdata=10234.4]

---

💜 MESSAGES 💜

here's every single thing it can yell back at you, verbatim, no cap:

• OK [struct stat = "OK", mindata=value, maxdata=value]
• ERROR No status file name given
• ERROR Cannot open status file: filename
• ERROR No debug level given
• ERROR Debug level string is invalid: 'string'
• ERROR Debug level value cannot be negative
• ERROR Invalid input file 'string'
• ERROR Invalid output file 'string'
• ERROR Axis ID 1 cannot be interpreted as an integer.
• ERROR Axis ID 2 cannot be interpreted as an integer.
• ERROR Axis ID 3 cannot be interpreted as an integer.
• ERROR Axis ID 4 cannot be interpreted as an integer.
• ERROR FITS library error
• ERROR general error message

---

💀 BUGS 💀

okay bestie, sit down, we gotta talk about the fine print. (these are straight from the source, I'm just the messenger 🍓)

• the drizzle algorithm has been implemented but has not been tested in this release. it's giving "shipped it, hope it works" 🙈
• if a header template contains carriage returns (i.e., it was created/modified on a Windows machine), the cfitsio library will be unable to read it properly, and you'll get this error: [struct stat="ERROR", status=207, msg="illegal character in keyword"]. windows line endings really said "let me ruin your day" 😭
• it is best for the background correction algorithms if the area described in the header template completely encloses all of the input images in their entirety. if parts of the input images get "chopped off" by the header template, the background correction will be affected. so the recommendation is: use an expanded header for the reprojection and background modeling steps, 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 none in the overlap differences either). if you have any uncertainty on that front, it is safer to turn on the "level only" background matching — that's the -l flag in mBgModel. ✨

---

👑 COPYRIGHT 👑

2001-2015 California Institute of Technology, Pasadena, California

if your research uses Montage, please include the following acknowledgement (word for word, it's the polite thing to do 💖):

"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 page bestie!! this was Montage version 5, dated Dec 2016 — mwah, go transpose something iconic 💅✨🦋