(Created page with "<h3>SYNOPSIS</h3> <p style="margin-left:11%; margin-top: 1em"><b>firandom</b> [<i>options</i>] [<i>-o|--output <output></i>]</p> <h3>DESCRIPTION</h3> <p style="marg...") |
m (Apal moved page firandom:synopsis to man/firandom) |
firandom [options] [-o|--output <output>]
The main purpose of this program is to generate artifical object lists and/or artifical (astronomical) images.
General
options:
−h, −−help
Gives general summary about the command line options.
−−long−help
Gives a detailed list of command line options.
−−version
Gives some version information about the program.
Creating
artifical 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
artifical 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 <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 1.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 artifical list of sources and then creates an artifical 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.