iSTARMOD: Python Code for Stellar Chromospheric Activity

• iSTARMOD is a Python-based tool that implements spectral subtraction to isolate chromospheric excess emission in late-type stars.
• The code automates continuum normalization, radial velocity correction, and equivalent width integration to convert spectra into absolute surface fluxes using calibrated chi-functions.
• Its modular design supports rapid processing and integration into large-scale pipelines, aiding in mitigating activity-induced RV jitter in exoplanet searches.

iSTARMOD is a Python-based code for quantifying chromospheric activity in late-type stars using the spectral subtraction technique. It is an updated and extended version of the original STARMOD code, reimplemented for modern usability, modularity, and workflow integration. iSTARMOD provides quantitative measurements of chromospheric excess emission in several activity indicators and automates the conversion of equivalent width excesses into absolute surface fluxes using calibrated $\chi$-functions. It supports rapid processing and is designed for integration into large-scale stellar activity and exoplanet search pipelines (Labarga et al., 9 Dec 2025).

1. Spectral Subtraction Technique

The core principle underlying iSTARMOD is the spectral subtraction technique, which isolates chromospheric “excess” emission by removing a synthetic photospheric template from the observed stellar spectrum. The method proceeds as follows:

• Template construction: One or multiple inactive reference star spectra $F_{\mathrm{ref},i}(\lambda)$ are chosen. Each is Doppler-shifted to correct for radial velocity $\Delta v_{r,i}$ using $\lambda' = \lambda_0 (1+v_r/c)$.
• Rotational broadening: Reference spectra are convolved with a Gray-profile kernel $G(v; v\,\sin\,i, \epsilon)$ (with $\epsilon=0.6$ by default), and optionally with a macroturbulent Gaussian.
• Template combination: For multi-component systems (e.g., SB2), the synthetic template $F_{\mathrm{syn}}(\lambda)$ is a weighted sum: $F_{\mathrm{syn}} = \sum_i w_i F_{\mathrm{ref},i}$, enforcing $\sum w_i = 1$.
• Subtraction and measurement: The residual spectrum is constructed as $$Residual(\lambda) = F_{obs}(\lambda) - F_{syn}(\lambda)$$, and the excess equivalent width $$EW_{excess} = \int [F_{obs}(\lambda) - F_{syn}(\lambda)]\,d\lambda$$ is calculated.
• Activity flux: Chromospheric line surface flux is then $$\mathcal{F}'_{\mathrm{line}} = \int Residual\,d\lambda$$, with final calibration applied as $$F_S(\lambda) = \chi(\lambda, T_{\mathrm{eff}}) \cdot EW_{excess}$$.

This approach enables quantitative isolation of chromospheric activity signatures in H$\alpha$ and other Balmer lines, He I D3, Na I D1 and D2, Ca II H & K, Ca II infrared triplet, Paschen series, and He I $\lambda$10830.

2. Preprocessing: Continuum Normalization, Radial Velocity Alignment, and Template Matching

A sequence of preprocessing steps ensures accurate subtraction:

• Rebinning: Spectra are resampled to a constant $\Delta\lambda$ grid as needed.
• Continuum placement: Adopts ARES methodology to locate line-free continuum windows and fits a low-order polynomial (2nd–4th order), normalizing spectra to unity.
• Radial velocity correction: Shifts are split into integer and fractional pixel displacements, achieved via array reindexing and local linear Lagrange interpolation. Least-squares minimization of $rms = \sum [F_{obs} - F_{syn}]^2$ (excluding activity line pixels) is used to fit $v_r$.
• Rotational broadening: Performed via convolution with the Gray-profile kernel; $v\,\sin\,i$ can be fit or fixed.
• Component weighting: For SB2s, weights $w_1$, $w_2$ are set by luminosity ratio or fitted, with $\sum w = 1$. Component EWs de-blended using two-Lorentzian fits and corrected by $1/w_i$.
• Diagnostic metrics: Successful subtraction yields $rms \lesssim 0.5$ (normalized units) outside excluded pixel regions.

3. $\chi$-Function Calibrations for Surface Flux Determination

iSTARMOD includes a suite of calibrations for $\chi$-functions, translating measured $EW_{excess}$ to surface fluxes ($\mathrm{erg\,cm}^{-2}\,\mathrm{s}^{-1}$):

• Formalism: $$\log(L_\mathrm{line}/L_\mathrm{bol}) = \log \chi + \log EW$$, and $$\mathcal{F}_\mathrm{line} = \chi(T_\mathrm{eff})\cdot EW_{excess}$$ with $$\mathcal{F}_\mathrm{line}/\sigma T_\mathrm{eff}^4 = L_\mathrm{line}/L_\mathrm{bol}$$.
• Calibration grid: BT-Settl-CIFIST synthetic spectra spanning $T_\mathrm{eff} \in [2200, 7000]$ K, $\log g = 4.5-5.5$, [Fe/H] = 0, degraded to $R \approx 85\,000$.
• Functional form:

$$\chi = C_0 (T_\mathrm{eff}/T_s)^\alpha\,10^{P_5(T_\mathrm{eff})}, \quad \text{or} \quad \log \chi = C_1 + \alpha \log T_\mathrm{eff} + \beta_1 T_\mathrm{eff} + \ldots + \beta_5 T_\mathrm{eff}^5$$

• Representative coefficients (for H$\alpha$): $C_1 = -0.0046 \pm 0.0002$, $\alpha = 0.1281 \pm 0.0006$, $\beta_1 = -1.01\times10^{-3}$, higher-order $\beta_j = 0$ for $j > 1$.
• Tabulated fits: Annex A, Table 1, provides coefficients for each line/group (H$\alpha$, Ca II H & K, He I D3+Na D, Ca II IRT, Paschen, He I 10830), along with $R^2$.

Calibrated $\chi$-functions enable fully automated and uniform flux computation for large stellar samples.

4. Software Design, Modules, and User Parameters

iSTARMOD is implemented in Python 3, relying on dependencies including Astropy, NumPy, SciPy, optional ARES, and Matplotlib. Its modular architecture separates IO, continuum fitting, radial velocity shifting, rotational broadening, synthetic spectrum synthesis, subtraction, equivalent width integration, flux calibration, and plotting.

Key modules and their roles:

Module	Functionality	Input/Output
istarmod.io	FITS/dat reading, rebinning	Spectra (obs/ref), output files
istarmod.continuum	ARES-based continuum fit, normalization	Input spectrum, normalized spectrum
istarmod.rvshift	Integer and fractional pixel shift for RV correction	Input/shifted spectrum
istarmod.rotbroaden	Gray-profile convolution for $v\,\sin\,i$ broadening	Spectrum, broadened spectrum
istarmod.synth	Weighted synthetic template construction	Obs/ref spectra, synthetic spectrum
istarmod.subtract	Residual calculation ($F_{obs}-F_{syn}$)	Observed/synthetic, residual
istarmod.ew	EW integration, Cayrel error formula	Residual, EW/uncertainty
istarmod.chi	$\chi(T_\mathrm{eff})$ interpolation, flux computation	EW, surface flux
istarmod.plot	Visualization of fits and residuals	All, graphical output

User interaction occurs primarily via configuration files (inputParameters.sm) and Python API calls. Inputs include: active and reference spectra (FITS or .dat), initial $v_r$, $v\,\sin\,i$, weights, flags for variable/fixed parameters, and detailed spectral regions to analyze. Outputs are normalized/broadened templates, subtracted residuals, and summary tables of $EW_{excess}$ and uncertainties.

5. Usage Example and Workflow

A typical workflow with iSTARMOD proceeds:

1. Load observed spectrum: ISTARMOD.load_spectrum("target.fits")
2. Specify reference star: Input spectrum path, $v_r$, $v\,\sin\,i$, weight, variable/fixed flags.
3. Set fitting zone and exclusion window: Define spectral windows and exclude chromospheric line cores from the fit.
4. Initialize and run subtraction: Normalize continuum, fit $v_r$ and $v\,\sin\,i$, synthesize and subtract template.
5. Measure chromospheric $EW_{excess}$ and uncertainty: Via numerical integration and Cayrel formula.
6. Convert to surface flux: Apply $\chi$-function calibrations at known $T_\mathrm{eff}$.
7. Repeat for all lines of interest: Automated via script or notebook.

Batch processing across many stars or spectra is supported, as is integration into larger data reduction pipelines. Output products include both machine- and human-readable data.

6. Pipeline Integration and Radial Velocity Jitter Mitigation

iSTARMOD is designed for rapid and automated integration with spectroscopic survey pipelines such as CARMENES DR1. It supports hands-off workflow—continuum normalization, inactive template subtraction, EW measurement, and flux calculation—in batch mode across large data volumes.

In the context of precision radial velocity (RV) measurements, iSTARMOD facilitates:

• Mitigation of activity-induced RV jitter: Subtracting chromospheric emission lines before cross-correlation reduces spurious RV shifts due to line-shape changes from activity.
• Flagging and downweighting strong activity epochs: Analysis of residual spectra enables identification of flares or activity epochs, aiding in selection of quiescent data for exoplanet searches.

Output residuals, EWs, and fluxes can be programmatically incorporated into high-level analysis workflows.

7. Distribution, Documentation, and Extensibility

iSTARMOD is publicly available under open access (Zenodo DOI 10.5281/zenodo.17329154, GitHub flabarga/iSTARMOD) with comprehensive documentation covering the Python API, configuration syntax, $\chi$-factor calibration procedures, and worked examples (Labarga et al., 9 Dec 2025). The package includes several practical examples to facilitate learning and rapid adoption. Direct integration with common astronomical analysis environments and notebooks is supported. This architecture positions iSTARMOD as a versatile tool for both large-scale stellar activity surveys and detailed studies of individual targets.