aspcap 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,185 @@
1
+ Metadata-Version: 2.4
2
+ Name: aspcap
3
+ Version: 0.2.0
4
+ Summary: Element abundance fits with FERRE
5
+ Author: David Nidever
6
+ License: MIT License
7
+
8
+ Copyright (c) 2026 David Nidever
9
+
10
+ Permission is hereby granted, free of charge, to any person obtaining a copy
11
+ of this software and associated documentation files (the "Software"), to deal
12
+ in the Software without restriction, including without limitation the rights
13
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14
+ copies of the Software, and to permit persons to whom the Software is
15
+ furnished to do so, subject to the following conditions:
16
+
17
+ The above copyright notice and this permission notice shall be included in all
18
+ copies or substantial portions of the Software.
19
+
20
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26
+ SOFTWARE.
27
+
28
+ Project-URL: Documentation, https://aspcap.readthedocs.io/
29
+ Project-URL: Repository, https://github.com/dnidever/aspcap
30
+ Project-URL: Issues, https://github.com/dnidever/aspcap/issues
31
+ Requires-Python: >=3.9
32
+ Description-Content-Type: text/markdown
33
+ License-File: LICENSE
34
+ License-File: LICENSE-DOPPLER
35
+ Requires-Dist: numpy>=1.23
36
+ Requires-Dist: scipy>=1.9
37
+ Dynamic: license-file
38
+
39
+ # aspcap
40
+
41
+ ASPCAP provides multi-order spectral data objects, external continuum
42
+ normalization, and element-abundance fitting with FERRE for HGE.
43
+
44
+ - [Spec1D objects](https://github.com/dnidever/aspcap/blob/main/docs/spectrum.rst): single or multiple orders, unequal chip
45
+ lengths, masks, uncertainties, copying, and native-grid mapping.
46
+ - [External continuum normalization](https://github.com/dnidever/aspcap/blob/main/docs/continuum.rst): polynomial, spline,
47
+ median, percentile, and model-ratio methods with diagnostics.
48
+ - [FERRE abundance fitting](https://github.com/dnidever/aspcap/blob/main/docs/quickstart.rst): fit an element using fixed
49
+ global parameters and a supplied continuum.
50
+
51
+ Install the latest release from PyPI with:
52
+
53
+ ```sh
54
+ python -m pip install --upgrade aspcap
55
+ ```
56
+
57
+ The spectrum and continuum modules do not need a FERRE executable or Doppler
58
+ model files. Install [FERRE](https://github.com/dnidever/ferre) separately when
59
+ running spectral fits: `python -m pip install --upgrade ferre`.
60
+
61
+ ## Try the worked example
62
+
63
+ Install Python 3.9 or later and [FERRE](https://github.com/dnidever/ferre).
64
+ The example was verified with FERRE 5.1.3. From the repository checkout, run:
65
+
66
+ ```sh
67
+ python -m pip install -e .
68
+ aspcap abundances examples/one-star.json --output abundance.csv --pixels pixels.csv
69
+ ```
70
+
71
+ If `ferre` is outside your PATH, add `--ferre /path/to/ferre`. The example
72
+ uses a synthetic spectrum and a toy grid. Expect a raw `ALPHA` coordinate of
73
+ about 0.20 and a reported `[Mg/H]` of about −0.05, using four pixels and fixed
74
+ `METALS = -0.25`. The pixel CSV shows the normalized flux, uncertainty, model,
75
+ and whether each pixel was used. Add `--keep-runs` to inspect FERRE's input
76
+ files after a successful fit. A failed fit keeps its files and reports their
77
+ location.
78
+
79
+ ## Run your own fit
80
+
81
+ 1. Copy [one-star.json](https://github.com/dnidever/aspcap/blob/main/examples/one-star.json) and point it to your inputs.
82
+ Relative paths are resolved from the configuration file. Supply the global
83
+ fit as a dictionary with one starting value per grid label.
84
+ 2. Supply a spectrum CSV with `wavelength,flux,error,continuum` columns. The
85
+ spectrum must already be on the native rest-frame grid in the library's
86
+ wavelength units and air/vacuum convention. Give flux and one-sigma error
87
+ in the same units as the positive global continuum. The wrapper divides
88
+ both by that continuum and holds it fixed during the fit.
89
+ 3. Copy [mg.json](https://github.com/dnidever/aspcap/blob/main/examples/mg.json) and set the species, the one free grid label,
90
+ and one or more inclusive wavelength windows. Overlapping windows still
91
+ give each pixel weight one. Nonfinite flux and nonpositive or nonfinite
92
+ uncertainties get zero weight. Use `add_labels` to list any fixed logarithmic
93
+ coordinates to add to the fitted coordinate to report `[X/H]`. Leave it empty
94
+ if the fitted coordinate is already `[X/H]`. Verify this mapping and the
95
+ wavelength windows against the scientific conventions of your grid.
96
+
97
+ This version supports single-segment, non-PCA FERRE libraries with a positive
98
+ spectral resolution, either formatted ASCII or matching `.hdr` and `.unf`
99
+ files. Point `grid` to the ASCII library or to the binary library's `.hdr`.
100
+ The fit uses linear interpolation. The reported error is conditional on the
101
+ fixed global parameters and continuum. The reduced χ² column comes from FERRE.
102
+
103
+ ## Use from Python
104
+
105
+ ```python
106
+ from aspcap import Grid, fit_abundance
107
+
108
+ grid = Grid.read("examples/toy-grid.dat")
109
+ result, pixels = fit_abundance(
110
+ grid, wavelength, flux, error, continuum,
111
+ {"ALPHA": 0.0, "METALS": -0.25},
112
+ star_id="my-star", species="Mg", label="ALPHA",
113
+ windows=[(15002, 15005)], add_labels=["METALS"],
114
+ )
115
+ ```
116
+
117
+ Pass the four CSV columns as sequences. `result` is a dictionary and `pixels`
118
+ iterates over the diagnostic rows.
119
+
120
+ The FERRE protocol lives in `aspcap/ferre.py`, the abundance logic in
121
+ `aspcap/abundances.py`, and file input and output in `aspcap/cli.py`. Run
122
+ `python -m unittest discover -s tests -v` for the tests. Set
123
+ `ASPCAP_TEST_FERRE=/path/to/ferre` to include the integration test if FERRE
124
+ is outside your PATH.
125
+
126
+ ## Documentation
127
+
128
+ The [user guide](https://github.com/dnidever/aspcap/blob/main/docs/index.rst) includes a quickstart, input reference,
129
+ [Spec1D guide](https://github.com/dnidever/aspcap/blob/main/docs/spectrum.rst), [continuum methods](https://github.com/dnidever/aspcap/blob/main/docs/continuum.rst), and
130
+ Python API. The repository includes Read the Docs build configuration. To
131
+ preview the guide locally after installing ASPCAP:
132
+
133
+ ```sh
134
+ python -m pip install -r docs/requirements.txt
135
+ python -m sphinx -W -b html docs docs/_build/html
136
+ ```
137
+
138
+
139
+ The full-wavelength APOGEE DR17 M-giant test grid and detector weights are
140
+ included in ASPCAP installations.
141
+
142
+ ```sh
143
+ python -m pip install --upgrade aspcap
144
+ ```
145
+
146
+ See the [Grid walkthrough](https://github.com/dnidever/aspcap/blob/main/docs/grid.rst#fit-the-full-apogee-dr17-wavelength-grid)
147
+ for an example using the installed files.
148
+
149
+
150
+ ## Multi-order spectra and external continuum fitting
151
+
152
+ `Spec1D` follows Doppler's `(pixels, orders)` layout, accepts unequal-length
153
+ orders, preserves masks/metadata, and can map detector chips back to a native
154
+ wavelength grid. It imports no Doppler fitting code or model loaders. Existing
155
+ Doppler objects can be used directly with the continuum functions.
156
+
157
+ ```python
158
+ from aspcap import Spec1D, continuum
159
+
160
+ spec = Spec1D(flux_orders, wave=wavelength_orders, err=error_orders)
161
+ result = continuum.fit(spec, method="chebyshev", degree=4)
162
+ normalized = result.apply(spec) # independent copy
163
+ ```
164
+
165
+ Choose the estimator with `continuum.fit(spec, method=...)`:
166
+
167
+ | Method | Useful options | Defaults |
168
+ |---|---|---|
169
+ | `chebyshev` / `polynomial` | `degree`, `weighted`, `clip` | Degree 4, unweighted, no clipping |
170
+ | `spline` | `degree`, `smoothing`, `weighted`, `clip` | Degree 3, noise-based smoothing |
171
+ | `median` | `window`, `mode` | 151 pixels, mirror edges |
172
+ | `percentile` | `percentile`, `bins` | 90th percentile, 20 bins |
173
+ | `model_ratio` | `model`, `window`, `ratio_bounds`, `mode` | Model required; 151 pixels; ratios 0.1–10 |
174
+
175
+ Methods operate independently per order. Use `result.fit_mask`, `result.flags`,
176
+ `result.parameters`, and `result.settings` to inspect the estimate. Invalid
177
+ orders raise an error by default; `on_failure="mask"` returns flagged, masked
178
+ results instead. `result.apply(spec)` returns a copy; `inplace=True` updates the
179
+ input explicitly. All normalization here is outside FERRE. Applying a
180
+ continuum rescales both flux and error; it does not include uncertainty in the
181
+ continuum estimate. See [the spectrum guide](https://github.com/dnidever/aspcap/blob/main/docs/spectrum.rst),
182
+ [the continuum guide](https://github.com/dnidever/aspcap/blob/main/docs/continuum.rst), and the runnable
183
+ [example](https://github.com/dnidever/aspcap/blob/main/examples/spectrum_continuum.py). The core design is adapted from
184
+ [Doppler Spec1D](https://github.com/dnidever/doppler/blob/6e165f87c6d766eff6eaa1fbee2c82be5bb30cc0/doppler/spec1d.py);
185
+ its MIT notice is retained in `LICENSE-DOPPLER`.
@@ -0,0 +1,16 @@
1
+ aspcap/__init__.py,sha256=J2jMY1aNsd4n8VeE4Rs3hXXlWnuAwgwQKKV0bjGSfco,257
2
+ aspcap/abundances.py,sha256=qeakgJZlkV9dT-KS9lH9kq8Bjgrf4e5IeujovZV1Uzg,3771
3
+ aspcap/cli.py,sha256=Vxm_1I02DUeJVaRHQ2jlN2uom67ibfhYKOHm0vsKGUk,2824
4
+ aspcap/continuum.py,sha256=xOCC33yhoMUZWpsmuhRAnPZ-CNw2AH1dHM1do2p55p4,18842
5
+ aspcap/ferre.py,sha256=XlniahdFhlDql0g-sVM9MHlBnSOWE1nezefcuJnOiHI,20332
6
+ aspcap/spectrum.py,sha256=gvMipWnNBL2W2gi6zptkP6KgNCPzI6_8JhRcX0pbefQ,21428
7
+ aspcap/data/apogee-dr17-mgiant-full-weights.json,sha256=PNVLHyjX4kxAMWNRHZWc1LZncB64GNFS2FgssR9_UrU,25726
8
+ aspcap/data/apogee-dr17-mgiant-full.hdr,sha256=_PfcExQ2nPFz_LwrFdY6UEgFeZfla2hIgebnH80xLkg,257
9
+ aspcap/data/apogee-dr17-mgiant-full.unf,sha256=EcMFSWRzmTk8w648qNWw_9k6if_zdaLFhfkrGJGnNMQ,4287500
10
+ aspcap-0.2.0.dist-info/licenses/LICENSE,sha256=0npGIjCMX1gaJWGJ30LnukyktmQ3iCEzJ_q_Brh2GRs,1070
11
+ aspcap-0.2.0.dist-info/licenses/LICENSE-DOPPLER,sha256=ykcdTlNxwsfbg5SlIXBQdRpg-4pWgj8LO1GU6ja8J-Q,1070
12
+ aspcap-0.2.0.dist-info/METADATA,sha256=I3i5thFGyNJ885ArPM1Pe4WBOLQO1BAKOG-2xVONyR8,8873
13
+ aspcap-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
14
+ aspcap-0.2.0.dist-info/entry_points.txt,sha256=bBWh7SBw-W3yCKtP10uLztL1LUbOFSAirmt7i74iQTg,43
15
+ aspcap-0.2.0.dist-info/top_level.txt,sha256=dSqh_rTfHcziHzPXNJWp1S9VIW8K0IrWbtnN3QlNavM,7
16
+ aspcap-0.2.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ aspcap = aspcap.cli:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 David Nidever
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2019 David Nidever
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ aspcap