def instrument_simulator(input_events,
out_file,
exp_time,
instrument,
sky_center,
overwrite=False,
instr_bkgnd=True,
foreground=True,
ptsrc_bkgnd=True,
bkgnd_file=None,
no_dither=False,
dither_params=None,
roll_angle=0.0,
subpixel_res=False,
aimpt_shift=None,
prng=None):
"""
Take unconvolved events and create an event file from them. This
function calls generate_events to do the following:
1. Determines which events are observed using the ARF
2. Pixelizes the events, applying PSF effects and dithering
3. Determines energy channels using the RMF
and then calls make_background to add instrumental and astrophysical
backgrounds, unless a background file is provided, in which case
the background events are read from this file. The events are
then written out to a file.
Parameters
----------
input_events : string, dict, or None
The unconvolved events to be used as input. Can be one of the
following:
1. The name of a SIMPUT catalog file.
2. A Python dictionary containing the following items:
"ra": A NumPy array of right ascension values in degrees.
"dec": A NumPy array of declination values in degrees.
"energy": A NumPy array of energy values in keV.
"flux": The flux of the entire source, in units of erg/cm**2/s.
out_file : string
The name of the event file to be written.
exp_time : float, (value, unit) tuple, or :class:`~astropy.units.Quantity`
The exposure time to use, in seconds.
instrument : string
The name of the instrument to use, which picks an instrument
specification from the instrument registry.
sky_center : array, tuple, or list
The center RA, Dec coordinates of the observation, in degrees.
overwrite : boolean, optional
Whether or not to overwrite an existing file with the same name.
Default: False
instr_bkgnd : boolean, optional
Whether or not to include the instrumental/particle background.
Default: True
foreground : boolean, optional
Whether or not to include the local foreground.
Default: True
ptsrc_bkgnd : boolean, optional
Whether or not to include the point-source background.
Default: True
bkgnd_file : string, optional
If set, backgrounds will be loaded from this file and not generated
on the fly. Default: None
no_dither : boolean, optional
If True, turn off dithering entirely. Default: False
dither_params : array-like of floats, optional
The parameters to use to control the size and period of the dither
pattern. The first two numbers are the dither amplitude in x and y
detector coordinates in arcseconds, and the second two numbers are
the dither period in x and y detector coordinates in seconds.
Default: [8.0, 8.0, 1000.0, 707.0].
roll_angle : float, (value, unit) tuple, or :class:`~astropy.units.Quantity`, optional
The roll angle of the observation in degrees. Default: 0.0
subpixel_res: boolean, optional
If True, event positions are not randomized within the pixels
within which they are detected. Default: False
aimpt_shift : array-like, optional
A two-float array-like object which shifts the aimpoint on the
detector from the nominal position. Units are in arcseconds.
Default: None, which results in no shift from the nominal aimpoint.
prng : :class:`~numpy.random.RandomState` object, integer, or None
A pseudo-random number generator. Typically will only
be specified if you have a reason to generate the same
set of random numbers, such as for a test. Default is None,
which sets the seed based on the system time.
Examples
--------
>>> instrument_simulator("sloshing_simput.fits", "sloshing_evt.fits",
... 300000.0, "lynx_hdxi", [30., 45.], overwrite=True)
"""
from soxs.background import add_background_from_file
if not out_file.endswith(".fits"):
out_file += ".fits"
mylog.info(f"Making observation of source in {out_file}.")
# Make the source first
events, event_params = generate_events(input_events,
exp_time,
instrument,
sky_center,
no_dither=no_dither,
dither_params=dither_params,
roll_angle=roll_angle,
subpixel_res=subpixel_res,
aimpt_shift=aimpt_shift,
prng=prng)
# If the user wants backgrounds, either make the background or add an already existing
# background event file. It may be necessary to reproject events to a new coordinate system.
if bkgnd_file is None:
if not instr_bkgnd and not ptsrc_bkgnd and not foreground:
mylog.info("No backgrounds will be added to this observation.")
else:
mylog.info("Adding background events.")
bkg_events, _ = make_background(exp_time,
instrument,
sky_center,
foreground=foreground,
instr_bkgnd=instr_bkgnd,
no_dither=no_dither,
dither_params=dither_params,
ptsrc_bkgnd=ptsrc_bkgnd,
prng=prng,
subpixel_res=subpixel_res,
roll_angle=roll_angle,
aimpt_shift=aimpt_shift)
for key in events:
events[key] = np.concatenate([events[key], bkg_events[key]])
else:
mylog.info(f"Adding background events from the file {bkgnd_file}.")
if not os.path.exists(bkgnd_file):
raise IOError(
f"Cannot find the background event file {bkgnd_file}!")
events = add_background_from_file(events, event_params, bkgnd_file)
if len(events["energy"]) == 0:
raise RuntimeError(
"No events were detected from source or background!!")
write_event_file(events, event_params, out_file, overwrite=overwrite)
mylog.info("Observation complete.")
def instrument_simulator(input_events, out_file, exp_time, instrument,
sky_center, overwrite=False, instr_bkgnd=True,
foreground=True, ptsrc_bkgnd=True,
bkgnd_file=None, no_dither=False,
dither_params=None, roll_angle=0.0,
subpixel_res=False, prng=None):
"""
Take unconvolved events and create an event file from them. This
function calls generate_events to do the following:
1. Determines which events are observed using the ARF
2. Pixelizes the events, applying PSF effects and dithering
3. Determines energy channels using the RMF
and then calls make_background to add instrumental and astrophysical
backgrounds, unless a background file is provided, in which case
the background events are read from this file. The events are
then written out to a file.
Parameters
----------
input_events : string, dict, or None
The unconvolved events to be used as input. Can be one of the
following:
1. The name of a SIMPUT catalog file.
2. A Python dictionary containing the following items:
"ra": A NumPy array of right ascension values in degrees.
"dec": A NumPy array of declination values in degrees.
"energy": A NumPy array of energy values in keV.
"flux": The flux of the entire source, in units of erg/cm**2/s.
out_file : string
The name of the event file to be written.
exp_time : float, (value, unit) tuple, or :class:`~astropy.units.Quantity`
The exposure time to use, in seconds.
instrument : string
The name of the instrument to use, which picks an instrument
specification from the instrument registry.
sky_center : array, tuple, or list
The center RA, Dec coordinates of the observation, in degrees.
overwrite : boolean, optional
Whether or not to overwrite an existing file with the same name.
Default: False
instr_bkgnd : boolean, optional
Whether or not to include the instrumental/particle background.
Default: True
foreground : boolean, optional
Whether or not to include the local foreground.
Default: True
ptsrc_bkgnd : boolean, optional
Whether or not to include the point-source background.
Default: True
bkgnd_file : string, optional
If set, backgrounds will be loaded from this file and not generated
on the fly. Default: None
no_dither : boolean, optional
If True, turn off dithering entirely. Default: False
dither_params : array-like of floats, optional
The parameters to use to control the size and period of the dither
pattern. The first two numbers are the dither amplitude in x and y
detector coordinates in arcseconds, and the second two numbers are
the dither period in x and y detector coordinates in seconds.
Default: [8.0, 8.0, 1000.0, 707.0].
roll_angle : float, (value, unit) tuple, or :class:`~astropy.units.Quantity`, optional
The roll angle of the observation in degrees. Default: 0.0
subpixel_res: boolean, optional
If True, event positions are not randomized within the pixels
within which they are detected. Default: False
prng : :class:`~numpy.random.RandomState` object, integer, or None
A pseudo-random number generator. Typically will only
be specified if you have a reason to generate the same
set of random numbers, such as for a test. Default is None,
which sets the seed based on the system time.
Examples
--------
>>> instrument_simulator("sloshing_simput.fits", "sloshing_evt.fits",
... 300000.0, "hdxi_3x10", [30., 45.], overwrite=True)
"""
from soxs.background import add_background_from_file
if not out_file.endswith(".fits"):
out_file += ".fits"
mylog.info("Making observation of source in %s." % out_file)
# Make the source first
events, event_params = generate_events(input_events, exp_time, instrument, sky_center,
no_dither=no_dither, dither_params=dither_params,
roll_angle=roll_angle, subpixel_res=subpixel_res,
prng=prng)
# If the user wants backgrounds, either make the background or add an already existing
# background event file. It may be necessary to reproject events to a new coordinate system.
if bkgnd_file is None:
if not instr_bkgnd and not ptsrc_bkgnd and not foreground:
mylog.info("No backgrounds will be added to this observation.")
else:
mylog.info("Adding background events.")
bkg_events, _ = make_background(exp_time, instrument, sky_center,
foreground=foreground, instr_bkgnd=instr_bkgnd,
no_dither=no_dither, dither_params=dither_params,
ptsrc_bkgnd=ptsrc_bkgnd, prng=prng,
subpixel_res=subpixel_res, roll_angle=roll_angle)
for key in events:
events[key] = np.concatenate([events[key], bkg_events[key]])
else:
mylog.info("Adding background events from the file %s." % bkgnd_file)
if not os.path.exists(bkgnd_file):
raise IOError("Cannot find the background event file %s!" % bkgnd_file)
events = add_background_from_file(events, event_params, bkgnd_file)
if len(events["energy"]) == 0:
raise RuntimeError("No events were detected from source or background!!")
write_event_file(events, event_params, out_file, overwrite=overwrite)
mylog.info("Observation complete.")
def make_background_file(out_file,
exp_time,
instrument,
sky_center,
overwrite=False,
foreground=True,
instr_bkgnd=True,
ptsrc_bkgnd=True,
no_dither=False,
dither_params=None,
subpixel_res=False,
input_sources=None,
absorb_model="wabs",
nH=0.05,
prng=None):
"""
Make an event file consisting entirely of background events. This will be
useful for creating backgrounds that can be added to simulations of sources.
Parameters
----------
exp_time : float, (value, unit) tuple, or :class:`~astropy.units.Quantity`
The exposure time to use, in seconds.
instrument : string
The name of the instrument to use, which picks an instrument
specification from the instrument registry.
sky_center : array, tuple, or list
The center RA, Dec coordinates of the observation, in degrees.
overwrite : boolean, optional
Whether or not to overwrite an existing file with the same name.
Default: False
foreground : boolean, optional
Whether or not to include the Galactic foreground. Default: True
instr_bkgnd : boolean, optional
Whether or not to include the instrumental background. Default: True
ptsrc_bkgnd : boolean, optional
Whether or not to include the point-source background. Default: True
no_dither : boolean, optional
If True, turn off dithering entirely. Default: False
dither_params : array-like of floats, optional
The parameters to use to control the size and period of the dither
pattern. The first two numbers are the dither amplitude in x and y
detector coordinates in arcseconds, and the second two numbers are
the dither period in x and y detector coordinates in seconds.
Default: [8.0, 8.0, 1000.0, 707.0].
subpixel_res: boolean, optional
If True, event positions are not randomized within the pixels
within which they are detected. Default: False
input_sources : string, optional
If set to a filename, input the point source positions, fluxes,
and spectral indices from an ASCII table instead of generating
them. Default: None
absorb_model : string, optional
The absorption model to use, "wabs" or "tbabs". Default: "wabs"
nH : float, optional
The hydrogen column in units of 10**22 atoms/cm**2.
Default: 0.05
prng : :class:`~numpy.random.RandomState` object, integer, or None
A pseudo-random number generator. Typically will only
be specified if you have a reason to generate the same
set of random numbers, such as for a test. Default is None,
which sets the seed based on the system time.
"""
prng = parse_prng(prng)
events, event_params = make_background(exp_time,
instrument,
sky_center,
ptsrc_bkgnd=ptsrc_bkgnd,
foreground=foreground,
instr_bkgnd=instr_bkgnd,
no_dither=no_dither,
dither_params=dither_params,
subpixel_res=subpixel_res,
input_sources=input_sources,
absorb_model=absorb_model,
nH=nH,
prng=prng)
write_event_file(events, event_params, out_file, overwrite=overwrite)
def make_background_file(out_file, exp_time, instrument, sky_center,
overwrite=False, foreground=True, instr_bkgnd=True,
ptsrc_bkgnd=True, no_dither=False, dither_params=None,
subpixel_res=False, input_sources=None,
absorb_model="wabs", nH=0.05, prng=None):
"""
Make an event file consisting entirely of background events. This will be
useful for creating backgrounds that can be added to simulations of sources.
Parameters
----------
exp_time : float, (value, unit) tuple, or :class:`~astropy.units.Quantity`
The exposure time to use, in seconds.
instrument : string
The name of the instrument to use, which picks an instrument
specification from the instrument registry.
sky_center : array, tuple, or list
The center RA, Dec coordinates of the observation, in degrees.
overwrite : boolean, optional
Whether or not to overwrite an existing file with the same name.
Default: False
foreground : boolean, optional
Whether or not to include the Galactic foreground. Default: True
instr_bkgnd : boolean, optional
Whether or not to include the instrumental background. Default: True
ptsrc_bkgnd : boolean, optional
Whether or not to include the point-source background. Default: True
no_dither : boolean, optional
If True, turn off dithering entirely. Default: False
dither_params : array-like of floats, optional
The parameters to use to control the size and period of the dither
pattern. The first two numbers are the dither amplitude in x and y
detector coordinates in arcseconds, and the second two numbers are
the dither period in x and y detector coordinates in seconds.
Default: [8.0, 8.0, 1000.0, 707.0].
subpixel_res: boolean, optional
If True, event positions are not randomized within the pixels
within which they are detected. Default: False
input_sources : string, optional
If set to a filename, input the point source positions, fluxes,
and spectral indices from an ASCII table instead of generating
them. Default: None
absorb_model : string, optional
The absorption model to use, "wabs" or "tbabs". Default: "wabs"
nH : float, optional
The hydrogen column in units of 10**22 atoms/cm**2.
Default: 0.05
prng : :class:`~numpy.random.RandomState` object, integer, or None
A pseudo-random number generator. Typically will only
be specified if you have a reason to generate the same
set of random numbers, such as for a test. Default is None,
which sets the seed based on the system time.
"""
prng = parse_prng(prng)
events, event_params = make_background(exp_time, instrument, sky_center,
ptsrc_bkgnd=ptsrc_bkgnd,
foreground=foreground,
instr_bkgnd=instr_bkgnd,
no_dither=no_dither,
dither_params=dither_params,
subpixel_res=subpixel_res,
input_sources=input_sources,
absorb_model=absorb_model,
nH=nH, prng=prng)
write_event_file(events, event_params, out_file, overwrite=overwrite)