Xstack: X-ray Spectral Stacking

:checkered_flag: If you are in a hurry, please jump to this link for installation, and this link for basic usage of this code. Demo notebook gives you a quick walk-through of Xstack.

For more information, please check our documentation (still in progress)!

:pirate_flag: What is Xstack ?

Xstack is a comprehensive standalone pipeline code for X-ray spectral (rest-frame) shifting and stacking.

In the era of eROSITA All Sky X-ray Survey (eRASS), the code should be very useful, if you have a special sample (point or extended sources) selected in other bands (infra-red color, optical line/line ratios, variability, etc), and you would like to see how their averaged X-ray spectral shape looks like. You simply download your targets' spectra from eROSITA archive, and Xstack them (see below for examples).

:bulb: How Xstack works: a very brief introduction

Difficulties, and solutions

X-ray spectral stacking is non-trivial compared to optical spectral stacking. The difficulties arise from two facts:

:cold_sweat: X-ray has much fewer photon counts (Poisson), meaning that spectral counts and uncertainties cannot be scaled simultaneously (as compared to optical);

:cold_sweat: X-ray has non-diagonal, complex response, meaning that the response needs to be taken into account when stacking.

To tackle these issues, we develop Xstack: a standalone pipeline code for X-ray spectral stacking. The methodology is to first sum all (rest-frame) PI spectra, without any scaling; and then sum the response files (ARFs and RMFs), each with appropriate weighting factors to preserve the overall spectral shape. The preservation of Poisson statistics for the data (and Gaussian for the background) ensures the validity of subsequent spectral fitting (via e.g., XSPEC).

Key features of Xstack

:star_struck: properly preserve X-ray spectral shape, by assigning optimal (data-driven) response weighting factors;

:star_struck: preserve Poisson statistics;

:star_struck: support Galactic absorption correction, if an additional nH value (in units of 1 $\text{cm}^{-2}$) for each spectrum is given.

You can find in the appendix of S. Chen, J. Bucher, T. Liu, et al., 2025, A&A, 701, A144 (2025) more technical details!

:wrench: Prerequisites and Installation

To install Xstack (along with the prerequisite packages), simply put:

git clone https://github.com/AstroChensj/Xstack.git
cd Xstack
python -m pip install .

python -m ensures that all required packages are installed for your current conda environment only (i.e., the path where your python is called, which python).

Troubleshooting:

If you encounter network issues (e.g., Port 443) when installing with https, try ssh instead (see this link for setup of github ssh):
```
ssh -T git@github.com
git clone git@github.com:AstroChensj/Xstack.git
```

:ledger: How to use Xstack

Stacking X-ray spectra with Xstack is simple: you can either call it from command line, or invoke it as a python module.

In either case, Xstack requires the following as input:

individual source PI spectra, with proper headers following OGIP standards; additional redshift file (with .z extension) and Galactic nH file (with .nh extension) under the same directory as each source PI spectrum;
- An example of .nh file:
```
119000000000000000000.000000
```
- An example of .z file:
```
0.1
```
background PI spectra (with proper BACKSCAL parameters);
effective area curve ARFs (extracted for source region);
and response matrix RMFs.

The output will be:

stacked source PI spectrum;
stacked background BKGPI spectrum (already scaled);
stacked ARF;
stacked RMF;
and first contributing energy file FENE.

All stacked FITS outputs also include command provenance in HISTORY cards, storing the executed CLI command.

New in same_target mode: you can stack multiple exposures of one target directly in observed frame. In this mode, Xstack skips rest-frame shifting, Galactic NH correction, and pre-scaling of background PI.

:one: Command line version

A simple and quick example:
```
runXstack your_filelist.txt --prefix ./results/stacked_
```
- And you will get the stacked spectra ./results/stacked_pi.fits, ./results/stacked_bkgpi.fits, and stacked response files ./results/stacked_arf.fits, ./results/stacked_rmf.fits, and ./results/stacked_fene.fits which stores the first contributing energy of each individual source.
- runXstack is the alias for python3 /path/to/your/Xstack/Xstack_scripts/Xstack_autoscript.py, which should be set automatically after python -m pip install ..
- your_filelist.txt stores the absolute path of the PI spectrum file for each source. The PI spectrum should follow OGIP standards – its header (of extension SPECTRUM) should have keywords helping Xstack to find the corresponding bkg PI spectrum file (BACKFILE), the RMF (RESPFILE) and ARF (ANCRFILE). An example of your_filelist.txt would be:
```
/path/to/your/PI_001.fits
/path/to/your/PI_002.fits
/path/to/your/PI_003.fits
# ...
```
 Note that under each directory, it is assumed there exist a redshift file and Galactic nH file, with naming convention like /path/to/your/PI_001.fits.z and /path/to/your/PI_001.fits.nh. The redshift value and Galactic nH value ([1 cm^-2]) are stored in these two files, separately.
- 1.0 and 2.3 are lower/upper end of the energy range [keV] for computing flux. The flux represents the contribution from each source’s PI spectrum to the total stacked spectrum, and will be used as the weighting factors when stacking ARFs/RMFs.
- SHP is the response weighting method, assuming all sources to be stacked have the same spectral shape (the minimum assumption). Under this method, the response weighting factor is calculated from flux (in a data-driven way).
Or more sophisticatedly, specify more parameters:
```
runXstack your_filelist.txt --prefix ./results/stacked_ --rsp_weight_method SHP --rsp_proj_gamma 2.0 --flux_energy_lo 1.0 --flux_energy_hi 2.3 --nthreads 20 --ene_trc 0.2 --extended --same_rmf AllSourcesUseSameRMF.rmf
```
- nthreads specifies the number of CPUs used for shifting RMF.
- ene_trc specifies the energy (keV) below which the ARF is unreliable and should manually be truncated. For example, for eROSITA there may be some calibration issues below 0.2 keV, so you can set this parameter to 0.2.
- use --extended only if you are stacking extended sources (methods following X. Zhang+2024)
- same_rmf : the RMF files are usually large, and sometimes all sources to be stacked could share the same RMF in order to save space. Under this case, you can specify the file name of the common RMF with same_rmf.

If you want to do bootstrap, that is also easy:

runXstack your_filelist.txt --prefix ./results/stacked_ --rsp_weight_method SHP --rsp_proj_gamma 2.0 --flux_energy_lo 1.0 --flux_energy_hi 2.3 --nthreads 20 --ene_trc 0.2 --extended --same_rmf AllSourcesUseSameRMF.rmf --bootstrap --num_bootstrap 100

If your filelist contains multiple exposures of the same target, use same_target mode:
```
runXstack your_filelist.txt --prefix ./results/stacked_ --same_target
```
- In this mode:
  - source/background PI are summed directly (integer counts preserved at output);
  - full response (ARF*RMF) is stacked with FLX weighting;
  - stacked EXPOSURE is the summed exposure;
  - stacked src/bkg AREASCAL, BACKSCAL, CORRSCAL are written as means of inputs;
  - if var(x/mean(x)) is large for any of these three scale keywords, a warning is written in the log file.
You can run runXstack -h to get the documentation of all the above parameters. Or equivalently check below:

| Parameters | Description | Default values| |---|---|---| |filelist|text file containing the file names|--| |--prefix|prefix for output stacked PI, BKGPI, ARF, and RMF files|./results/stacked_| |--rsp_weight_method|method to calculate RSP weighting factor for each source; 'SHP': assuming all sources have same spec

Xstack

Install / Use

README

Xstack: X-ray Spectral Stacking

:pirate_flag: What is <span style="font-family: 'Courier New', Courier, monospace; font-weight: 700;">Xstack</span> ?

:bulb: How <span style="font-family: 'Courier New', Courier, monospace; font-weight: 700;">Xstack</span> works: a very brief introduction

Difficulties, and solutions

Key features of <span style="font-family: 'Courier New', Courier, monospace; font-weight: 700;">Xstack</span>

:wrench: Prerequisites and Installation

:ledger: How to use <span style="font-family: 'Courier New', Courier, monospace; font-weight: 700;">Xstack</span>

:one: Command line version

Related Skills