FIPHOT(1)

👑 FIPHOT(1) 👑

okay bestie, sit down, grab a snack 🍓, because we are about to do photometry. aperture photometry. on normal images or on subtracted/convolved ones. it's giving observatory-at-3am energy and honestly? iconic. 💅 this is the manual page for fiphot, and by the end of it you will know every single flag. no cap. ✨

---

✨ NAME ✨

fiphot — performing photometry on normal or subtracted images 🦋

🌸 SYNOPSIS 🌸

fiphot [options] [<input>] [-o|--output <output>]

💖 DESCRIPTION 💖

This program performs aperture photometry on normal or subtracted/convolved images. that's the whole vibe. periodt. 🌈

---

🎀 OPTIONS 🎀

💫 General options:

• -h, --help — Gives general summary about the command line options. like a lil recap, cute. 🫶
• --long-help, --help-long — Gives a detailed list of command line options. the full lore drop. 📖
• --wiki-help, --help-wiki, --mediawiki-help, --help-mediawiki — Gives a detailed list of command line options in Mediawiki format. for when you wanna paste it somewhere pretty. ✨
• --version, --version-short, --short-version — Gives some version information about the program. who are you, what era are you from. 👑
• -i, --input <image file> — Name of the input FITS image file. your main character image. 📸

🔭 Simple aperture photometry:

• -L, --input-list <input coordinate list file> — Name of the input coordinate list file. the guest list of all your objects. 📋
• --col-xy <colx>,<coly> — Column indices for centroid coordinates. and listen, the coordinates read from this file follow the native coordinating scheme (which is not the same as e.g. in IRAF), namely the lower-left corner of the lower-left pixel has the coordinate of (0,0) while the center of the lower-left pixel has the coordinate of (0.5,0.5). Programs like IRAF use the coordinate (1,1) for the center of the lower-left pixel. so like, do not come in here with IRAF habits, bestie, i'm begging 😭
• --col-ap <A1>,<A2>,... — Column indices for various apertures. In each such column, there must be three colon-separated number, for the radius of the aperture, inner radius for the background annulus and the thickness of the annulus, respectively. This option is not mandatory, all of the objects can be measured with the same set of apertures, see also -a|--apertures for more details. so it's optional but she's there if you need her. 💅
• --col-id <identifier column> — Column index for object identifier. name tag for each lil guy. 🏷️
• --col-mag, --col-magnitude <magnitude column> — Column index for reference magnitude.
• --col-col, --col-color <color column> — Column index for photometric color.
• --col-err, --col-error <magnitude error column> — Column index for magnitude uncertainty.
• -z, --zoom <zoom level> — Mutiply both the input centroid coordinates and aperture/annulusradii by the given integer factor. yes, it's a glow-up for your whole coordinate system. 🔍
• --serial <serial> — Serial identifier for the whole photometry procedure. Can be any arbitrary string and used only in the formatted output (see -F|--format for more details). it's a lil serial number, you can literally write whatever. 💫
• -F, --format, --format-output <objecttags>,<photometrytags> — List of output format tags. The formatted (user-friendly) output photometry contains a few columns containing the data related to the object, which followed by a the per-aperture photometry results. See "Format tags" for the list of format tags used here. this is how you dress up the output. 🎀
• --nan <nan-string> — String which is used to denote bad photometry. By default, objects on which photometry cannot be performed (due to various reasons, e.g. the object is off from the image, the background level cannot be determined or there are bad pixels in the aperture itself), are marked by a simple dash ('-') in the output file. so if photometry can't happen, you get a dash instead of a number. it's the sad little shrug of output. 🫠
• -M, --input-mask <image file> — Input mask file to co-add to the mask of the input image. Useful for marking pixels to be ignored from the photometry process beyond the ones which are previously marked in the input image. extra pixels to ✨ignore✨.
• -a, --aperture, --apertures <list of circular apertures> — List of circular apertures to be involved in the photometry. Each circular aperture is defined by three numbers: the radius of the aperture, and the inner radius and "thickness" of the annulus used for sky background estimation. The aperture specifications must be spearated by commas while these three numbers must be separated by colons. E.g. to perform aperture photometry on a series of apertures with a radius of 1.5, 2.0 and 2.5 pixels, where all of the annuli have an inner and outer radius of 6.5 and 12 pixels (i.e. the thickness is 5.5 pixels), one should write 1.5:6.5:5.5,2.0:6.5:5.5,2.5:6.5:5.5 as an argument for this option. circles only, no polygons allowed here, we'll get to those. ⭕
• -a, --aperture, --apertures <list of simple polygon apertures> — List of polygon shaped apertures. Polygons can only be simple (i.e. non-intersection) or weakly simple polygons which are defined throughout the form of P[x1,y1,...,xn,yn] or polygon[x1,y1,...,xn,yn]. The (x,y)=(0,0) point always refer to the aperture centroid as read from the input list (see --input-list above). There are two types of pre-defined simple polygons which is useful in astronomical image processing. The first definition is Q[R,n,alpha] or regular[R,n,alpha] which implies a regular polygon having n sides and an area equivalent to a circle with a radius of R and the polygon is rotated w.r.t the xy-plane by "alpha" degrees. In the asymptotic limit of n -> infinity, this aperture is equivalent to a circular aperture. The second type is T[R,n,dx,dy] or trail[R,n,dx,dy] where this definition implies a nearly oval racetrack-shaped aperture with a curvature radius of R, a net length of L=sqrt(dx^2+dy^2), the round part is approximated by a regular n-gon and the whole shape is rotated w.r.t the x+ axis as defined by the (dx,dy) vector. In the limit of L -> 0, this shape is equivalent to the aperture definition of regular[R,n,alpha]. The trail[....] shape is useful to perform photometry on asteroid or meteoroid trails. One should note that circular and polygon aperture definitions cannot be mixed. In addition, it should be noted that in case of polygon-shaped apertures, the second definition implies the inner edge of the background area and the third definition implies the outer edge of the background area. For instance, the aperture 3:5:5 can be ideal for point sources, the aperture trail[3,16,3.0,4.0]:trail[5,16,3.0,4.0]:trail[10,16,3.0,4.0] can be optimal for a asteroid trail on the same image that has a net length of 5.0 pixels and parallel with the vector (3.0,4.0). In this case, the equivalent radius of the third part is set to 10 which is equivalent to the 5+5=10 pixels of the radius of the outer annulus in the definition of 3:5:5. this one is a whole saga but she ate. 🔥
• -g, --gain, --gain-poly <gain polynomial> — The polynomial describing the gain level throughout the image. Altough during the image readout process, the electron <-> ADU conversion ratio has a fixed value, during the calibration process when the vignetting is strong, the ADU levels may substantially change. The comma-separated numbers in the gain polynomial should denote the coefficients for the monomials 1, x, y, 1/2x^2, xy, ... (the standard order for 2 dimensional polynomial coefficients), where x and y are the normalized coordinates (i.e. zero at the center of the image, x = +/- 1 at the right/left edge of the image and y is scaled appropriately keeping the aspect ratio). Note that the number of coefficients should be 1, 3, 6, 10, ... and so on, for zeroth, first, second, third... order variations, respectively. Specifying zero or negative gain will imply an "infinitely large" gain, thus data are treated as being affected only by instrumental noise and lack intrinsic photon noise. no photons, just vibes. ⚡
• --gain-vmin <minimal gain> — The minimal value for the gain level. If the polynomial describing the spatial gain variations is evaluated on the regular image domain and yielded a smaller value than this given number, this will be used as gain level. In certain optical systems, the vignetting can be well described by second-order polynomial coefficients except at the very corners of the image. In such a situation this minimal gain is quite useful. it's the floor, the bare minimum, we respect her. 🧚
• --correlation-length <background correlation length> — Correlation length of the image. This number is used as an estimator for background noise in the case of images where the background shows correlation. By default, this parameter is unity (1.0). If the image is magnified during processing, then one should specify this magnification ratio here. For instance, if an image is created with fitrans --zoom 4, then specify fiphot --correlation-length 4 ... as well. so like, keep them matching, bestie, it's giving coordinated outfits. 👯
• --mag-flux <mag>,<flux> — Magnitude - flux conversion level. The specified magnitude will be equivalent to the specified flux level. a lil exchange rate between mags and flux. 💱
• --sky-fit <sky fitting parameters> — This argument is followed by a set of parameters for the sky (i.e. background level) fitting algorithm. See "Sky fitting parameters" below for more details. background glow-up incoming. 🌌
• --aperture-mask-ignore <list of masks> — This switch is followed by a space separated list of standard masks which should be ignored if such a pixel is marked so in the aperutre. In practice, it might be useful to put saturated objects into the set of "good" stars. yes queen, ignore the mask, let her cook. 🙈
• -o, --output <output photometry file> — Name of the output file containing the results of the aperture photometry. The format and content of this file can be arbitrarily set, see -F|--format. your final product. the reveal. ✨
• --output-raw-photometry <output raw photometry> — Name of the output file containing the all of the low-level photometric information in a fixed format. From this file, one can derive all of the quantities which are written to the "normal" output photometry file. The main purpose of this file is to be an input for image subtraction based photometry, i.e. the photometric information for the reference image is supposed to be stored in this format and the successive calls of fiphot on the subtracted residual images read this information in order to derive the final photometric information. See the subsection "Photometry on subtracted/convolved images" about more details on the image subtraction based photometry. this is the ✨behind the scenes✨ file, the raw unedited footage. 🎬

Note that the literal "auto" argument can also be used after the -g|--gain switch. In this case, fiphot tries to figure out the gain polynomial from the GAINPOLY and GAIN keywords (in this order) as well as the minimal value for the gain from the GAINVMIN keyword. so auto = let her figure it out herself. 💅

---

🌟 Format tags for generic object data:

• I — identifier
• S — serial identifier (set by --serial)
• X — X coordinate of the centroid
• Y — Y coordinate of the centroid
• - — empty column

✨ Format tags for photometric data ✨

Okay bestie, these are the little letters that tell fiphot what to write out for each object. They are literally the alphabet of photometry, no cap. 💖

• M — magnitude
• m — uncertainty in the magnitude
• B — background level
• b — background scatter
• F — flux
• f — flux uncertainty
• A — same as F
• a — same as f
• E — flux in electrons
• e — flux uncertainty in electrons
• X — X coordinate of the fitted centroid
• x — X coordinate uncertainty
• Y — Y coordinate of the fitted centroid
• y — Y coordinate uncertainty
• W — Statistical profile size (S), in pixels
• D — Statistical profile deviation parameter (D), in pixels
• K — Statistical profile deviation parameter (K), in pixels
• w — Uncertainty of statistical profile size
• - — empty column

💅 Fine tuning of aperture photometry 💅

Now we get into the spicy aperture stuff, bestie. These options let you control how the background is determined and how photometry is done. Slay.

• -j, --disjoint-annuli, --disjoint-rings — During the background determination on the aperture annuli, omit the pixels which belong to the annuli of other centroids. On very dense fields this might make the aperture photometry impossible since for some or many of the target centroids, the background level cannot be derived due to the lack of sufficient number of background pixels. 💀
• -p, --disjoint-apertures — During the background determination on the aperture annuli, omit the pixels which belong to the apertures of other centroids.
• -x, --disjoint-radius <radius> — During the background determination on the aperture annuli, omit the pixels which are closer to the other centroids than the specified radius.
• -k, --spline — Use a flux-conserving biquadratic spline interpolation surface for photometry purposes. This surface yields some sort of weighting within each pixel due to the properties of the spline interpolation. ✨
• -m, --magfit orders=<c0>[:<c1>[:<c2>[:<c3>]]],iterations=<d>,sigma=<s> — Perform a magnitude transformation after the photometry. Currently implemented only in the case of image subtraction photometry and always use the reference photometry (see --input-raw-photometry) as a reference for magnitude transformation too. This command line option must be followed by the parameters of the magnitude fit, namely the list of spatial polynomial orders for the subsequent color orders (colon-separated list), and the number of (optional) outlier rejection iterations and its limit in standard deviation (sigma) units. 🔥

🌈 Photometry on subtracted/convolved images 🌈

For when you're doing the subtraction/convolved image thing, these options are your besties. 💜

• -P, --input-raw-photometry <input reference raw photometry> — Name of the file containing the coordinate lists and the raw photometric information for the reference image.
• -K, --input-kernel <input file with kernel solution> — The kernel solution which resulted during the creation of the convolved and/or subtracted image. This information is also required for the proper self-consistent aperture photometry on subtracted images. Omitting this file will result an assumption for identical convolution transformation, which only appropriate if the subtracted image is created by a literal arithmetic subtraction (and not convolution based subtraction). 😭
• --normalize-kernel — Normalize kernel solution on each point to unity. Useful for space-borne photometry with high variations in the PSF shape in the cases where the kernel solution is derived empirically and there are many variable sources in the field. 👑

🎀 Optimal aperture determination 🎀

These help you find the perfect aperture size, because your faves deserve the best. ✨

• --output-list <output coordinate list file> — The name of the output centroid list file, in which the radius of the optimal aperture is also stored. The optimal aperture is derived from the object flux itself, the gain level, the background noise and the FWHM of the objects. The background noise can be specified using the -d|--sky-noise argument (see there). The FWHM is given by the option -f|--fwhm.
• -d, --skynoise <noise> — Sky (background level) noise level in ADUs.
• -f, --fwhm <FWHM> — Full width at half magnitude (FWHM) for the stellar objects.

🌸 Sky fitting parameters 🌸

Now for the sky background vibes. These are the parameters you can use to fit the sky, bestie. 🌈

• mean — Use the mean value of the pixels in the annulus as a sky value.
• median — Use the median value of the pixels in the annulus as a sky value.
• mode — Use the mode of the pixels in the annulus as a sky value.
• iterations=<iterations> — Do the specified number of iterations in order to reject outlier pixels.
• lower, upper, sigma=<sigma level> — Lower, upper and generic (symmetric) outlier level in the units of standard deviations.
• force=<level> — Use the forced constant level for sky background, with zero nominal scatter.

🐞 REPORTING BUGS 🐞

Found a bug? Don't be shy, bestie. Report bugs to <apal@szofi.net>, see also https://fitsh.net/. 💌

👑 COPYRIGHT 👑

Copyright © 1996, 2002, 2004-2008, 2010-2016, 2018-2020; Pal, Andras <apal@szofi.net>

---

That's the whole page, bestie. fiphot 0.9.4 (2021.01.24), January 2021 — and yes, it's giving main character energy. Periodt. 💅✨🫶