/usr/share/doc/munipack/artific.html

<!DOCTYPE HTML>
<html lang="en">
<head>
<!-- meta -->
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<meta name="description" content="A general astronomical image processing software">
<meta name="author" content="Filip Hroch">
<link href="news_feed.xml" type="application/atom+xml" rel="alternate" title="Sitewide ATOM Feed" />
<link type="text/css" rel="stylesheet" href="munipack.css">
<link rel="shortcut icon" href="favicon.ico">
<title>Munipack ‒ Artificial Sky</title>
</head>
<body>
<header>
<a href="munipack.html"><img src="title_logo.png" alt="Munipack's logo" class="head"></a>
<div class="headhead">
<div class="headtitle">
<a class="headtitle" href="munipack.html">Munipack</a>
<a class="headsubtitle" href="munipack.html">A general astronomical image processing software</a>
</div>
<ul class="menu">
  <li class="menu">◈ <a href="docs.html" class="menu">Documents</a></li>
  <li class="menu">☺ <a href="guide.html" class="menu">User guide</a></li>
</ul>
</div>
</header>

<h1>Artificial Sky</h1>

<p class="abstract">
  An overview of an artificial sky modelling.
</p>


<h2>Purpose</h2>

<p>
  The tool <samp>artificial</samp> creates artificial frames which looks
  similar as frames acquired by a real telescope. The primary purpose of
  this tool is to test and to verify algorithms of Munipack.
  However, it can be very useful
  for both education and planing of an observation
  because various atmospheric and instrumental effects as well
  as various phenomena can be easy modelled.
</p>

<h2>Brand Icon</h2>

<p>
  All generated frames are marked by a brand icon. The icon is supposed
  as the very important element because the created frames can look very
  realistic for inexperienced peoples. In many situations, it can be very
  difficult to recognise, even by an objective method,
  between a real and an artificial frame. That why there is no way how
  to remove the icon without a source code modification.
</p>

<figure>
<img class="figure" src="artbrand.png" alt="artbrand.png" title="Brand Icon">
<figcaption>The brand icon</figcaption>
</figure>

<p>
  FITS headers of all files contains review of parameters used for frame
  generation. It naturally indicates the right origin of any frame without
  doubts. However, frames are sometimes converted to other picture formats
  such as PNG or JPG, or examined by non-expers,
  so the clearly visible watermark is the proper warning sign.
</p>


<h2>The Very First Simulation</h2>

<p>
  For our very first generated frame, we'll select the open star
  cluster NGC 637 (see <a href="chart.html">A Star Chart Tutorial</a>).
  The artificial frame can be generated by these commands:
</p>
<pre>
$ munipack cone -o ngc637.fits -r 0.1 -- 25.775 64.03
$ munipack artificial -c ngc637.fits --rcen 25.775 --dcen 64.03 --verbose
</pre>
<p>
  The result is available as <samp>artificial.fits</samp> and displayed
  on figure below. Many parameters has been keep on their default values
  as <samp>--verbose</samp> switch shows.
  The most important parameters are the telescope area 1m<sup>2</sup>
  (cca 1.1m in diameter by default) and the exposure duration
  1 second.
  The stars on the frame has been given by a catalogue (in this case UCAC4)
  so a real exposure can provide more deeper look.
</p>

<figure>
<img class="figure" src="ngc637_art.jpeg" alt="ngc637_art.jpeg" title="NGC 637">
<figcaption>Artificial frame of NGC 637</figcaption>
</figure>


<p>
  Size of the generated picture, field of view (or scale) and rotation can be
  adjusted. Results can be saved to a named file. The following example creates
  a mini picture with dimensions in golden ratio, which is rotated around
  center with 180° angle and stored in <samp>ngc637_mini.fits</samp> file.
</p>
<pre>
$ munipack artificial -c ngc637.fits --rcen 25.775 --dcen 64.03 --verbose \
                      --width 168 --height 100 --fov 0.2 --angle 180 \
                      --mask ngc637_mini.fits
</pre>

<figure>
<img class="figure" src="ngc637_mini.jpeg" alt="ngc637_mini.jpeg" title="NGC 637">
<figcaption>Miniature of NGC 637</figcaption>
</figure>


<h2>Observation Planning</h2>

<p>
  Artificial frames can be useful in preparing of plans of an observation.
  The observer's proper choice of the exposure time for an unknown object
  significantly increase both reliability and precision of results.
  The matter can be generalised also on an unknown telescope,
  actual observing conditions, detectors. All the conditions can be
  adjusted "on the run", but this tool can help to save precious
  observing time.
</p>

<p>
  All the detector and telescope parameters can be set with <samp>--exptime,
    --diameter (--area), --qeff</samp> options.
  Their impact, using common values, in case of the field of blazar 0716+71
  displays the figure.
  The blazar itself is at centre of the picture on pixel coordinates 256, 192.
</p>
<pre>
$ munipack cone -r 0.3 -- 110.473 71.343
$ munipack artificial --qeff 0.02 --exptime 120 --area 0.3 \
                      -c cone.fits --rcen 110.473 --dcen 71.343 --fov 0.3 \
                      --width 512 --height 384 --col-mag Vmag
</pre>

<figure>
<img class="figure" src="0716_art.jpeg" alt="0716_art.jpeg" title="0716+71">
<figcaption>Artificial frame of 0716+71</figcaption>
</figure>

<p>
  Keep in mind, the frames with different parameters can looks identical due
  auto-adjusting capabilities of FITS viewers. Observed frames taken
  at longer exposures will reveal more faint stars, which are not included
  in common catalogues, due to its limitations. To be sure, while playing with
  artificial sky, inspect values of single pixels inside stars, that
  simulated counts are proportional to the parameters.
</p>

<p>
  The quantum efficiency (<samp>--qeff</samp>) of a telescope includes
  products of
  all individual efficiencies in given spectral band of detector (CCD), filter, telescope
  (and possibly other optical elements down to optical path). They can be estimated
  from a calibrated observed frame by CTPH keyword as <i>r</i>
  (<a href="dataform_photometry.html">see</a>). The frame should be
  take near zenith. Assuming of an extinction in the given filter on <i>k</i>
  (typical values are 0.05 for Johnson R and 0.3 for Johnson B filters),
  the efficiency is <i>η = 1/r - k</i>. The typical values <i>η</i> lies inside
  interval from 0.05 (bad) to 0.5 (very good).
</p>


<p>
<span class="par">Range checking</span>
The visual inspection of peak value of the blazar gives
4300 counts above background (peak at 5300, background one thousand).
The value is pretty acceptable. The peak value is within expected dynamical
range (65 thousands), if a 16-bit CCD detector is expected.
</p>

<p>
  <span class="par">Result Precision</span>
  More detailed analysis can be performed with help of the complete
  photometry calibration:
</p>
<pre>
$ munipack find artificial.fits
$ munipack aphot artificial.fits
$ munipack phcal -c cone.fits --photsys-ref Johnson --area 0.3 \
                 -f V --col-mag Vmag --col-magerr e_Vmag artificial.fits
</pre>

<p>
  The result in <samp>artificial_cal.fits</samp> gives for
  magnitude of the blazar 14.23 ± 0.01 with good agreement
  with catalogue value 14.2 ± 0.4 (note use of parameter
  <samp>--col-mag</samp> which
  is important here). The error due to photon noise is relative
  high and longer exposure duration can be recommend. Moreover,
  the used quantum efficiency only 2% (!) is extremely low and
  an technical improvement in apparatus can be recommended.
</p>



<h2>Atmospheric Effect Modelling</h2>

<p>
  Light rays passing Earth's atmosphere are scattered, reflected
  and attenuated proportionally to the length its path in the atmosphere.
  The atmosphere related effects, which are modelled, includes
  both atmospheric extinction and seeing and sky background dependence.
  The atmospheric refraction is excluded.
</p>

<p>
  The effects are considered just if <samp>--atmosphere</samp>
  switch is presented. Only the extinction parameter (<samp>--extk</samp>)
  can be adjusted (see <a href="man_artificial.html">manual page</a>).
  The proper set up of observation station and time
  (<samp>--long, --lat, --date, --time </samp>) is necessary.
</p>

<p>
  To show the capability, we will prepare of a sequence of seven frames,
  each 1 s, separated by one hour interval which demonstrate atmospheric
  effects on BL Lac blazar field during its down somewhere in central Europe.
  The figure below shows two selected output frames.
</p>
<pre>
$ munipack cone -r 0.2 -- 330.68 42.27
$ munipack artificial --verbose --fov 0.3 -c cone.fits --rcen 330.68 --dcen 42.27 \
                      --mask 'art_?.fits' --lat 50 --long -15 --date 2016-08-29 \
                      --time 00:00:00.000 --count 7 --timestep 3600 --exptime 1 \
                      --atmosphere --extk 0.1 --width 315 --height 510
</pre>


<table>
<tr>
<td class="blank">
<figure>
<img src="bllac_art1.jpeg" alt="bllac_art1.jpeg" title="Artificial BL Lac">
<figcaption>BL Lac field near zenith</figcaption>
</figure>
</td>
<td class="blank">
<figure>
<img src="bllac_art7.jpeg" alt="bllac_art7.jpeg" title="Artificial BL Lac">
<figcaption>BL Lac field 20° above horizon</figcaption>
</figure>
</td>
</tr>
</table>

<p>
<!--  Both extinction and seeing is modeled as desicibes manual page.-->
The actual value of the radius of seeing core is determined from <samp>--hwhm</samp>
option.
The radius represents spreading of a star image by turbulent motions
in Earth atmosphere. The turbulence is very unpredictable. The fact
is known to observers at moments when "focusing is impossible".
It also confirms the experience that the best focusing is near zenith.
</p>

<h2 id="lc">Light Curves</h2>

<p>
  Light curves extracted from generated frames can be used for
  training purposes as well as testing of various processing algorithms.
</p>

<p>
  There are more ways to specify a light curve.
  We will select the most common way.
  The light curve pattern can be included in a table with twines:
  time, magnitude (detailed description by <a href="dataform_tmseries.html">Times
    series</a> document). The table is used to create a required light curve.
  Points located out of tabulated values are interpolated by
  <a href="https://en.wikipedia.org/wiki/Smoothing_spline">smooth spline</a>.
</p>

<p>
  As the model data, I selected a light curve extracted from article
  <a href="https://phys.org/news/2011-11-planet-kepler-21b.html">New planet
    -- Kepler-21b -- discovered (physrev.org)</a>. The weighted original data
  (the plus or star symbol in blue by the paper) are used but I changed significantly
  the deep of the occultation.
  Therefore only the shape of light curve is similar to original. Everything
  else is my personal choice (period,...).
</p>

<p>
  The first step is preparation of the data to form (FITS file) required
  by the utility. The easy way is modification
  of <a href="Kepler-21b.lst">Kepler-21b.lst</a> file:
</p>
<pre>
0 1.00714
0.0245776 1.00714
0.0506912 0.953571
0.0768049 1.03393
....
</pre>
<p>
  The data can be replaced any another set. The number of rows must
  corresponds with NAXIS2 keyword. When the file is prepared, create
  FITS table (note that FITS table can be also created by any other way):
</p>
<pre>
$ munipack fits --restore Kepler-21b.lst
</pre>
<p>
  No catalogue is used here with contrast to previous examples of modelling.
  The background field stars are random in both positions and brightness.
  The picture looks artificially because stars are limited by 13 magnitude.
  The frame is not the actual field of Kepler 21b in any case!
</p>

<p>
  Light curve related parameters starts with <samp>--lc-</samp>
  and defines equatorial coordinates <samp>--lc-ra, --lc-dec</samp>
  of a variable object (there exactly in the centre of frame),
  magnitude <samp>--lc-mag</samp> and the light elements
  <samp>--lc-jd0, --lc-per</samp> (the created sequence of frames
  covers the full period).
</p>

<pre>
$ munipack artificial --verbose --mask 'art_??.fits' --fov 0.3 --rcen 150 --dcen 50 \
         --date 2017-07-14 --time 00:00:00 --count 48 --timestep 180 --exptime 60 \
  	 --lc-table Kepler-21b.fits --lc-mag 12 --lc-jd0 2457948.5 --lc-per 0.1 \
         --lc-ra 150 --lc-dec 50
</pre>

<figure>
<img class="figure" src="Kepler_art.jpeg" alt="Kepler_art.jpeg" title="Kepler-21b">
<figcaption>Artificial frame of Kepler-21b.</figcaption>
</figure>

<p>
  The artificial frames can be processed by the same way how frames
  which has been taken on the real sky. The processing
  skips photometric corrections (like bias frames) and the astrometry
  calibration which is already included. There is no
  photometry catalogue, so I referenced all frames against the first
  (by random choice) frame in sequence. There are the processing steps:
</p>
<pre>
$ munipack find art_??.fits
$ munipack aphot art_??.fits
$ munipack phcal -C 1 --photsys-ref Johnson -f V -O --mask '\!\1_man.\2' art_01.fits
$ ls art_??.fits | xargs -L 1 munipack phcal --photsys-ref Johnson -f V -r art_01_man.fits
$ munipack timeseries -c MAG,MAGERR --stdout 150,50 art_*_cal.fits > Kepler-21b.lc
</pre>

<figure>
<img class="figure" src="Kepler-21b.svg" alt="Kepler-21b.svg" title="Kepler-21b">
<figcaption>The artificial light curve and the model of Kepler-21b.</figcaption>
</figure>



<p>
  The graph shows small visible offset between model and data curve.
  The slight difference due to some improper normalisation in model data
  is a potential trap.
</p>

<p>
  Tip. It is very instructive to play with shorter or longer exposures to discover
  a noise contribution.
</p>


<h2>See Also</h2>


<p>
Manuals:
<a href="man_artificial.html">Artificial frames</a>.
<a href="http://physics.muni.cz/~hroch/artific.pdf">Artificial Sky …</a> (seminary talk)
</p>

<footer>
<div style="float:left; margin-left:2em;">
Copyright &copy; 1997 – 2018
Filip Hroch (<a style="text-decoration: none" href="mailto:hroch@physics.muni.cz?Subject=Munipack" title="Author's Email">✉</a>), license <a href="http://www.gnu.org/licenses/gpl.html">GPLv3</a>.
</div>
<div style="float:right; margin-right:2em; margin-top:-0.2em;">
<a href="http://monteboo.blogspot.com/search/label/Munipack" title="Munipack on MonteBoo Blog"><img src="favicon-blogger.png" alt="Blogger"></a>
<a href="http://www.muni.cz/?lang=en" title="Masaryk University in Brno, Czech Republic"><img src="mu-logo.png" alt="Masaryk University"></a>
<a href="news_feed.xml" title="Munipack's Releases in Atom Syndication Format"><img src="Feed-icon.png" alt="Atom Feed"></a>
</div>
</footer>

</body>
</html>
munipack-doc 0.5.10-1 / usr / share / doc / munipack / artific.html
