gaussFitSpec 0.1.0__tar.gz

gaussfitspec-0.1.0/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.

gaussfitspec-0.1.0/MANIFEST.in

@@ -0,0 +1,17 @@
+include README.md
+include LICENSE
+include pyproject.toml
+include examples/example_spectra.txt
+include examples/example_components.csv
+include examples/example_fit.png
+recursive-include src *.py
+recursive-include docs *.rst *.py
+
+global-exclude __pycache__
+global-exclude *.py[cod]
+
+prune .pytest_cache
+prune tests
+prune build
+prune dist
+prune docs/_build

gaussfitspec-0.1.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: gaussFitSpec
+Version: 0.1.0
+Summary: Lightweight 1D Gaussian spectral decomposition.
+Author: Hongxing Chen
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+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: pytest>=7.4; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=8; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=3; extra == "docs"
+Dynamic: license-file
+
+# gaussFitSpec
+
+[![PyPI version](https://img.shields.io/pypi/v/gaussFitSpec.svg)](https://pypi.org/project/gaussFitSpec/)
+[![Python versions](https://img.shields.io/pypi/pyversions/gaussFitSpec.svg)](https://pypi.org/project/gaussFitSpec/)
+[![Documentation Status](https://readthedocs.org/projects/gaussfitspec/badge/?version=latest)](https://gaussfitspec.readthedocs.io/en/latest/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20917299.svg)](https://doi.org/10.5281/zenodo.20917299)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Lightweight 1D Gaussian spectral decomposition for independent spectra.
+
+`gaussFitSpec` fits one-dimensional spectra with multiple Gaussian components
+and returns fitted component parameters as a pandas DataFrame.
+
+## Links
+
+- PyPI: https://pypi.org/project/gaussFitSpec/
+- Documentation: https://gaussfitspec.readthedocs.io/en/latest/
+- Source code: https://github.com/retarchen/GaussianFitSpectra
+- Citation DOI: https://doi.org/10.5281/zenodo.20917299
+
+This release is archived on Zenodo and can be cited with DOI
+`10.5281/zenodo.20917299`.

gaussfitspec-0.1.0/README.md

@@ -0,0 +1,22 @@
+# gaussFitSpec
+
+[![PyPI version](https://img.shields.io/pypi/v/gaussFitSpec.svg)](https://pypi.org/project/gaussFitSpec/)
+[![Python versions](https://img.shields.io/pypi/pyversions/gaussFitSpec.svg)](https://pypi.org/project/gaussFitSpec/)
+[![Documentation Status](https://readthedocs.org/projects/gaussfitspec/badge/?version=latest)](https://gaussfitspec.readthedocs.io/en/latest/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20917299.svg)](https://doi.org/10.5281/zenodo.20917299)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Lightweight 1D Gaussian spectral decomposition for independent spectra.
+
+`gaussFitSpec` fits one-dimensional spectra with multiple Gaussian components
+and returns fitted component parameters as a pandas DataFrame.
+
+## Links
+
+- PyPI: https://pypi.org/project/gaussFitSpec/
+- Documentation: https://gaussfitspec.readthedocs.io/en/latest/
+- Source code: https://github.com/retarchen/GaussianFitSpectra
+- Citation DOI: https://doi.org/10.5281/zenodo.20917299
+
+This release is archived on Zenodo and can be cited with DOI
+`10.5281/zenodo.20917299`.

gaussfitspec-0.1.0/docs/api.rst

@@ -0,0 +1,26 @@
+API Reference
+=============
+
+Public API
+----------
+
+.. automodule:: gaussFitSpec
+   :members:
+
+Fitting
+-------
+
+.. automodule:: gaussFitSpec.fitting
+   :members: SpectrumFitResult, fit_spectrum
+
+I/O
+---
+
+.. automodule:: gaussFitSpec.io
+   :members:
+
+Plotting
+--------
+
+.. automodule:: gaussFitSpec.plotting
+   :members:

gaussfitspec-0.1.0/docs/conf.py

@@ -0,0 +1,28 @@
+"""Sphinx configuration for gaussFitSpec."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import sys
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(PROJECT_ROOT / "src"))
+
+project = "gaussFitSpec"
+author = "Hongxing Chen"
+release = "0.1.0"
+
+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

gaussfitspec-0.1.0/docs/examples.rst

@@ -0,0 +1,32 @@
+Examples
+========
+
+The repository includes an example spectrum at:
+
+.. code-block:: text
+
+   examples/example_spectra.txt
+
+Run the example script from the project root:
+
+.. code-block:: bash
+
+   python examples/run_example.py
+
+The script writes:
+
+.. code-block:: text
+
+   examples/example_components.csv
+   examples/example_fit.png
+
+The example output plot is shown below as a reference for a successful fit:
+
+.. image:: ../examples/example_fit.png
+   :alt: Diagnostic Gaussian fit for the bundled example spectrum
+   :align: center
+   :width: 90%
+
+The fitted component table is also included as a downloadable example output:
+
+:download:`Download example_components.csv <../examples/example_components.csv>`

gaussfitspec-0.1.0/docs/index.rst

@@ -0,0 +1,18 @@
+gaussFitSpec documentation
+==========================
+
+``gaussFitSpec`` is a lightweight Python package for decomposing an independent
+1D spectrum into multiple Gaussian components. It supports BIC and approximate
+F-test model selection, returns fitted components as a pandas DataFrame, and can
+create diagnostic plots.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: User Guide
+
+   installation
+   input_format
+   usage
+   model_selection
+   examples
+   api

gaussfitspec-0.1.0/docs/input_format.rst

@@ -0,0 +1,29 @@
+Input Format
+============
+
+Input spectrum files must contain exactly three numerical columns in this order:
+
+1. ``velocity``
+2. ``spectrum``
+3. ``spectrum_err``
+
+Plain text tables such as ``.txt``, ``.dat``, and ``.csv`` are supported when
+they follow this three-column structure. Whitespace-separated and comma-separated
+tables are both accepted.
+
+Example
+-------
+
+.. code-block:: text
+
+   223.526564  0.040043  0.172759
+   224.113598  0.180919  0.789550
+   224.700631  0.293556  1.416493
+
+Read a file with:
+
+.. code-block:: python
+
+   from gaussFitSpec import read_spectrum
+
+   velocity, spectrum, spectrum_err = read_spectrum("examples/example_spectra.txt")

gaussfitspec-0.1.0/docs/installation.rst

@@ -0,0 +1,16 @@
+Installation
+============
+
+Install the package in editable mode from the project root:
+
+.. code-block:: bash
+
+   pip install -e .
+
+For development and testing:
+
+.. code-block:: bash
+
+   pip install -e ".[dev]"
+
+The package depends on ``numpy``, ``scipy``, ``pandas``, and ``matplotlib``.

gaussfitspec-0.1.0/docs/model_selection.rst

@@ -0,0 +1,32 @@
+Model Selection
+===============
+
+BIC
+---
+
+``method="bic"`` is the default. The package fits models with 1 through
+``max_components`` Gaussian components and selects the model with the lowest BIC:
+
+.. math::
+
+   \mathrm{BIC} = \chi^2 + k \ln(n)
+
+where ``k`` is the number of free parameters and ``n`` is the number of data
+points.
+
+F-test
+------
+
+``method="f_test"`` adds one component at a time and keeps the additional
+component only when the approximate F-test reports:
+
+.. code-block:: text
+
+   p < f_test_alpha
+
+The default threshold is ``f_test_alpha=0.05``.
+
+The F-test implementation is an approximate nested-model comparison based on
+the improvement in residual sum of squares. It is useful for practical model
+selection, but it should not be treated as a fully rigorous astrophysical
+line-identification test.

gaussfitspec-0.1.0/docs/usage.rst

@@ -0,0 +1,89 @@
+Basic Usage
+===========
+
+Fit a spectrum with the default BIC model selection:
+
+.. code-block:: python
+
+   from gaussFitSpec import fit_spectrum, plot_fit, read_spectrum
+
+   velocity, spectrum, spectrum_err = read_spectrum("examples/example_spectra.txt")
+
+   result = fit_spectrum(
+       velocity,
+       spectrum,
+       spectrum_err,
+       name="spectra1",
+       method="bic",
+       max_components=8,
+   )
+
+   print(result.components)
+   result.to_csv("examples/example_components.csv")
+
+   plot_fit(
+       velocity,
+       spectrum,
+       spectrum_err,
+       result,
+   output_file="examples/example_fit.png",
+   )
+
+Fitting Options
+---------------
+
+Use ``min_fwhm`` and ``max_fwhm`` to constrain component widths:
+
+.. code-block:: python
+
+   result = fit_spectrum(
+       velocity,
+       spectrum,
+       spectrum_err,
+       min_fwhm=2.0,
+       max_fwhm=40.0,
+   )
+
+Fit Result
+----------
+
+The returned ``SpectrumFitResult`` contains:
+
+``components``
+   A pandas DataFrame with one row per Gaussian component.
+
+``best_model``
+   The total fitted Gaussian model evaluated on the input velocity grid.
+
+``individual_components``
+   A 2D array containing each Gaussian component evaluated on the input velocity
+   grid.
+
+``residual``
+   ``spectrum - best_model``.
+
+``method``
+   The selected model-selection method.
+
+``n_components``
+   The number of selected Gaussian components.
+
+``fit_statistics``
+   A dictionary with values such as ``chi2``, ``reduced_chi2``, ``aic``, and
+   ``bic``.
+
+Component Table
+---------------
+
+The component table includes:
+
+.. code-block:: text
+
+   name
+   component_index
+   amplitude
+   amplitude_err
+   velocity
+   velocity_err
+   fwhm
+   fwhm_err

gaussfitspec-0.1.0/examples/example_components.csv

@@ -0,0 +1,3 @@
+name,component_index,amplitude,amplitude_err,velocity,velocity_err,fwhm,fwhm_err
+spectra1,1,30.719455863304102,1.2960236955351023,242.08519230354096,0.12379227433705506,8.785013010396264,0.3637763168311731
+spectra1,2,18.043265182018196,0.8105330499276882,245.05006347937564,0.27913280072025837,29.697380157924023,0.7310859766237641

gaussfitspec-0.1.0/examples/example_spectra.txt

@@ -0,0 +1,200 @@
+169.223213	-0.051378	0.084575
+170.029980	-0.209886	0.381358
+170.836746	-0.240423	0.704199
+171.643513	0.084050	0.796395
+172.450280	0.225295	0.740715
+173.257047	0.109119	0.824865
+174.063813	0.069419	0.835017
+174.870580	0.108204	0.742901
+175.677347	0.294026	0.801274
+176.484113	0.355414	0.849117
+177.290880	0.279666	0.800087
+178.097647	0.143762	0.665558
+178.904413	-0.013534	0.731112
+179.711180	-0.058090	0.872266
+180.517947	-0.038125	0.903539
+181.324713	0.035891	0.961912
+182.131480	0.027419	0.831842
+182.938247	-0.006093	0.907416
+183.745013	-0.046264	0.998111
+184.551780	-0.198992	0.926267
+185.358547	-0.309919	0.943745
+186.165313	-0.248100	0.934969
+186.972080	-0.062067	0.876708
+187.778847	0.064827	0.791065
+188.585613	0.018504	0.713378
+189.392380	0.008915	0.815016
+190.199147	0.095548	0.901835
+191.005913	0.127256	0.849412
+191.812680	-0.046437	0.925115
+192.619447	-0.210392	0.939867
+193.426213	-0.136177	0.906167
+194.232980	0.088370	0.789601
+195.039747	0.296789	0.815457
+195.846514	0.312478	0.711472
+196.653280	0.215387	0.676745
+197.460047	0.189120	0.810944
+198.266814	0.256178	0.959052
+199.073580	0.459011	0.939783
+199.880347	0.593154	0.959268
+200.687114	0.477939	0.767762
+201.493880	0.244436	0.695782
+202.300647	0.247385	0.818448
+203.107414	0.361873	0.884467
+203.914180	0.256186	0.872900
+204.720947	0.135204	0.768211
+205.527714	0.351266	0.763784
+206.334480	0.762746	0.719210
+207.141247	0.919308	0.612173
+207.948014	0.755364	0.684702
+208.754780	0.701783	0.853603
+209.561547	0.782473	0.866252
+210.368314	0.824836	0.940176
+211.175080	0.851642	0.993832
+211.981847	0.903761	0.943186
+212.788614	1.030113	0.952811
+213.595380	1.137577	0.941376
+214.402147	1.161150	0.790976
+215.208914	1.175361	0.775262
+216.015681	1.309951	0.903400
+216.822447	1.624255	0.910242
+217.629214	1.833445	0.886051
+218.435981	2.022358	0.894370
+219.242747	2.437275	0.939360
+220.049514	2.741029	0.807583
+220.856281	2.821305	0.863376
+221.663047	3.007326	1.148641
+222.469814	3.383987	1.201270
+223.276581	3.756919	1.128092
+224.083347	4.105148	1.146127
+224.890114	4.471130	1.086450
+225.696881	4.888089	0.884743
+226.503647	5.376625	1.066133
+227.310414	6.053403	1.175447
+228.117181	6.985528	1.269142
+228.923947	7.888375	1.445930
+229.730714	8.670854	1.619215
+230.537481	9.559677	1.363808
+231.344247	10.811086	0.986892
+232.151014	12.232121	1.050776
+232.957781	13.597061	1.076988
+233.764547	15.122914	1.289056
+234.571314	17.204223	1.648180
+235.378081	19.853025	1.570089
+236.184847	22.913794	1.485301
+236.991614	26.414981	1.784028
+237.798381	30.477241	2.243435
+238.605148	34.997132	2.786707
+239.411914	39.631692	3.161263
+240.218681	43.899251	3.220666
+241.025448	46.789029	3.235564
+241.832214	47.715295	3.321778
+242.638981	47.227129	3.096399
+243.445748	45.992398	2.861070
+244.252514	43.871485	2.691917
+245.059281	40.961346	2.277715
+245.866048	37.481588	1.747065
+246.672814	33.458518	1.527372
+247.479581	28.906482	1.567346
+248.286348	24.612455	1.463185
+249.093114	21.355218	1.252439
+249.899881	19.160100	1.173143
+250.706648	17.779837	1.358749
+251.513414	16.781671	1.426363
+252.320181	15.889040	1.392637
+253.126948	15.302381	1.338812
+253.933714	14.751068	1.313500
+254.740481	14.021037	1.198413
+255.547248	13.339361	1.186116
+256.354014	12.537086	1.355677
+257.160781	11.839795	1.358574
+257.967548	11.121042	1.203808
+258.774315	10.240221	1.261968
+259.581081	9.350617	1.283421
+260.387848	8.462893	1.335831
+261.194615	7.655898	1.463723
+262.001381	6.978076	1.606239
+262.808148	6.347233	1.671197
+263.614915	5.824419	1.445448
+264.421681	5.451081	1.212917
+265.228448	5.068914	1.238327
+266.035215	4.644800	1.198635
+266.841981	4.123035	1.181262
+267.648748	3.605135	1.028579
+268.455515	3.139130	0.984841
+269.262281	2.624324	0.977819
+270.069048	2.188257	0.997455
+270.875815	2.066094	0.961392
+271.682581	1.997856	1.076353
+272.489348	1.739468	1.027318
+273.296115	1.357335	0.867431
+274.102881	1.222323	0.887501
+274.909648	1.105125	1.020115
+275.716415	0.898470	0.981746
+276.523181	0.733163	0.827639
+277.329948	0.763089	0.863280
+278.136715	0.781045	0.910205
+278.943482	0.620572	0.924676
+279.750248	0.368894	1.055941
+280.557015	0.206007	0.979581
+281.363782	0.260230	0.891572
+282.170548	0.299286	0.804352
+282.977315	-0.007887	0.814386
+283.784082	-0.360147	0.875297
+284.590848	-0.424664	0.962512
+285.397615	-0.417410	0.982056
+286.204382	-0.268576	0.755472
+287.011148	0.068532	0.807672
+287.817915	0.241941	0.914048
+288.624682	0.222014	0.784136
+289.431448	0.144930	0.762920
+290.238215	0.049685	0.774217
+291.044982	-0.074506	0.794487
+291.851748	-0.074674	0.795597
+292.658515	-0.047697	0.742641
+293.465282	-0.150940	0.839101
+294.272048	-0.186577	0.936325
+295.078815	-0.145823	0.822700
+295.885582	-0.258044	0.885174
+296.692348	-0.474601	1.029252
+297.499115	-0.274283	0.975450
+298.305882	0.108560	0.875500
+299.112648	0.308847	0.984088
+299.919415	0.222269	1.006629
+300.726182	-0.042506	1.003279
+301.532949	-0.134071	1.010686
+302.339715	-0.073285	0.959841
+303.146482	-0.093430	0.970801
+303.953249	-0.160899	0.977550
+304.760015	-0.031637	0.805491
+305.566782	0.142979	0.876339
+306.373549	0.218395	0.978226
+307.180315	0.387146	0.859842
+307.987082	0.558421	0.720247
+308.793849	0.477668	0.723772
+309.600615	0.319101	0.723067
+310.407382	0.232847	0.753574
+311.214149	0.146177	0.763329
+312.020915	0.063254	0.879100
+312.827682	0.067061	0.977356
+313.634449	0.085607	0.967621
+314.441215	-0.028195	1.022139
+315.247982	-0.104256	1.042327
+316.054749	-0.070856	0.891057
+316.861515	-0.006097	0.801960
+317.668282	0.038266	0.971858
+318.475049	0.065924	1.028126
+319.281815	0.104776	0.993460
+320.088582	0.093295	0.922851
+320.895349	0.046950	0.855686
+321.702116	-0.028960	0.719254
+322.508882	-0.113997	0.782099
+323.315649	-0.143435	0.936198
+324.122416	-0.084533	0.925058
+324.929182	-0.068900	0.763369
+325.735949	-0.060981	0.809960
+326.542716	0.000180	0.793946
+327.349482	0.122789	0.782817
+328.156249	0.160396	0.910406
+328.963016	0.092215	0.846644
+329.769782	0.028310	0.432021

gaussfitspec-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gaussFitSpec"
+version = "0.1.0"
+description = "Lightweight 1D Gaussian spectral decomposition."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Hongxing Chen" }
+]
+dependencies = [
+  "matplotlib>=3.7",
+  "numpy>=1.24",
+  "pandas>=2.0",
+  "scipy>=1.10"
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.4"
+]
+docs = [
+  "sphinx>=8",
+  "sphinx-rtd-theme>=3"
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

gaussfitspec-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gaussfitspec-0.1.0/src/gaussFitSpec/__init__.py

@@ -0,0 +1,19 @@
+"""Lightweight 1D Gaussian spectral decomposition.
+
+The public API is intentionally small. Most users will read a three-column
+spectrum table with :func:`read_spectrum`, fit it with :func:`fit_spectrum`,
+save the returned component table, and optionally create a diagnostic plot with
+:func:`plot_fit`.
+"""
+
+from .fitting import SpectrumFitResult, fit_spectrum
+from .io import read_spectrum, save_components_csv
+from .plotting import plot_fit
+
+__all__ = [
+    "SpectrumFitResult",
+    "fit_spectrum",
+    "plot_fit",
+    "read_spectrum",
+    "save_components_csv",
+]