FIRANDOM(1)

✨ NAME ✨

okay so firandom — that's a section 1 user commands situation, iykyk — and its whole thing is that it generates artificial object lists and simulated images. fake stars, fake sky, all of it, no cap. 🔭💫

🌸 SYNOPSIS 🌸

firandom [options] [-o|--output <output>]

💫 DESCRIPTION 💫

bestie, the main purpose of this program is literally to generate artificial object lists and/or artificial (astronomical) images. that's the main character energy right there. 👑

---

👑 OPTIONS 👑

🎀 General options 🎀

• -h, --help — gives a general summary about the command line options. the tl;dr, the vibes-only version. 🫶
• --long-help, --help-long — gives a detailed list of command line options. the director's cut, the extended edition. 💅
• --wiki-help, --help-wiki, --mediawiki-help, --help-mediawiki — gives that same detailed list of command line options, but in Mediawiki format. wiki girlies rise. 📝
• --version, --version-short, --short-version — gives some version information about the program. 🎀

🍓 Creating artificial object lists 🍓

• -l, --list <list> — the specs for your object list. so the list parameter should be a set of comma separated tags, and each tag is either a value declaration or a repeat count followed by an expression between square brackets. that bracketed expression gives the specifications for the individual objects being added to the list, and it's also in the form of a value declaration.

a value declaration has the syntax <variable>=<value>, and the variables can be these ones right here:

• f — full width at half magnitude (FWHM) of the stellar profiles to be created
• e — ellipticity of the stellar profiles
• p — position angle of the stellar profiles
• s — sigma parameter for the stellar profile (FWHM is roughly 2.35 * sigma)
• d — delta (plus-shaped deviance) parameter for the stellar profile
• k — kappa (cross-shaped deviance) parameter for the stellar profile
• S — Gaussian momentum (a.k.a. profile sharpness parameter) for the stellar profile (S=1/sigma^2)
• D — plus-shaped momentum for the stellar profile
• K — cross-shaped momentum for the stellar profile
• x — normalized X coordinate of the profile centroid (using the standard normalization)
• X — absolute X coordinate of the profile centroid
• y — normalized y coordinate of the profile centroid (using the standard normalization)
• Y — absolute Y coordinate of the profile centroid
• m — magnitude of the stellar object
• i — flux of the stellar object

ok important: you can use only one of the three equivalent sets of profile shape parameters — so that's f/e/p, or s/d/k, or S/D/K. pick a lane. 🫠 see some more detailed documentation about these parameters if you want the deep lore.

inside those square bracket expressions you can use arbitrary arithmetic expressions: the standard basic arithmetical operators, elementary functions, and also the functions r(lo,hi) and g(mean,sigma). r(lo,hi) gives you a uniformly distributed random number between lo and hi, and g(mean,sigma) gives you a Gaussian random number with the specified mean and sigma (standard deviation). respectively, obviously. 💫

and in the expressions for magnitude or intensity, you can also use the previously defined values for the centroid coordinates. so cute, they talk to each other. the variable n gets increased between 0 and the repeat count while the square bracket expressions are being evaluated.

• --output-list <list file> — name of the list file where the object list created by the subsequent --list options gets saved. 📄
• --fep, --fep-output — save the shape parameters as FWHM, ellipticity and position angle to the output list file.
• --sdk, --sdk-output — save the shape parameters as sigma, delta and kappa to the output list file.
• --SDK, --SDK-output — save the shape parameters as Gaussian momenta to the output list file.

🌈 Creating artificial images 🌈

• -s, --size <sx>,<sy> — size of the image to be created.
• -b, --bitpix <bitpix> — standard FITS output bitpix value.
• -D, --data <spec> — output pixel data format specification.
• -m, --sky <sky> — sky (background level) for the image. this can be either a constant or an arbitrary function of the x, y, X and Y coordinates (see above) for a background that shows systematic variations. you can use the previously discussed r(lo,hi) and g(mean,sigma) functions too, if you want to add some sort of noise to the background. 🎨
• -d, --sky-noise <noise> — additional Gaussian noise, equivalent to the term "+g(<noise>,0)" added after the background level expression.
• --photon-noise, --no-photon-noise — emulate or disable the effect of photon noise on the individual stellar objects.
• -l, --list <list> — specifications for object list (see above, bestie, it's the same one 👆).
• -L, --input-list <list file> — name of the input list file from which the coordinates, shape parameters and intensities are read for the individual objects.
• --col-xy <colx>,<coly> — column indices for X and Y (absolute) centroid coordinates.
• --col-flux <flux column> — column index for flux (intensity).
• --col-mag <magnitude column> — column index for astronomical magnitude, see also --mag-flux.
• --col-shape <profile width>,[<profile shape 1>,<profile shape 2>] — column indices for stellar profile parameters. either 1 or 3 columns should be specified following this command line switch. one shape parameter is interpreted as a profile size parameter, where the 2 additional (optional) shape parameters describe the deviation from the symmetric profile. see also options --fep, --sdk or --SDK for more details.
• --fep, --fep-input — interpret the shape parameters read from the input list file as FWHM, ellipticity and position angle.
• --sdk, --sdk-input — interpret the shape parameters read from the input list file as the sigma, delta and kappa parameters.
• --SDK, --SDK-input — interpret the shape parameters read from the input list file as the Gaussian momenta parameters.
• -S, --input-sky, --input-background, --input-image <sky list file> — name of the input file containing the sky level. this file should contain at least three columns: the two pixel coordinates and the sky value. see also --col-pixel and --col-value.
• --col-pixel <colx>,<coly> — column indices for X and Y (absolute) pixel coordinates.
• --col-value <sky value column> — column index for sky value (intensity).
• --mag-flux <mag>,<flux> — magnitude - flux conversion level. the specified magnitude will be equivalent to the specified flux level.
• --integral, --no-monte-carlo — draw the stellar profiles to the image using exact integration.
• --monte-carlo, --no-integral — draw the stellar profiles to the image using a Monte-Carlo way.

⚠️ heads up: using this Monte-Carlo method without additional photon noise emulation would result in asymmetric stellar profiles, even when the profile would be symmetric. so use this option only when the --photon-noise option is also used, because then the profiles are strained with photon noise anyway. 😭

• --noise-suppression <level> — if the profiles are drawn using exact integration, the profiles would be infinitely large, since an analytical Gaussian profile is positive on the whole image domain. to limit the integration boundaries, this level limits the size of the integration domain, like this: the expected level of the object's own photon noise at the edges of the integration domain is smaller by this factor at least than the flux level. higher suppression level results in a larger integration domain. in the case of additional photon noise, the default value of 10000.0 is satisfactory. for images with no photon noise, this level should be increased appropriately. 📈
• --quantize, --no-quantize — quantize the output images to integers or not. note that altering this option yields somehow the same as when the bitpix value is altered.
• --adus, --no-electrons — use the input fluxes as ADUs instead of electrons (default).
• --electrons, --no-adus — use the input fluxes as electrons instead of ADUs.
• -g, --gain <gain> — electron/ADU ratio (gain).

🔥 Random seeds 🔥

• --seed <seed>|auto — generic random seed for firandom. a literal "auto" argument yields a random seed derived from random sources available on the architecture (/dev/urandom, current time). 🎲
• --seed-noise <seed>|auto — specific random seed for creating background noise.
• --seed-spatial <seed>|auto — specific random seed for creating random spatial coordinates, i.e. the random seed for functions in the --list arguments.
• --seed-photon <seed>|auto — specific random seed for photon noise.

💅 Command line argument combinations 💅

• --list <list> --output-list <list file> — this combination creates only a list file based on the --list arguments. list girlies, this one's for you. 📝
• --input-list <list file> --output-list <list file> — this combination just filters and copies the relevant contents from the input list to the output list. the shape parameters might be converted — for example --SDK-input --fep-output would convert Gaussian momenta to FWHM, ellipticity and position angle. glow-up, but for data. ✨
• --list <list> --output <output image> [--output-list <list file>] — this combination creates an artificial list of sources and then creates an artificial image with this newly created set of objects. by default, the list itself (incl. the centroid coordinates, shape parameters and intensities) is not saved, unless an output list file is given. 🙈
• --input-list <list file> --list <list> — this combination is invalid. the centroid list must either be read from a file or created by the program invocation, but lists cannot be merged this way. in such a case, save the object list to a separate file and merge the files using standard tools. not me trying to merge lists like that, it's giving undefined. 💀

---

😭 REPORTING BUGS 😭

report bugs to <apal@szofi.net>, see also https://fitsh.net/. be nice, they're doing their best. 🫶

💜 COPYRIGHT 💜

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

---

and that's the whole page, bestie 🎀 this was firandom 0.9.4 (2021.01.24), from January 2021, and it's giving iconic. go make some fake stars. ⭐💖