Users guide

Configuration

You can use the Get the default config file command-line tool

iact-estimator config --to /where/to/save/config/file

to get the following example configuration file,

target_source:
  name: "Crab Nebula"
  coordinates:
    force: false # force use of custom coordinates for sources found also by name
    ra_l:
    dec_b:
    frame:
  assumed_model:
    # see https://docs.gammapy.org/1.1/user-guide/model-gallery/index.html#spectral-models
    name: gammapy.modeling.models.LogParabolaSpectralModel
    parameters:
      amplitude: 3.39e-11 TeV^-1 cm^-2 s^-1
      reference: 1 TeV
      alpha: 2.51
      beta: 0.21
    from_log10: True # relevant for e.g. LogParabolaSpectralModel

observer:
  # use any available location from astropy.coordinates.EarthLocation.get_site_names
  # overrides manual initialization
  auto: "Roque de los Muchachos"
  # or initialize one from scratch
  # see https://astroplan.readthedocs.io/en/latest/api/astroplan.Observer.html for details
  manual:
    timezone: "UTC"
    name:
    latitude:
    longitude:
    elevation:

observation:
  constraints:
    moon_illumination_fraction:
      max: 0.2
      min:
      ephemeris:
    moon_separation:
      # https://astroplan.readthedocs.io/en/latest/api/astroplan.MoonSeparationConstraint.html#astroplan.MoonSeparationConstraint
      min: "45 deg"
      max:
      ephemeris:
    zenith:
      min: "0 deg"
      max: "60 deg"
    max_solar_altitude: "-18 deg"
  time: "50 h"
  start_datetime: # default to today
  end_datetime: # default to 1 year from today
  time_resolution: "1 h"

wobbles:
  fov_offsets: 0.4 # deg
  position_angles: [0, 90, 180, 270] # deg

extension: 0.0 deg
redshift: -1 # redshift of the source (for the EBL absorption), if -1 then no absorption
sum_trigger: False

# see documentation for a table of publicly available
# values
# For private data, these values should come with the
# metadata of your file
instrument: "MAGIC"
fov: 3.5 deg
zenith_range: "low"
magic_lst1: True
# you can check visibility of your source e.g. here: http://www.magic.iac.es/scheduler/

ebl_file_path:

n_off_regions: 3 # number of background estimation regions
min_number_events: 10.0 # minimum number of events
min_ratio_signal_background: 0.05 # minimum ratio of excess to background

PSF: "0.1 deg" # PSF for worsening the performance for extended sources
offset_degradation_factor: 1.0 # degradation factor if observations are taken at higher offset then 0.4 deg from camera center

pulsar_mode:
  enable: False # if true the background is reduced to on phase (see below) and SBR cut is ignored
  pulsar_on_range: 0.092 # range of ON phases used for pulsar mode
  pulsar_off_range: 0.25 # range of OFF phases used for pulsar mode# global variables (DO NOT MODIFY)

plotting_options:
  show: False
  figure_size: [20, 10]
  bbox_inches: "tight"
  min_energy: "40 GeV"
  max_energy: "20 TeV"
  energy_unit: "TeV"
  energy_flux_unit: "TeV cm^-2 s^-1"
  min_error: 2 # showing only points with value > minerror * error
  draw_sigma: True # whether to draw also sigmas on the plot# pulsar mode settings
  n_points: 15
  file_format: "pdf"
  merge_horizon_profiles: True

skyview:
  save_hdus: True
  surveys:
    - name: "DSS"
      fov_radius: "10 arcmin"
      log: False
      reticle: False
      style_kwargs: { "cmap": "viridis" }
      reticle_style_kwargs: { "color": "white", "lw": 2 }
    - name: "GB6 (4850MHz)"
      fov_radius: "10 arcmin"
      log: False
      reticle: False
      style_kwargs: { "cmap": "viridis" }
      reticle_style_kwargs: { "color": "white", "lw": 2 }

use_seaborn: True
seaborn_options:
  context: talk
  style: whitegrid
  palette: viridis
  font: sans-serif
  font_scale: 1
  color_codes: True
  rc:
    "xtick.bottom": True
    "ytick.left": True

wobble_skymap_plot_options:
  wobbles_colormap: "tab10"
  map_color_scheme: "BLUE_LIGHT"
  legend:
    location: "outside right upper"
    num_columns: 1
    background_alpha: 1
  magnitude:
    danger: 5
    max: 30
  target_source:
    marker:
      size: 15
      symbol: "star"
      fill: "full"
      color: "#ed7eed"
      edge_color: "#e0c1e0"
      alpha: 0.4
  export:
    format: "png" # "png", "jpeg", or "svg"
    padding: 0.3
    transparent: True

Launch the simulation

You can use the Run the estimation process command-line tool to simulate the response of the telescope(s) to the input source settings.

To produce the output in the current working directory for a source named “my_source”,

iact-estimator run --config config.yml --source-name my_source

For detailed information about all possible options, please consult the Reference API or issue the help command with iact-estimator run -h.

Using custom performance data

If you want to use your own performance data, either for testing or because it is still not published, you can load it from an ECSV with the format shown below.

Producing such a table is very easy with astropy starting from the array quantities containing the data, for example,

from astropy.table import QTable
import astropy.units as u
import numpy as np

table = QTable([min_energy, max_energy, gamma_rate, bkg_rate],
                names=("min_energy", "max_energy", "gamma_rate", "background_rate"),
                meta={"name":"some_descriptive_title"})
table.write("my_performance.ecsv")

this will result in a data file similar to this,

# %ECSV 1.0
# ---
# datatype:
# - {name: min_energy, unit: GeV, datatype: float64}
# - {name: max_energy, unit: GeV, datatype: float64}
# - {name: gamma_rate, unit: 1 / min, datatype: float64}
# - {name: background_rate, unit: 1 / min, datatype: float64}
# meta:
#   __serialized_columns__:
#     background_rate:
#       __class__: astropy.units.quantity.Quantity
#       unit: !astropy.units.Unit {unit: 1 / min}
#       value: !astropy.table.SerializedColumn {name: background_rate}
#     gamma_rate:
#       __class__: astropy.units.quantity.Quantity
#       unit: !astropy.units.Unit {unit: 1 / min}
#       value: !astropy.table.SerializedColumn {name: gamma_rate}
#     max_energy:
#       __class__: astropy.units.quantity.Quantity
#       unit: &id001 !astropy.units.Unit {unit: GeV}
#       value: !astropy.table.SerializedColumn {name: max_energy}
#     min_energy:
#       __class__: astropy.units.quantity.Quantity
#       unit: *id001
#       value: !astropy.table.SerializedColumn {name: min_energy}
#   name: some_descriptive_title
# schema: astropy-2.0
min_energy max_energy gamma_rate background_rate
39.8 63.1 0.818446 3.66424

You can then load it using the –performance flag of Run the estimation process to tell the command-line tool where to find the data file.

Output

Terminal

For each estimated energy range one gets the number of excess events, signal-to-background ratio, significance, and information if a given bin satisfies the conditions for the detection.

Plots

Tha package comes with a small plotting library that allows to plot information about the observability of the source and its spectral properties as seen by the telescopes.

Some of these functions are called by the main script, but all of them can be imported separately e.g. in a notebook (see the interactive example).

For a complete list of plotting functions, see iact_estimator.plots.