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)