# 2.2 How Xstack Works

This section is a pedagogical walkthrough of Appendix A.2-A.4 in `2025Chen_Xstack.pdf`, aligned with the implementation in `Xstack/Xstack.py`.

## 2.2.1 Goal Of The Pipeline

Xstack does three things in one pipeline:

1. shift each source to rest frame,
2. stack source and background PI spectra with statistically consistent handling,
3. stack full responses with explicit weighting so spectral shape is preserved.

## 2.2.2 Step 1: Rest-frame Shifting

### PI and background shifting

For each source with redshift $z$, observed-frame channel bins are mapped to rest frame by factor $(1+z)$.
Counts are redistributed to overlapping output bins proportionally to overlap width.

Background PI is shifted the same way as the paired source PI.

### Full-response shifting

Xstack forms full response:

$$
P_{ij} = R_{ij}A_j.
$$

Then it applies two shifts:

1. horizontal shift along output-channel axis (dispersion broadens by $(1+z)$),
2. vertical shift along input-model-energy axis (mapped to rest-frame grid).

Why this matters: PI and response remain physically coupled after shifting.

## 2.2.3 Step 2: Stacking Strategy

- Source PI spectra are summed directly (no per-source flux normalization before summation).
- Background PI spectra are stacked with source-to-background scaling and separate uncertainty treatment.
- Shifted full responses are weighted and summed, then decomposed into stacked ARF and RMF products for fitting.

This gives a final data package similar to single-source spectroscopy:

- stacked PI,
- stacked background PI,
- stacked ARF,
- stacked RMF.

## 2.2.4 Step 3: Weighting Models (Why Three Modes?)

Xstack supports three response-weighting assumptions (`rspwt_method`):

1. `SHP` (recommended):
   - assumes sources share spectral shape,
   - uses data-driven weights from counts and full response over an integration band
     (`int_rng` / CLI `flux_energy_lo`, `flux_energy_hi`),
   - generally least biased for shape recovery in heterogeneous samples.

2. `FLX`:
   - assumes same shape + same flux level,
   - response weights scale mainly with exposure
     (and region-area terms in extended mode).

3. `LMN`:
   - assumes same shape + same luminosity,
   - response weights scale with exposure / distance$^2$
     (plus region-area terms in extended mode).

Pedagogical rule of thumb:

- start from `SHP` unless you have a strong physical reason for `FLX` or `LMN`.

## 2.2.5 Background Treatment And Uncertainty

Background handling is intentionally separate from source stacking:

- background PI is shifted and accumulated with source/background scaling,
- sources are grouped by similar scaling ratio (`Nbkggrp`),
- grouped approximation is used to propagate background uncertainty robustly.

This is why `Nbkggrp` is a real analysis parameter, not just a runtime detail.

## 2.2.6 Point Sources vs Extended Sources

`extended=False` (default):

- point-source-style weighting definitions.

`extended=True`:

- includes region-area factors in weighting logic,
- better matches extended-source assumptions (surface-brightness style behavior).

## 2.2.7 Computational Controls

### Parallelism

- `nthreads` controls parallel work, especially response shifting.

### Bootstrap

- `bootstrap=True` activates resampled realizations,
- `num_bootstrap` sets realization count,
- `bootstrap_portion` sets fraction of sources drawn each realization.

### Caching

- `do_cache=True` stores and reuses per-source rest-frame intermediates (`.rf*`),
- reduces rerun time for repeated experiments on same source list,
- increases disk usage and I/O.

You can remove cache files with:

- `clear_rf_files`.

## 2.2.8 Outputs And Interpretation

For each run (or each bootstrap realization), Xstack writes:

- stacked PI spectrum,
- stacked background PI spectrum,
- stacked ARF,
- stacked RMF,
- first-contributing-energy metadata (`fene`),
- and log files documenting settings and weights.

For reproducibility, stacked FITS outputs also store the executed command in header `HISTORY` cards.

Interpretation reminder:

- the pipeline is designed to preserve average spectral shape robustly;
- do not over-interpret absolute normalization without additional calibration context.

## 2.2.9 Same-target Mode (Multiple Exposures of One Target)

Xstack also provides `same_target` mode for coadding repeated exposures of one target.

Conceptual difference from standard mode:

- standard mode: rest-frame shifting + multi-target population stacking,
- `same_target` mode: observed-frame exposure coadd for one target.

In `same_target` mode:

- rest-frame shifting is skipped,
- Galactic NH correction is skipped,
- source/background PI are summed directly (no pre-scaling of background PI),
- full response is stacked using `FLX` weighting,
- stacked `EXPOSURE` is the summed exposure,
- stacked src/bkg `AREASCAL`, `BACKSCAL`, `CORRSCAL` are written as input means.

Quality guard in logs:

- if `var(x/mean(x))` is large for any of `AREASCAL`, `BACKSCAL`, or `CORRSCAL`, a warning is logged.