spec-rt 0.1.1__tar.gz

spec_rt-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hongxing Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spec_rt-0.1.1/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+recursive-include docs *.rst *.py Makefile
+recursive-include examples *.py *.txt *.png *.csv

spec_rt-0.1.1/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.2
+Name: spec_rt
+Version: 0.1.1
+Summary: Gaussian-based absorption and emission spectral fitting tools.
+License: MIT
+Project-URL: Documentation, https://specrt.readthedocs.io/en/latest/
+Project-URL: Homepage, https://pypi.org/project/spec-rt/
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: astropy>=5.0
+Requires-Dist: gaussFitSpec>=1.0.1
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scipy>=1.10
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=8.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=3.0; extra == "docs"
+
+# spec_rt
+
+[![PyPI version](https://img.shields.io/pypi/v/spec-rt.svg)](https://pypi.org/project/spec-rt/)
+[![Documentation Status](https://readthedocs.org/projects/specrt/badge/?version=latest)](https://specrt.readthedocs.io/en/latest/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21052795.svg)](https://doi.org/10.5281/zenodo.21052795)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Gaussian-based radiative-transfer fitting for absorption and emission spectra.
+
+`spec_rt` fits absorption and emission spectra with Gaussian components and
+exports radiative-transfer decomposition results. The PyPI project name is
+`spec_rt`; the Python import package is also `spec_rt`.
+
+## Links
+
+- PyPI: https://pypi.org/project/spec-rt/
+- Documentation: https://specrt.readthedocs.io/en/latest/installation.html
+- Source code: https://github.com/retarchen/specRT
+- Citation DOI: https://doi.org/10.5281/zenodo.21052795
+
+This release is archived on Zenodo and can be cited with DOI
+`10.5281/zenodo.21052795`.

spec_rt-0.1.1/README.md

@@ -0,0 +1,22 @@
+# spec_rt
+
+[![PyPI version](https://img.shields.io/pypi/v/spec-rt.svg)](https://pypi.org/project/spec-rt/)
+[![Documentation Status](https://readthedocs.org/projects/specrt/badge/?version=latest)](https://specrt.readthedocs.io/en/latest/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21052795.svg)](https://doi.org/10.5281/zenodo.21052795)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Gaussian-based radiative-transfer fitting for absorption and emission spectra.
+
+`spec_rt` fits absorption and emission spectra with Gaussian components and
+exports radiative-transfer decomposition results. The PyPI project name is
+`spec_rt`; the Python import package is also `spec_rt`.
+
+## Links
+
+- PyPI: https://pypi.org/project/spec-rt/
+- Documentation: https://specrt.readthedocs.io/en/latest/installation.html
+- Source code: https://github.com/retarchen/specRT
+- Citation DOI: https://doi.org/10.5281/zenodo.21052795
+
+This release is archived on Zenodo and can be cited with DOI
+`10.5281/zenodo.21052795`.

spec_rt-0.1.1/docs/Makefile

@@ -0,0 +1,11 @@
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+.PHONY: html clean
+
+html:
+	$(SPHINXBUILD) -b html $(SOURCEDIR) $(BUILDDIR)/html
+
+clean:
+	rm -rf $(BUILDDIR)

spec_rt-0.1.1/docs/api.rst

@@ -0,0 +1,23 @@
+API Reference
+=============
+
+.. automodule:: spec_rt
+   :members:
+   :exclude-members: SpectrumFitResult
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: spec_rt.spectra_decomposing
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: spec_rt.spectra_decomposing_io
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: spec_rt.spectra_decomposing_plotting
+   :members:
+   :undoc-members:
+   :show-inheritance:

spec_rt-0.1.1/docs/conf.py

@@ -0,0 +1,26 @@
+"""Sphinx configuration for specRT."""
+
+from pathlib import Path
+import sys
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(PROJECT_ROOT / "src"))
+
+project = "spec_rt"
+author = "Project contributors"
+release = "0.1.1"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+autodoc_typehints = "description"
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True

spec_rt-0.1.1/docs/configuration.rst

@@ -0,0 +1,72 @@
+Configuration
+=============
+
+``SpectraDecomposing`` keeps the original script-style configuration as
+attributes. Set these before calling ``fit_and_plot()``.
+
+Core options
+------------
+
+``name``
+   Source name written into plots and CSV files.
+
+``align_data``
+   If ``True``, interpolate absorption and emission spectra onto a shared
+   velocity grid before fitting.
+
+``peak_abs``
+   Optional absorption component centers. Leave as ``[]`` for automatic
+   Gaussian selection.
+
+``peak_emi``
+   Optional emission component centers. Setting this manually can make the
+   emission fit much faster.
+
+``Tsmin``
+   Lower bound for CNM spin temperature.
+
+``Tsky``
+   Background sky temperature. Use ``2.73`` for CMB-only, or add synchrotron
+   emission if available.
+
+``F``
+   Foreground fraction values tested for WNM components. The default is
+   ``[0, 0.5, 1]``.
+
+``max_auto_warm_components``
+   Optional cap for automatically selected WNM components. Leave as ``None``
+   for the full search, or set a small integer for faster examples.
+
+Output options
+--------------
+
+``savecsv``
+   If ``True``, write ``Fulldata.csv``, ``CNMonlydata.csv``, and
+   ``WNMonlydata.csv``.
+
+``datapath``
+   Directory where CSV files are written.
+
+``renew``
+   If ``True``, remove old rows with the same ``name`` before writing new
+   results. This is useful when redoing a fit.
+
+Example
+-------
+
+.. code-block:: python
+
+   spec_fit = SpectraDecomposing(x, y, yerr, xemi, yemi, yemi_err)
+   spec_fit.name = "example_spec"
+   spec_fit.v_shift = 4
+   spec_fit.peak_abs = []
+   spec_fit.peak_emi = []
+   spec_fit.max_auto_warm_components = 1
+   spec_fit.Tsmin = 10
+   spec_fit.Tsky = 2.73
+   spec_fit.F = [0, 0.5, 1]
+   spec_fit.align_data = True
+   spec_fit.savecsv = True
+   spec_fit.renew = True
+   spec_fit.datapath = "examples/example_spec_csv_outputs"
+   spec_fit.fit_and_plot()

spec_rt-0.1.1/docs/examples.rst

@@ -0,0 +1,34 @@
+Examples
+========
+
+The repository currently includes:
+
+- ``examples/example_spec.txt`` as a real six-column absorption plus emission spectrum
+- ``examples/run_example_spec.py`` to reproduce the legacy four-panel plot
+- ``examples/example_spec_fit.png`` as the saved output from the packaged workflow
+- ``examples/example_spec_csv_outputs/`` with example CSV products
+
+Run the bundled example
+-----------------------
+
+.. code-block:: bash
+
+   python examples/run_example_spec.py
+
+This creates:
+
+- ``examples/example_spec_fit.png``
+- ``examples/example_spec_csv_outputs/Fulldata.csv``
+- ``examples/example_spec_csv_outputs/CNMonlydata.csv``
+- ``examples/example_spec_csv_outputs/WNMonlydata.csv``
+
+Example plot
+------------
+
+.. image:: ../examples/example_spec_fit.png
+   :alt: Four-panel example_spec absorption and emission fit
+   :width: 100%
+
+The upper two panels show the emission spectrum, best-fit model, and emission
+residual. The lower two panels show the absorption spectrum in
+``1 - exp(-tau)`` form, the absorption fit, and its residual.

spec_rt-0.1.1/docs/index.rst

@@ -0,0 +1,17 @@
+spec_rt documentation
+=====================
+
+This site documents the installable ``spec_rt`` Python package.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+
+   installation
+   usage
+   input_format
+   configuration
+   outputs
+   examples
+   performance
+   api

spec_rt-0.1.1/docs/input_format.rst

@@ -0,0 +1,52 @@
+Input Format
+============
+
+The bundled ``examples/example_spec.txt`` file uses six columns:
+
+1. absorption velocity
+2. absorption spectrum
+3. absorption spectrum error
+4. emission velocity
+5. emission spectrum
+6. emission spectrum error
+
+The bundled example stores the second column directly as ``1 - exp(-tau)``,
+so it is kept unchanged before fitting:
+
+.. code-block:: python
+
+   from spec_rt import load_six_column_spectrum
+
+   x, y, yerr, xemi, yemi, yemi_err = load_six_column_spectrum(
+       "examples/example_spec.txt",
+       absorption_format="one_minus_exp_tau",
+   )
+
+After loading, ``y`` is guaranteed to be in the expected ``1 - exp(-tau)``
+form, and the helper also drops non-finite emission rows.
+
+Use :func:`spec_rt.validate_absorption_input` to confirm that the
+absorption baseline remains close to zero before fitting.
+
+Common checks
+-------------
+
+- The absorption array passed to ``SpectraDecomposing`` must already be
+  ``1 - exp(-tau)``.
+- The absorption baseline should be close to zero outside the line.
+- Error columns must be positive; rows with non-positive errors are dropped
+  before fitting.
+- Emission rows with non-finite velocity, intensity, or error values are
+  dropped by ``load_six_column_spectrum``.
+
+If your raw absorption file stores transmission as ``exp(-tau)``, use:
+
+.. code-block:: python
+
+   load_six_column_spectrum("my_transmission_file.txt", absorption_format="transmission")
+
+If your file already stores ``1 - exp(-tau)``, use:
+
+.. code-block:: python
+
+   load_six_column_spectrum("examples/example_spec.txt", absorption_format="one_minus_exp_tau")

spec_rt-0.1.1/docs/installation.rst

@@ -0,0 +1,10 @@
+Installation
+============
+
+Clone the repository and install the package in editable mode:
+
+.. code-block:: bash
+
+   pip install spec_rt
+
+Please install `gaussFitSpec <https://pypi.org/project/gaussFitSpec/>`_ first as this package depends on it for direct Gaussian fitting. It also depends on ``numpy``, ``scipy``, ``astropy``, ``pandas``, and ``matplotlib``.

spec_rt-0.1.1/docs/outputs.rst

@@ -0,0 +1,34 @@
+Outputs
+=======
+
+When ``savecsv=True``, the fitter writes three CSV files.
+
+``Fulldata.csv``
+   One row per source with total CNM/WNM column density estimates, cold gas
+   fraction, sky temperature, and fitted uncorrected HI column density.
+
+``CNMonlydata.csv``
+   One row per cold component with optical depth, velocity, FWHM, spin
+   temperature, velocity shift, ordering, and CNM column density.
+
+``WNMonlydata.csv``
+   One row per warm component with brightness temperature, velocity, FWHM,
+   WNM column density, and foreground fraction value.
+
+Redoing a fit
+-------------
+
+Use ``renew=True`` when repeating a fit for the same source:
+
+.. code-block:: python
+
+   spec_fit.savecsv = True
+   spec_fit.renew = True
+   spec_fit.datapath = "examples/example_spec_csv_outputs"
+   spec_fit.fit_and_plot()
+
+This removes previous rows with the same ``Name`` from the three CSV files
+before appending the new results. It prevents duplicated rows when tuning
+``peak_abs``, ``peak_emi``, ``Tsmin``, or ``Tsky``.
+
+The package no longer writes ``output.txt``.

spec_rt-0.1.1/docs/performance.rst

@@ -0,0 +1,46 @@
+Performance
+===========
+
+The emission fit can become slow when the absorption fit contains many CNM
+components. The expensive part is testing possible CNM foreground/background
+orders and WNM foreground fractions.
+
+For ``ncold`` cold components and ``nwarm`` warm components, the number of
+candidate nonlinear emission fits can scale roughly as:
+
+.. code-block:: text
+
+   ncold! * len(F) ** nwarm
+
+Practical speed tips
+--------------------
+
+- Set ``peak_emi`` manually when you know the likely emission component
+  centers. This avoids a larger automatic search.
+- Reduce ``F`` during exploration. For example, use ``spec_fit.F = [0.5]`` for
+  a fast first pass, then restore ``[0, 0.5, 1]`` for a final run.
+- Limit absorption components by setting ``peak_abs`` manually or using
+  ``num_cold`` when the automatic fit over-splits noisy absorption spectra.
+- Set ``max_auto_warm_components`` to cap the automatic emission search when
+  you want automatic centers but do not want to test many WNM components.
+- Keep ``align_data=True`` when absorption and emission velocity grids differ.
+
+Example fast first pass
+-----------------------
+
+.. code-block:: python
+
+   spec_fit.peak_emi = []
+   spec_fit.max_auto_warm_components = 1
+   spec_fit.F = [0.5]
+   spec_fit.num_cold = 5
+   spec_fit.fit_and_plot()
+
+After the fit is stable, rerun with the fuller configuration if needed:
+
+.. code-block:: python
+
+   spec_fit.F = [0, 0.5, 1]
+   spec_fit.num_cold = 0
+   spec_fit.renew = True
+   spec_fit.fit_and_plot()

spec_rt-0.1.1/docs/usage.rst

@@ -0,0 +1,71 @@
+Usage
+=====
+
+The package exposes the radiative-transfer class and re-exports the
+``gaussFitSpec`` Gaussian fitting API:
+
+- ``SpectraDecomposing`` for combined absorption and emission decomposition
+- ``fit_spectrum`` from ``gaussFitSpec`` for direct Gaussian component fitting
+
+Basic imports:
+
+.. code-block:: python
+
+   from spec_rt import (
+       SpectraDecomposing,
+       create_legacy_axes,
+       fit_spectrum,
+       load_six_column_spectrum,
+   )
+
+Direct Gaussian fitting
+-----------------------
+
+Use ``fit_spectrum`` when you only need a Gaussian decomposition of one
+one-dimensional spectrum:
+
+.. code-block:: python
+
+   result = fit_spectrum(velocity, spectrum, spectrum_err, method="bic")
+   print(result.components)
+
+Radiative-transfer fitting
+--------------------------
+
+Use ``SpectraDecomposing`` when you have matched absorption and emission
+spectra:
+
+.. code-block:: python
+
+   x, y, yerr, xemi, yemi, yemi_err = load_six_column_spectrum(
+       "examples/example_spec.txt",
+       absorption_format="one_minus_exp_tau",
+   )
+
+   fig, axes = create_legacy_axes()
+   spec_fit = SpectraDecomposing(x, y, yerr, xemi, yemi, yemi_err)
+   spec_fit.name = "example_spec"
+   spec_fit.ax = axes
+   spec_fit.align_data = True
+   spec_fit.peak_abs = []
+   spec_fit.peak_emi = []
+   spec_fit.max_auto_warm_components = 1
+   spec_fit.Tsmin = 10
+   spec_fit.Tsky = 2.73
+   spec_fit.fit_mode = "BIC"
+   spec_fit.fit_and_plot()
+
+Saving CSV outputs
+------------------
+
+Set ``savecsv=True`` and choose an output directory:
+
+.. code-block:: python
+
+   spec_fit.savecsv = True
+   spec_fit.renew = True
+   spec_fit.datapath = "examples/example_spec_csv_outputs"
+   spec_fit.fit_and_plot()
+
+``renew=True`` removes old rows for the same source name before appending new
+results, which is useful when you redo a fit.