Hardness Intensity Generator

Hardness Intensity Generator is an interactive scientific-Python workflow for turning calibrated X-ray event products into background-subtracted total, soft-band, and hard-band light curves; aligning their time bins; calculating hardness ratios with propagated uncertainties; and exporting both a hardness-intensity diagram and a FITS data product.

Independent-software notice: This is custom research software developed by M. Varun. It is not affiliated with, endorsed by, sponsored by, or maintained by NASA, HEASARC, the NICER mission team, or the official HEASoft/NICERDAS developers. Those projects remain the authoritative sources for mission calibration and processing software.

Scientific scope: This program orchestrates nicerl3-lc and derives a diagnostic diagram from its products. It does not implement mission calibration, event screening, or the SCORPEON background model. Scientific validity depends on the input data, GTIs, calibration, software versions, band definitions, time binning, and inspection of the products.

Copyright, permission, and mandatory citation

COPYRIGHT © 2026 M. VARUN, CHRIST (DEEMED TO BE UNIVERSITY), BENGALURU (BANGALORE), INDIA. ALL RIGHTS RESERVED.

NO PERMISSION IS GRANTED TO USE, COPY, MODIFY, REDISTRIBUTE, REPUBLISH, OR INCORPORATE THIS SOFTWARE INTO ANOTHER PROJECT WITHOUT PRIOR WRITTEN PERMISSION FROM THE AUTHOR. WHEN PERMISSION IS GRANTED, CLEAR ATTRIBUTION AND CITATION OF M. VARUN AND THIS REPOSITORY ARE MANDATORY.

Connected workflow

flowchart LR
    A[Calibrated and screened event products] --> B[nicerl3-lc]
    B --> C[Total net light curve]
    B --> D[Soft net light curve]
    B --> E[Hard net light curve]
    D --> F[Time-bin alignment]
    E --> F
    C --> F
    F --> G[Hardness and uncertainty]
    G --> H[HID PNG]
    G --> I[HID FITS table]

Loading

Portfolio companions:

• Varun's Custom NICER Pipeline — calibrated and screened event preparation.
• Spectral Product Generation — source spectra and response products.
• PhotonForge — general-purpose background-subtracted light-curve generation.

Synthetic workflow preview

The cover and animation are synthetic illustrations created for software documentation. They are not observational data, detections, or scientific validation.

Capabilities

• Reads observation folders from a text list and skips missing entries.
• Selects all observations, individual ObsIDs, multiple ObsIDs, or inclusive numeric ranges.
• Finds working folders common to all selected observations.
• Uses one consistent total, soft, and hard energy definition across the selected sample.
• Can choose disjoint soft and hard PI bands automatically from the first selected event file by seeking a near-unity count split.
• Runs nicerl3-lc with the SCORPEON background option and discovered ARF/RMF files when available.
• Computes net rates from embedded background columns or a separate background light curve.
• Propagates independent source and background errors in quadrature.
• Aligns total, soft, and hard products by time when their rows are not already identical.
• Propagates soft- and hard-rate errors into the hardness ratio.
• Saves a publication-ready PNG quicklook and a reusable FITS table.

Scientific definitions

For aligned bins with positive soft net rate,

hardness = hard net rate / soft net rate

with first-order independent-error propagation,

sigma_hardness = sqrt[(sigma_hard / soft)^2
                      + (hard * sigma_soft / soft^2)^2].

The plotted intensity is the net rate measured independently over the requested total band. It is not assumed to equal the arithmetic sum of the soft and hard rates unless the chosen bands exactly partition the total band.

Requirements

• Python 3.10 or newer
• NumPy
• Matplotlib
• Astropy
• A configured HEASoft/NICERDAS environment providing nicerl3-lc
• An appropriate CALDB installation
• Calibrated, screened event products

Install the Python packages with:

python -m pip install -r requirements.txt

Expected layout

Launch the program from a project directory containing an observation list and observation folders:

project/
├── obs_list.txt
├── 1050000001/
│   └── products/
│       └── ni1050000001_0mpu7_cl.evt
└── 1050000002/
    └── products/
        └── ni1050000002_0mpu7_cl.evt

Each non-blank line in obs_list.txt must point to an observation directory, either relatively or absolutely.

Run

python hardness_intensity_generator.py

The prompts request the observation-list file, ObsID selection, shared working folder, time bin, total PI range, and soft/hard PI ranges. Leaving both component-band prompts blank enables automatic selection from the first chosen observation. PI ranges use channel units, not keV.

Outputs

For each successfully processed observation, the selected working directory receives an HID/ folder containing:

HID/
├── total_<range>_sr.lc
├── total_<range>_bg.lc
├── Net_lc_total_<range>.lc
├── soft_<range>_sr.lc
├── soft_<range>_bg.lc
├── Net_lc_soft_<range>.lc
├── hard_<range>_sr.lc
├── hard_<range>_bg.lc
├── Net_lc_hard_<range>.lc
├── HID_<obsid>.flc
└── HID_<obsid>.png

The FITS table records time, time-bin half-width, soft and hard net rates and errors, hardness and its error, total-band intensity and error, and fractional exposure. Band definitions are stored in the header.

Data-safety and interpretation notes

• clobber=yes is passed to the external task, and derived HID products are overwritten on rerun. Preserve products you need before repeating an analysis.
• Automatic bands are selected from the first chosen observation and then held fixed for all selected observations, which supports cross-observation comparison but does not guarantee physically optimal bands.
• Automatic count balancing is an operational choice, not a source-state classification method.
• Bins with non-finite values or non-positive soft net rates are excluded because their hardness is undefined or unstable.
• The calculation assumes independent reported rate errors; background-model systematics are not added.
• A hardness-intensity track is a diagnostic representation and does not by itself establish a physical state transition.

Validation boundary

The repository check compiles the Python source and the animation helper. The portfolio copy was also statically inspected for its selection, alignment, uncertainty-propagation, and output logic. Full validation requires real observations, configured HEASoft/NICERDAS and CALDB, inspection of task output, and scientific review of the chosen bands and generated diagrams. No mission-software or observational run is claimed here.

Official external-task reference: nicerl3-lc

Citation

Citation metadata are provided in CITATION.cff. Citation does not replace the requirement to obtain prior written permission.

Author

M. Varun
X-ray astronomy researcher and scientific Python developer
CHRIST (Deemed to be University), Bengaluru (Bangalore), India
GitHub: varunastronomy