DAMPE Tools >>User Guide
DmpST Document
| Source： | Pubtime：2021-08-31 |
1. What is DmpST
DAMPE Science Tools (DmpST) is a software for gamma-ray data analysis of DAMPE. It depends on the photon events, spacecraft file, instrument response functions (IRFs) and assumed model of gamma-ray sources to do the analysis. It allows users to select photons based on the direction, time, energy, and trigger type, calculate the exposure of DAMPE observation over the sky, and analyze the flux and error (or upper limit), spectrum, confidence, spectral energy distribution (SED) and light curve (LC) of gamma-ray sources based on the selected data.
2. Requirements Library of DmpST
Python == 3.7
numpy == 1.19.5
scipy == 1.5.4
matplotlib == 3.3.3
healpy == 1.14.0
astropy == 4.1
iminuit == 1.3.2
PyYAML == 5.3.1
numba == 0.51.2
3. What are needed for data analysis
(1) photon events: [FITS] selected from the 2A data based on the algorithm. It stores the information of selected photons, including the time of arrive, energy, direction by reconstruction, and the trigger type.
(2) spacecraft file: [FITS] got from housekeeping database. It stores the information of spacecraft, including the time, position, pointing direction and live time for gamma-ray observation.
(3) Instrument response functions (IRFs): [FITS] parameterized from simulation data through the same algorithm with photon selection. It includes effective area, point-spread function and energy dispersion. DAMPE_AEFF.fits, DAMPE_PSF.fits and DAMPE_EDISP.fits are saved in the DmpIRFs folder.
(4) Model of gamma-ray source: [XML or YAML] model of spectrum and spatial distribution of gamma-ray sources which contribute photons to the ROI.
4. Structure of the DmpST
The cyan modules are the input of DmpST, including Events, SpaceCraft, DmpIRFs, Parameter, SpatialModel, Spectrum and Model.
The white modules are the processes of DmpST, including SkyMap, Exposure, Source, LikelihoodBase and Binned/Unbinned Likelihood.
The yellow modules are the output of the DmpST, including Likelihood Analysis and DmpSkyObsSimu.
5. How to do data analysis with DmpST
Before the analysis, user should determine the time range and energy range of the analysis, and pay attention to the observed time of DAMPE for the source and the distribution of events near the source and the counts map.
The script FindObservedTime.py to get the observed time of the target source between UTCmin and UTCmax.
The script GetInfo.py is used to show the distribution of events in the ROI, and the counts map of these events.
python FindObservedTime.py scfile srcName GorC xref yref UTCmin UTCmax
- scfile: name of spacecraft file
- srcName: name of target source
- GorC: ‘G’ for galactic coordinate or ‘C’ for celestial equatorial coordinate
- xref: L in galactic coordinate or RA in celestial equatorial coordinate
- yref: B in galactic coordinate or DEC in celestial equatorial coordinate
- UTCmin: the minimum value of time in UTC system
- UTCmax: the maximum value of time in UTC system
This script will create a folder named with srcName and calculate the angles between the target source and the Z axis of spacecraft to create the ObservedAngle.dat, ObservedTime.dat, UTCbounds.dat, METbounds.dat and ObservedTime.png file. When the angles larger than 60-degree, the target source is not in the field of view of DAMPE.
python GetInfo.py evfile srcName GorC xref yref rad binsz proj emin emax ebins UTCmin UTCmax [Tperiod cosThetamin cosThetamax evtype]
- evfile: name of photon data file
- srcName: name of target source
- GorC: ‘G’ for galactic coordinate or ‘C’ for celestial equatorial coordinate
- xref: L in galactic coordinate or RA in celestial equatorial coordinate
- yref: B in galactic coordinate or DEC in celestial equatorial coordinate
- rad: radius from the target source to show the counts map in degree
- binsz: size of bin for counts map in degree
- proj: projection of counts map, ‘CAR’ or ‘AIT’
- emin: the minimum value of energy to show the energy bin in MeV
- emax: the maximum value of energy to show the energy bin in MeV
- ebins: the number of bins for energy to show the energy bin
- UTCmin: the minimum value of time in UTC system
- UTCmax: the maximum value of time in UTC system
- Tperiod: the number of days in each bin to show the time bin [default: 1]
- cosThetamin: the minimum value of cos theta of photon data [default: 0.5].
- cosThetamax: the maximum value of cos theta of photon data [default: 1.0].
- evtype: event type of photon data, 0 for LET or 1 for HET or 2 for LET and HET data [default: 2].
This script will create the counts map, energy bin, time bin and events map to show the photon information about energy, time, and spatial distributions.
User should determine the ROI for the analysis based on the angular resolution as a function of energy and select events in the ROI. Note that the fitted region is a square centered at the source, the square's edge length should larger than to the 95% PSF. For example, 5 degree is recommended above 3 GeV.
User should calculate the live time cube based on the events and the spacecraft with ltcube.py script.
python Dmpltcube.py scfile evfile outfile [order ordering thetabins phibins zmax nthreads]
- scfile: name of spacecraft file
- evfile: name of photon data file
- outfile: name of output ltcube file
- order: order for healpix bin, [default: 6]
- ordering: ordering scheme of healpix pixels, ‘NESTED’ or ‘RING’ [default: ‘NESTED’]
- thetabins: number of bins for theta [default: 20]
- phibins: number of bins for phi [default: 1]
- zmax: the maximum value for zenith angle [default: 100]
- nthreads: number of threads [default: 1]
This scipt will calculate the live time cube for whole sky used for data analysis.
User should provide the model file named with srcName_input.yaml for data analysis, all the sources which contribute events to the ROI should be included in the model file. DmpST allows most of spectral type model for point sources and some spatial model for extended sources. The galactic diffuse emission template can be downloaded here, an alternative choice is Fermi-LAT’s template. The power-law isotropic emission model is recommended.
DmpST provides the scripts to do the analysis, like BinnedPipeline.py and UnbinnedPipeline.py. As the results of the analysis, users can get the fitted model file and the values/errors of parameters and flux and TS values of sources in YAML format.
python BinnedPipeline.py evfile scfile ltcube path srcName GorC xref yref rad freerad binsz proj emin emax ebins UTCmin UTCmax [cosThetamin cosThetamax evtype irf]
- evfile: name of photon data file
- scfile: name of spacecraft file
- ltcube: name of ltcube file
- path: path name for data analysis
- srcName: name of target source
- GorC: ‘G’ for galactic coordinate or ‘C’ for celestial equatorial coordinate
- xref: L in galactic coordinate or RA in celestial equatorial coordinate
- yref: B in galactic coordinate or DEC in celestial equatorial coordinate
- rad: radius from the target source for data analysis in degree
- freerad: radius from the target source for model fit in degree
- binsz: size of bin for counts map in degree
- proj: projection of counts map, ‘CAR’ or ‘AIT’
- emin: the minimum value of energy for data analysis in MeV
- emax: the maximum value of energy for data analysis in MeV
- ebins: the number of bins for energy for data analysis
- UTCmin: the minimum value of time in UTC system
- UTCmax: the maximum value of time in UTC system
- cosThetamin: the minimum value of cos theta of photon data [default: 0.5].
- cosThetamax: the maximum value of cos theta of photon data [default: 1.0].
- evtype: event type of photon data, 0 for LET or 1 for HET or 2 for LET and HET data [default: 2].
- irf: path of irf file [default: ‘../DmpIRFs’]
For the SED and LC of sources, user can repeat these processes with user-defined energy or time range.
For the TS map of source, DmpST provides srcTSmap option. We assume one point source at each pixel of in the ROI, and refit to get the TS value of the assumed source.
