MADDCUBE(1)

💖 mAddCube — the Montage co-addition queen 💖

okay bestie, welcome to mAddCube(1), aka the part of Montage where we take all your reprojected cubes and stack them into one gorgeous output mosaic. she's giving assembly-line glamour and honestly? iconic. ✨

---

🎀 SYNOPSIS 🎀

mAddCube [-p imgdir] [-n(o-areas)] [-a mean|median|count] [-e(xact-
size)] [-d level] [-s statusfile] images.tbl template.hdr out.fits

yes that's a lot of brackets, no we are not scared of them. 🫶

---

🌸 DESCRIPTION 🌸

So what she actually does: you hand her a whole list of reprojected cubes and she coadds them into one output mosaic, using the FITS header keywords that you specify in a header file. periodt.

She makes two output files, not one:

• one with the coadded pixel values for each cube plane 🧚
• the other with the coadded pixel area values

and the pixel area values? lowkey the moment. they can be used as a weighting function if the output cube values are themselves going to be coadded with other projected cubes — and they're also useful for validating the fidelity of the output pixel values. so she's not just pretty, she's functional. 💅

---

✨ OPTIONS ✨

• -p imgdir — tells her where the reprojected images live. if you don't pass -p, mAddCube will go looking for the input images in the current working directory, like a girl checking the fridge for snacks she already knows aren't there. 🙈
• -n — co-addition ignores weighting by pixel areas and does the coaddition based only on pixel positions. also: she will not output an area image for the output image. no area pic, no problem.
• -a type — picks which kind of averaging happens on the accumulated pixel values: either mean or median. and if you want a map showing counts of how many times each pixel was overlapped by the input images? use count. slay. 🔥
• -e — turns on exact size mode. the output image will match the header template exactly, instead of shrinking the output to fit the data. she stays her full size, no shrinking for anyone. 👑
• -d level — turns on debugging to the specified level (1-3). diagnostic queen behavior.
• -s statusfile — mAddCube output and errors get written to statusfile instead of stdout. for the girls who like their receipts filed away. 🍓

---

🦋 ARGUMENTS 🦋

• images.tbl — ASCII table (generated by mImgtbl) holding metadata for all the images to be coadded. heads up for cube girlies: mImgtbl needs to be run with the -C option, which picks up the third dimension parameters (and fourth if they exist). don't skip that flag, i'm begging. 😭
• template.hdr — the FITS header template used in generation of the output FITS cube. this is her blueprint.
• out.fits — name of the output FITS image. name her something cute.

---

🌈 RESULT 🌈

If everything goes right, mAddCube creates a FITS datacube file out.fits that is a coadd of all the FITS cubes in the table images.tbl, according to the header template given. and a corresponding out_area.fits is also created, because she always brings a plus-one. 💜

---

💀 MESSAGES 💀

here's the full roster of what she can yell at you. every single one, no skipping:

• OK [struct stat = "OK", time=time]
• ERROR Invalid argument for -a flag
• ERROR Cannot open status file: statusfile
• ERROR Invalid image metadata file: filename
• ERROR Need columns: cntr,fname, crpix1, crpix2, cdelt1, cdelt2, naxis1, naxis2, crval1, crval2, naxis3 in image list
• ERROR Too many open files
• ERROR Input wcsinit() failed.
• ERROR Bad WCS in header template.
• ERROR FITS library error
• ERROR general error message
• ERROR Allocation failed for file info (realloc)
• ERROR Allocation failed for file info structs
• ERROR Allocation failed for area file info structs
• ERROR Allocation failed for input buffer
• ERROR Allocation failed for input area buffer
• ERROR Allocation failed for start/end info
• ERROR Allocation failed for data line pointers
• ERROR Allocation failed for data line
• ERROR Allocation failed for area line pointers
• ERROR Allocation failed for area line
• ERROR Allocation failed for data counts
• ERROR Allocation failed for output data line
• ERROR Allocation failed for output area line
• ERROR Allocation failed for data line (realloc)
• ERROR Allocation failed for area line (realloc)
• ERROR Allocation failed for median array
• ERROR Allocation failed for median array (realloc)
• ERROR Allocation failed for linked list structs
• ERROR Allocation failed for linked list structs (additions)

ngl the allocation ones are giving "the server is out of RAM and so am i". 💀

---

⭐ EXAMPLES ⭐

the classic. this one runs mAddCube on 4 FITS images and generates the output file mosaic.fits. related files are images.tbl and template.hdr.

$ mAddCube -p proj images.tbl template.hdr output/mosaic.fits
       [struct stat="OK", time=1]

look at that [struct stat="OK", time=1]. clean. ate. no crumbs. 🔥

---

🙈 BUGS 🙈

okay now the fine print, and we do read the fine print here:

• The drizzle algorithm has been implemented but has not been tested in this release. so like… she exists, but nobody vetted her. proceed accordingly. 😭
• If a header template contains carriage returns (i.e., created/modified on a Windows machine), the cfitsio library will be unable to read it properly, resulting in the error: [struct stat="ERROR", status=207, msg="illegal character in keyword"]. windows line endings remain the villain of every story.
• 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 input images are "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, returning to the originally desired header size for the final coaddition. The default background matching assumes that there are no non-linear background variations in the individual images (and therefore in the overlap differences). If there is any uncertainty in this regard, it is safer to turn on the "level only" background matching (the -l flag in mBgModel).

bestie. do not let the header template chop off your input images. she will be affected. the background correction will be affected. everyone will be affected. give the girl room to breathe. 🫶

---

👑 COPYRIGHT 👑

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 page, bestie 💖 this was Montage 5, dated Dec 2016 — mAddCube said coadd and she meant it. go make a mosaic, you're the main character now. ✨🎀🦋