FIRANDOM(1)

NAME
firandom - generates artificial object lists and simulated images

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

DESCRIPTION
The main purpose of this program is to generate artificial object lists and/or artificial (astronomical) images.

OPTIONS

  General options:

-h, --help
    Gives general summary about the command line options.

--long-help, --help-long
    Gives a detailed list of command line options.

--wiki-help, --help-wiki, --mediawiki-help, --help-mediawiki
    Gives a detailed list of command line options in Mediawiki format.

--version, --version-short, --short-version
    Gives some version information about the program.

  Creating artificial object lists:

-l, --list <list>
    Specifications for object list. The "list" parameter should be a set of comma separated tags, which can either be a value declaration or a repeat count followed by an expression between square brackets giving specifications for individual objects to be added to the list, also in the form of value declaration. The value declaration has the sintax of <variable>=<value>, where the variables can be the following:

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 momenum (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

One can use only one of the three equivalent set of profile shape parameters (i.e. f/e/p, s/d/k or S/D/K). See some more detailed documentation about these parameters. In the expressions which are in the square brackets, one can use arbitrary arithmetic expressions, using the standard basic arithmetical operators, elementary functions and the functions r(lo,hi) and g(mean,sigma) which results an uniformly distrbuted random number between "lo" and "hi" and a Gaussian random number with the specified "mean" and "sigma" (standard deviation), respectively. In the expressions for magnitude or intensity, one can use the previously defined values for the centroid coordinates too. The variable "n" is increased between 0 and the repeat count during the evaluation of the square bracket expressions.

--output-list <list file>
    Name of the list file where the object list created by the subsequent --list options are 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 backgroud with shows systematic variations. One can use the previously discussed r(lo,hi) and g(mean,sigma) functions, in order 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).

-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 vaule. 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. Note that using this Monte-Carlo method without additional photon noise emulation would result assymetric stellar profiles even when the profile would be symmetric. Use this option only when the --photon-noise option is also used, therefore the profiles are strained with photon noise either.

--noise-suppression <level>
    If the profiles are drawn using exact integration, the profiles would be infintely large since an analytical Gaussian profile is positive on the whole image domain. In order to limit the integration boundaries, this level limits the size of the integration domain, by the following way. The expected level of the objects'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 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 insead 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.

--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.

--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 case, save the object list to a separete file and merge the files using standard tools.

REPORTING BUGS
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>