astro-hexmaps 5.0.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,424 @@
1
+ Metadata-Version: 2.4
2
+ Name: astro-hexmaps
3
+ Version: 5.0.0
4
+ Summary: HexMaps: Hexagonal-grid Multi-data Analysis and Processing Software for multi-wavelength astronomical datasets.
5
+ Author-email: Jakob den Brok <jadenbrok@mpia.de>, Lukas Neumann <lukas.neumann@eso.org>
6
+ License: MIT License
7
+
8
+ Copyright (c) 2025 Jakob den Brok, Lukas Neumann
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: Homepage, https://github.com/PhangsTeam/HexMaps
29
+ Project-URL: Repository, https://github.com/PhangsTeam/HexMaps
30
+ Project-URL: Issues, https://github.com/PhangsTeam/HexMaps/issues
31
+ Project-URL: Documentation, https://hexmaps.readthedocs.io/en/latest/
32
+ Keywords: astronomy,astrophysics,FITS,radio,pipeline
33
+ Classifier: Development Status :: 4 - Beta
34
+ Classifier: Intended Audience :: Science/Research
35
+ Classifier: Topic :: Scientific/Engineering :: Astronomy
36
+ Classifier: License :: OSI Approved :: MIT License
37
+ Classifier: Programming Language :: Python :: 3
38
+ Classifier: Programming Language :: Python :: 3.10
39
+ Classifier: Programming Language :: Python :: 3.11
40
+ Classifier: Programming Language :: Python :: 3.12
41
+ Classifier: Programming Language :: Python :: 3.13
42
+ Requires-Python: >=3.10
43
+ Description-Content-Type: text/markdown
44
+ License-File: LICENSE
45
+ Requires-Dist: astropy>=5.0
46
+ Requires-Dist: numpy>=1.22
47
+ Requires-Dist: pandas>=1.4
48
+ Requires-Dist: scipy>=1.7
49
+ Requires-Dist: matplotlib>=3.4
50
+ Requires-Dist: reproject>=0.9
51
+ Requires-Dist: radio_beam>=0.3.4
52
+ Requires-Dist: spectral_cube>=0.6
53
+ Requires-Dist: scikit-image>=0.19
54
+ Provides-Extra: dev
55
+ Requires-Dist: pytest>=7.0; extra == "dev"
56
+ Requires-Dist: pytest-cov; extra == "dev"
57
+ Requires-Dist: ruff; extra == "dev"
58
+ Requires-Dist: black; extra == "dev"
59
+ Provides-Extra: docs
60
+ Requires-Dist: sphinx; extra == "docs"
61
+ Requires-Dist: sphinx-rtd-theme; extra == "docs"
62
+ Requires-Dist: numpydoc; extra == "docs"
63
+ Dynamic: license-file
64
+
65
+ <!-- back-to-top anchor -->
66
+ <a name="readme-top"></a>
67
+
68
+ <br />
69
+ <div align="center">
70
+ <a href="https://github.com/lukas-neumann-astro/astro-HexMaps">
71
+ <img src="images/logo.png" alt="Logo" width="100" height="100">
72
+ </a>
73
+
74
+ <h3 align="center">HexMaps</h3>
75
+
76
+ <p align="center">
77
+ Hexagonal-grid Multi-data Analysis and Processing Software
78
+ <br />
79
+ <a href="https://astro-hexmaps.readthedocs.io/en/latest/"><strong>Explore the docs »</strong></a>
80
+ <br /><br />
81
+ <a href="https://astro-hexmaps.readthedocs.io/en/latest/quickstart.html">View Demo</a>
82
+ ·
83
+ <a href="https://github.com/lukas-neumann-astro/astro-HexMaps/issues">Report Bug</a>
84
+ ·
85
+ <a href="https://github.com/lukas-neumann-astro/astro-HexMaps/issues">Request Feature</a>
86
+ </p>
87
+ </div>
88
+
89
+ [![Contributors][contributors-shield]][contributors-url]
90
+ [![Forks][forks-shield]][forks-url]
91
+ [![Stargazers][stars-shield]][stars-url]
92
+ [![Issues][issues-shield]][issues-url]
93
+ [![MIT License][license-shield]][license-url]
94
+
95
+ ---
96
+
97
+ ## About the Project
98
+
99
+ [![HexMaps screenshot][product-screenshot]](https://astro-hexmaps.readthedocs.io/en/latest/)
100
+
101
+ **HexMaps** is a Python package for homogenizing and analysing
102
+ multi-wavelength astronomical datasets on hexagonal grids. It is ideally
103
+ suited for combining a heterogeneous set of 2D maps and 3D spectral cubes
104
+ observed at different angular resolutions and pixel scales into a single,
105
+ science-ready table for sightline-by-sightline analysis.
106
+
107
+ Given a set of input data, HexMaps:
108
+
109
+ 1. **Regrids** all maps and cubes onto a common hexagonal sampling grid at a
110
+ user-specified angular resolution, convolving each dataset to a common
111
+ beam.
112
+ 2. **Processes** each spectral cube: builds an S/N mask from a reference line,
113
+ then computes moment maps (integrated intensity, mean velocity, line width,
114
+ peak temperature, rms, equivalent width) and shuffled spectra for every
115
+ line.
116
+ 3. **Writes FITS** output: PPV-native moment maps, optionally convolved cubes,
117
+ and 2D band images — all on the same pixel grid as the overlay cube.
118
+
119
+ The primary deliverable is an Astropy `.ecsv` table with one row per
120
+ hexagonal sightline, containing all spectra, moment maps, and 2D map values
121
+ side by side. This makes line-ratio analysis, radial profile extraction, and
122
+ spectral stacking straightforward with standard Python tools.
123
+
124
+ HexMaps is the successor to
125
+ [PyStructure (PhangsTeam)](https://github.com/PhangsTeam/PyStructure),
126
+ refactored into a pip-installable package with a clean CLI, an INI-style
127
+ single configuration file, and a modular stage architecture.
128
+
129
+ <p align="right">(<a href="#readme-top">back to top</a>)</p>
130
+
131
+ ---
132
+
133
+ ## Getting Started
134
+
135
+ ### Prerequisites
136
+
137
+ HexMaps requires **Python ≥ 3.10**. All Python dependencies are installed
138
+ automatically by pip:
139
+
140
+ ```
141
+ astropy numpy pandas scipy matplotlib
142
+ reproject radio_beam spectral_cube scikit-image
143
+ ```
144
+
145
+ ### Installation
146
+
147
+ ```bash
148
+ # From PyPI (once published)
149
+ pip install astro-hexmaps
150
+
151
+ # From GitHub — latest version
152
+ pip install git+https://github.com/lukas-neumann-astro/astro-HexMaps.git
153
+
154
+ # Editable / development install
155
+ git clone https://github.com/lukas-neumann-astro/astro-HexMaps.git
156
+ cd astro-HexMaps
157
+ pip install -e ".[dev]"
158
+ ```
159
+
160
+ <p align="right">(<a href="#readme-top">back to top</a>)</p>
161
+
162
+ ---
163
+
164
+ ## Usage
165
+
166
+ ### 1 — Initialise a working directory
167
+
168
+ ```bash
169
+ # Creates config.txt, keys/, and run_hexmaps.py in the current folder
170
+ hexmaps --init
171
+
172
+ # Or target a specific directory
173
+ hexmaps --init --workdir ~/my_project
174
+ cd ~/my_project
175
+ ```
176
+
177
+ This copies template configuration files into your working directory.
178
+ The installed package is never modified.
179
+
180
+ ### 2 — Download the example dataset *(optional)*
181
+
182
+ To try the pipeline immediately with real data, download the bundled
183
+ NGC 5194 example dataset (~46 MB):
184
+
185
+ ```bash
186
+ hexmaps --download-example --workdir ~/my_project
187
+ ```
188
+
189
+ This fetches the input FITS files (CO(2–1) cube, CO(1–0) cube, SPIRE 250 µm
190
+ map and associated files) into `~/my_project/data/`. The bundled `config.txt`
191
+ is already configured to use these files. Use `--force` to re-download
192
+ existing files.
193
+
194
+ You can also download the example Jupyter notebook separately:
195
+
196
+ ```bash
197
+ hexmaps --download-notebook --workdir ~/my_project
198
+ ```
199
+
200
+ ### 3 — Edit your configuration
201
+
202
+ | File | What to configure | How often |
203
+ |------|-------------------|-----------|
204
+ | `config.txt` | data directory, target list, overlay cube, maps/cubes, target resolution, masking, output flags | every run |
205
+ | `keys/target_definitions.txt` | sky coordinates, distance, inclination per target | only when adding new targets |
206
+ | `keys/hfs_lines.txt` *(optional)* | Hyperfine structure line definitions | rarely |
207
+
208
+ `config.txt` replaces the `PyStructure.conf` file of the old PyStructure.
209
+
210
+ > **Migrating from PyStructure?** Use the conversion scripts:
211
+ >
212
+ > ```bash
213
+ > python conversion_from_pystructure/config_conversion.py PyStructure.conf config.txt
214
+ > python conversion_from_pystructure/target_definitions_conversion.py geometry.txt keys/target_definitions.txt
215
+ > python conversion_from_pystructure/hfs_lines_conversion.py hfs_lines.txt keys/hfs_lines.txt
216
+ > ```
217
+
218
+ ### 4 — Run
219
+
220
+ ```bash
221
+ # Default: regrid + products (writes .ecsv database)
222
+ hexmaps --conf config.txt
223
+
224
+ # All stages including FITS output
225
+ hexmaps --conf config.txt --stages all
226
+
227
+ # Single target
228
+ hexmaps --conf config.txt --targets ngc5194
229
+
230
+ # Also write a log file
231
+ hexmaps --conf config.txt --log_file run.log
232
+ ```
233
+
234
+ Or from Python:
235
+
236
+ ```python
237
+ import hexmaps as hm
238
+
239
+ handler = hm.PipelineHandler(conf_path="config.txt")
240
+ handler.run_all() # regrid + products
241
+ handler.run_stages(["regrid", "products", "fits"]) # include FITS output
242
+ handler.run_stages(["fits"], targets=["ngc5194"]) # re-run one stage only
243
+ ```
244
+
245
+ *For more examples, please refer to the [Documentation](https://astro-hexmaps.readthedocs.io/en/latest/).*
246
+
247
+ <p align="right">(<a href="#readme-top">back to top</a>)</p>
248
+
249
+ ---
250
+
251
+ ## Repository Layout
252
+
253
+ ```
254
+ astro-HexMaps/ ← git repository root (pip install this)
255
+ ├── hexmaps/ ← installable package
256
+ │ ├── handler_keys.py reads & validates config and key files
257
+ │ ├── handler_targets.py target geometry lookups
258
+ │ ├── handler_pipeline.py PipelineHandler: stage orchestration
259
+ │ ├── stage_regrid.py hex grid + convolution + sampling → .ecsv
260
+ │ ├── stage_products.py spectral masking, moments, shuffled spectra
261
+ │ ├── stage_fits.py FITS moment maps / cubes / band images
262
+ │ ├── utils_fits.py FITS/WCS helpers (convolution, reprojection)
263
+ │ ├── utils_table.py table I/O, spectral shuffle, moments
264
+ │ ├── hexmaps_analysis.py HexMapsAnalysis class (importable as part of package)
265
+ │ ├── logger.py centralised stage-labelled logger
266
+ │ ├── init_workdir.py --init scaffolding
267
+ │ ├── download_example.py --download-example and --download-notebook
268
+ │ ├── cli.py hexmaps console-script entry point
269
+ │ ├── test_hexmaps.py unit and integration tests
270
+ │ └── templates/ template files copied by --init
271
+ │ ├── config.txt
272
+ │ ├── run_hexmaps.py
273
+ │ └── keys/
274
+ │ ├── target_definitions.txt
275
+ │ └── hfs_lines.txt
276
+ ├── config.txt ← example / template config file
277
+ ├── keys/
278
+ │ ├── target_definitions.txt ← target geometry table (PHANGS example)
279
+ │ └── hfs_lines.txt ← hyperfine structure definitions
280
+ ├── analysis/
281
+ │ └── hexmaps_example.ipynb example analysis notebook
282
+ ├── conversion_from_pystructure/ ← migration scripts from old PyStructure
283
+ │ ├── config_conversion.py
284
+ │ ├── target_definitions_conversion.py
285
+ │ └── hfs_lines_conversion.py
286
+ ├── data/ ← example FITS input (NGC 5194)
287
+ ├── docs/ ← Sphinx / Read the Docs source
288
+ ├── images/ ← README images (logo, screenshot)
289
+ ├── run_hexmaps.py ← example run script
290
+ └── pyproject.toml
291
+ ```
292
+
293
+ ---
294
+
295
+ ## Pipeline Stages
296
+
297
+ The pipeline runs three stages always in this order:
298
+
299
+ | Stage | Module | Default | Description |
300
+ |-------|--------|---------|-------------|
301
+ | `regrid` | `stage_regrid.py` | ✓ | Generate the hexagonal sampling grid; convolve and sample all maps & cubes onto it; write the `.ecsv` database |
302
+ | `products` | `stage_products.py` | ✓ | Build the S/N mask; compute moment maps (mom0/1/2, Tpeak, rms, EW) and shuffled spectra |
303
+ | `fits` | `stage_fits.py` | optional | Compute PPV-native moment maps on the convolved cubes; write FITS images |
304
+
305
+ The default run (`hexmaps --conf config.txt`) executes **regrid + products** only.
306
+ Add `--stages all` to also run the fits stage.
307
+
308
+ ---
309
+
310
+ ## Reading the Output
311
+
312
+ ```python
313
+ from hexmaps.utils_table import load_hexmaps
314
+ import matplotlib.pyplot as plt
315
+
316
+ table = load_hexmaps("output/ngc5194_hexmaps_27p0as_2025_01_01.ecsv")
317
+
318
+ plt.figure(figsize=(5, 5))
319
+ plt.scatter(table["RA"], table["DEC"],
320
+ c=table["MOM0_12CO21"], marker="h", s=60, cmap="inferno")
321
+ plt.gca().invert_xaxis()
322
+ plt.xlabel("R.A. [deg]"); plt.ylabel("Dec. [deg]")
323
+ plt.show()
324
+ ```
325
+
326
+ For richer quicklook plots use the `HexMapsAnalysis` class, which is now
327
+ part of the installed package:
328
+
329
+ ```python
330
+ from hexmaps import HexMapsAnalysis
331
+
332
+ db = HexMapsAnalysis("output/ngc5194_hexmaps_27p0as_2025_01_01.ecsv")
333
+ db.quickplot_map("12CO21")
334
+ db.quickplot_spectrum("12CO21")
335
+
336
+ # Recover provenance information embedded at run time
337
+ print(db.get_config()) # recover config.txt used for this run
338
+ print(db.get_log()) # recover the full pipeline log
339
+ hdr = db.get_input_header("12CO21") # recover raw FITS header of input cube
340
+ print(db.list_input_headers()) # list all embedded headers
341
+ ```
342
+
343
+ <p align="right">(<a href="#readme-top">back to top</a>)</p>
344
+
345
+ ---
346
+
347
+ ## Roadmap
348
+
349
+ - [ ] PyPI release
350
+ - [ ] Expanded documentation and tutorials
351
+ - [ ] Additional analysis utilities in `hexmaps_analysis.py`
352
+ - [ ] Various feature updates (e.g. "island-method" masking, chunking for large datasets)
353
+
354
+ See the [open issues](https://github.com/lukas-neumann-astro/astro-HexMaps/issues)
355
+ for a full list of proposed features and known issues.
356
+
357
+ <p align="right">(<a href="#readme-top">back to top</a>)</p>
358
+
359
+ ---
360
+
361
+ ## Contributing
362
+
363
+ Contributions are greatly appreciated! If you have a suggestion that would
364
+ make this better, please fork the repository and create a pull request. You
365
+ can also open an issue with the tag "enhancement".
366
+
367
+ 1. Fork the Project
368
+ 2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
369
+ 3. Commit your Changes (`git commit -m 'Add AmazingFeature'`)
370
+ 4. Push to the Branch (`git push origin feature/AmazingFeature`)
371
+ 5. Open a Pull Request
372
+
373
+ <p align="right">(<a href="#readme-top">back to top</a>)</p>
374
+
375
+ ---
376
+
377
+ ## License
378
+
379
+ Distributed under the MIT License — see [LICENSE](LICENSE) for details.
380
+
381
+ <p align="right">(<a href="#readme-top">back to top</a>)</p>
382
+
383
+ ---
384
+
385
+ ## Contact
386
+
387
+ Dr. Jakob den Brok — jadenbrok@mpia.de
388
+
389
+ Dr. Lukas Neumann — lukas.neumann@eso.org
390
+
391
+ Project Link: [https://github.com/lukas-neumann-astro/astro-HexMaps](https://github.com/lukas-neumann-astro/astro-HexMaps)
392
+
393
+ <p align="right">(<a href="#readme-top">back to top</a>)</p>
394
+
395
+ ---
396
+
397
+ ## Acknowledgements
398
+
399
+ HexMaps builds on the original PyStructure IDL scripts developed within the
400
+ PHANGS collaboration. The routines have been updated, improved, and fully
401
+ rewritten in Python.
402
+
403
+ The code has been employed in several peer-reviewed publications including
404
+ den Brok et al. (2021, 2022, 2023, 2025), Eibensteiner et al. (2022, 2023),
405
+ Neumann et al. (2023), Stuber et al. (2025), and others. See the
406
+ [documentation](https://astro-hexmaps.readthedocs.io) for the full list.
407
+
408
+ * [PHANGS collaboration](https://sites.google.com/view/phangs/home)
409
+ * [Prof. Bigiel's research group](https://www.astro.uni-bonn.de/~bigiel/)
410
+
411
+ <p align="right">(<a href="#readme-top">back to top</a>)</p>
412
+
413
+ <!-- MARKDOWN LINKS & IMAGES -->
414
+ [contributors-shield]: https://img.shields.io/github/contributors/lukas-neumann-astro/astro-HexMaps.svg?style=for-the-badge
415
+ [contributors-url]: https://github.com/lukas-neumann-astro/astro-HexMaps/graphs/contributors
416
+ [forks-shield]: https://img.shields.io/github/forks/lukas-neumann-astro/astro-HexMaps.svg?style=for-the-badge
417
+ [forks-url]: https://github.com/lukas-neumann-astro/astro-HexMaps/network/members
418
+ [stars-shield]: https://img.shields.io/github/stars/lukas-neumann-astro/astro-HexMaps.svg?style=for-the-badge
419
+ [stars-url]: https://github.com/lukas-neumann-astro/astro-HexMaps/stargazers
420
+ [issues-shield]: https://img.shields.io/github/issues/lukas-neumann-astro/astro-HexMaps.svg?style=for-the-badge
421
+ [issues-url]: https://github.com/lukas-neumann-astro/astro-HexMaps/issues
422
+ [license-shield]: https://img.shields.io/github/license/lukas-neumann-astro/astro-HexMaps.svg?style=for-the-badge
423
+ [license-url]: https://github.com/lukas-neumann-astro/astro-HexMaps/blob/master/LICENSE
424
+ [product-screenshot]: images/screenshot.png
@@ -0,0 +1,25 @@
1
+ astro_hexmaps-5.0.0.dist-info/licenses/LICENSE,sha256=dDUwijnENEvwRJ_UPOA8rkKx4iWyZbFW774NuSmcM5k,1086
2
+ hexmaps/__init__.py,sha256=1nfmP0g1GGwPB-T_d44B0hoUFy2nTJrRS1a1zeDkwGU,506
3
+ hexmaps/cli.py,sha256=lJdxn4wf3ZFTH059t0CBAL50Vddm7ljwB3J0fItcebQ,5941
4
+ hexmaps/download_example.py,sha256=wBUVo5vUQwo8IrG7JC6uDlhXZLCScZ8ewZplMPjd2r0,7865
5
+ hexmaps/handler_keys.py,sha256=ShY333geJ5uVm1DYMQx-FJSMG_gdb8CWsoDQy3_R7Ds,37683
6
+ hexmaps/handler_pipeline.py,sha256=m51_M6uZsBdGGY9I3-XlGxB33t2GtSuZHPjVZcQr9Qc,15795
7
+ hexmaps/handler_targets.py,sha256=fv-leKVddozzmaYb77mohlJJXG5QfClnnDR3cJtclHA,6467
8
+ hexmaps/hexmaps_analysis.py,sha256=g1m0gHei3ZErfbviEgc2L5T2vD_PjwFb3BFwPQ55jgY,22319
9
+ hexmaps/init_workdir.py,sha256=SRczrwwyIT_lax6bIogjiAUtTE8KMebjnkENDlW-UHM,4052
10
+ hexmaps/logger.py,sha256=U3XvCcuaSes1HMpHX4WHcV2wkx4CyaFZpM1lqeo2yM8,10037
11
+ hexmaps/stage_fits.py,sha256=1Epa13xgWNwElEhAy4GnALsiJsceErdqC6dlUwohLJs,60141
12
+ hexmaps/stage_products.py,sha256=Z5xtbYGd5GdXXjJHvvwqb4meo2KgLXsloFkVOFxPOLo,32452
13
+ hexmaps/stage_regrid.py,sha256=j3fh8VRLHeRKT4ZdfZIEd0y63-Y3sjn4dFXk7KYoqVU,48700
14
+ hexmaps/test_hexmaps.py,sha256=sCNVqsi7krQGtZaT11hw6aezCCFIow7fXT4xJRlfYAM,47643
15
+ hexmaps/utils_fits.py,sha256=HZOMsCw66FZppyqJiit9J1DjCz6WxH1w_pfnVOg94eo,50470
16
+ hexmaps/utils_table.py,sha256=4PlvEAllIUC5Iqj9YnFIcQsHW99YZe5I3UgzwdJh2yY,26476
17
+ hexmaps/templates/config.txt,sha256=KAZ-3SuCfxmvM9YJ2GCbkHrVTYn_8p4ytAAFXOISQoA,9265
18
+ hexmaps/templates/run_hexmaps.py,sha256=wPBQ6GfVXs1fZo4rjPTCBt4RIaV0FlUtD7Le4C9PB7A,1990
19
+ hexmaps/templates/keys/hfs_lines.txt,sha256=AGNVssshyifJ6_C-QEPB2Hu3RLtjiim2DTWAbYBFdrQ,769
20
+ hexmaps/templates/keys/target_definitions.txt,sha256=5CCeA36jB4ybWMAx5VG5G2I05Y1vnq_uruMjyXV3cWA,17505
21
+ astro_hexmaps-5.0.0.dist-info/METADATA,sha256=iGjvhm86wyTdeLWg1wQzOLcoaK22Zyz30JKUSA_55yE,16389
22
+ astro_hexmaps-5.0.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
23
+ astro_hexmaps-5.0.0.dist-info/entry_points.txt,sha256=YLzBVfl3moM2ErOgmT3RXgV-mTr-3ymH_kz3A-mG2cQ,45
24
+ astro_hexmaps-5.0.0.dist-info/top_level.txt,sha256=td2BoddhONjq9KwC3OGG3Uy5qP7CswwbusohKYtLjM0,8
25
+ astro_hexmaps-5.0.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (83.0.0)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ hexmaps = hexmaps.cli:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Jakob den Brok, Lukas Neumann
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
+ hexmaps
hexmaps/__init__.py ADDED
@@ -0,0 +1,14 @@
1
+ """
2
+ HexMaps Pipeline: homogenize and analyze multi-wavelength astronomical datasets.
3
+ """
4
+
5
+ __author__ = "J. den Brok & L. Neumann"
6
+ __version__ = "5.0.0"
7
+ __email__ = "jadenbrok@mpia.de & lukas.neumann@eso.org"
8
+ __credits__ = ["M. Jimenez-Donaire", "E. Rosolowsky", "A. Leroy", "I. Beslic"]
9
+
10
+ from hexmaps.handler_pipeline import PipelineHandler
11
+ from hexmaps.init_workdir import init_workdir
12
+ from hexmaps.hexmaps_analysis import HexMapsAnalysis
13
+
14
+ __all__ = ["PipelineHandler", "init_workdir", "HexMapsAnalysis"]
hexmaps/cli.py ADDED
@@ -0,0 +1,186 @@
1
+ """
2
+ hexmaps.cli — entry point for the `hexmaps` console script.
3
+
4
+ Installed by pip via pyproject.toml [project.scripts]:
5
+ hexmaps = "hexmaps.cli:main"
6
+
7
+ Usage
8
+ -----
9
+ Initialise a working directory (copies key templates + run script):
10
+ hexmaps --init
11
+ hexmaps --init --workdir ./my_project
12
+
13
+ Run the pipeline (from inside a working directory):
14
+ hexmaps --conf config.txt
15
+ hexmaps --conf config.txt --stages regrid products
16
+ hexmaps --conf config.txt --targets ngc5194
17
+ hexmaps --conf config.txt --log_file hexmaps_run.log
18
+ """
19
+
20
+ import argparse
21
+ import sys
22
+
23
+ ALL_STAGES = ["regrid", "products", "fits"]
24
+ DATABASE_STAGES = ["regrid", "products"]
25
+
26
+
27
+ def parse_args(argv=None):
28
+ parser = argparse.ArgumentParser(
29
+ description="HexMaps: homogenize and analyze multi-wavelength astronomical datasets.",
30
+ formatter_class=argparse.RawDescriptionHelpFormatter,
31
+ epilog=__doc__,
32
+ )
33
+
34
+ # --- Init mode ---
35
+ parser.add_argument(
36
+ "--init",
37
+ action="store_true",
38
+ help=(
39
+ "Initialise a new working directory: copies key-file templates "
40
+ "and a run script. Use --workdir to set the destination."
41
+ ),
42
+ )
43
+ parser.add_argument(
44
+ "--workdir",
45
+ default=".",
46
+ help="Working directory to initialise (used with --init). Default: current directory.",
47
+ )
48
+ parser.add_argument(
49
+ "--overwrite",
50
+ action="store_true",
51
+ help="Overwrite existing files when using --init.",
52
+ )
53
+ parser.add_argument(
54
+ "--download-example",
55
+ action="store_true",
56
+ default=False,
57
+ help=(
58
+ "Download the NGC 5194 example dataset (~46 MB) into the data/ "
59
+ "sub-directory of --workdir. Run after --init to get data you "
60
+ "can process immediately with the bundled config.txt."
61
+ ),
62
+ )
63
+ parser.add_argument(
64
+ "--download-notebook",
65
+ action="store_true",
66
+ default=False,
67
+ help=(
68
+ "Download the HexMaps example Jupyter notebook "
69
+ "(hexmaps_example.ipynb) into --workdir."
70
+ ),
71
+ )
72
+ parser.add_argument(
73
+ "--force",
74
+ action="store_true",
75
+ default=False,
76
+ help="Overwrite existing files when using --download-example.",
77
+ )
78
+
79
+ # --- Run mode ---
80
+ parser.add_argument(
81
+ "--conf",
82
+ default=None,
83
+ help="Path to your config.txt configuration file.",
84
+ )
85
+ parser.add_argument(
86
+ "--stages",
87
+ nargs="+",
88
+ choices=ALL_STAGES + ["all"],
89
+ default=None,
90
+ help=(
91
+ f"Pipeline stage(s) to run: {', '.join(ALL_STAGES)}, or 'all' to run every stage. "
92
+ f"Default: {' '.join(DATABASE_STAGES)} (fits is optional and not run by default)."
93
+ ),
94
+ )
95
+ parser.add_argument(
96
+ "--targets",
97
+ nargs="+",
98
+ default=None,
99
+ help="Target name(s) to process. Default: all targets in config.txt.",
100
+ )
101
+ parser.add_argument(
102
+ "--quiet",
103
+ action="store_true",
104
+ help="Suppress informational output.",
105
+ )
106
+ parser.add_argument(
107
+ "--log_file",
108
+ default=None,
109
+ help="Write all log messages to this file in addition to stdout.",
110
+ )
111
+
112
+ return parser.parse_args(argv)
113
+
114
+
115
+ def main(argv=None):
116
+ args = parse_args(argv)
117
+
118
+ # ------------------------------------------------------------------
119
+ # --init mode: scaffold a working directory and exit
120
+ # ------------------------------------------------------------------
121
+ if args.init:
122
+ from hexmaps.init_workdir import init_workdir
123
+
124
+ try:
125
+ init_workdir(workdir=args.workdir, overwrite=args.overwrite)
126
+ except FileExistsError as exc:
127
+ print(f"[ERROR] {exc}")
128
+ print("[ERROR] Use --overwrite to replace existing files.")
129
+ sys.exit(1)
130
+ return
131
+
132
+ # ------------------------------------------------------------------
133
+ # --download-example mode: fetch NGC 5194 example data and exit
134
+ # ------------------------------------------------------------------
135
+ if args.download_example:
136
+ from hexmaps.download_example import download_example_data
137
+
138
+ download_example_data(workdir=args.workdir, force=args.force)
139
+ return
140
+
141
+ # ------------------------------------------------------------------
142
+ # --download-notebook mode: fetch example Jupyter notebook and exit
143
+ # ------------------------------------------------------------------
144
+ if args.download_notebook:
145
+ from hexmaps.download_example import download_notebook
146
+
147
+ download_notebook(workdir=args.workdir, force=args.force)
148
+ return
149
+
150
+ # ------------------------------------------------------------------
151
+ # Run mode
152
+ # ------------------------------------------------------------------
153
+ if args.conf is None:
154
+ print(
155
+ "[ERROR] --conf is required when not using --init.\n"
156
+ " Example: hexmaps --conf config.txt\n"
157
+ " To set up a new project: hexmaps --init"
158
+ )
159
+ sys.exit(1)
160
+
161
+ try:
162
+ from hexmaps import PipelineHandler
163
+ except ImportError as exc:
164
+ print(f"[ERROR] Could not import hexmaps: {exc}")
165
+ sys.exit(1)
166
+
167
+ raw_stages = args.stages if args.stages else DATABASE_STAGES
168
+ # "all" is a convenience alias for ALL_STAGES; run_stages also handles
169
+ # it, but expanding here gives a cleaner log line.
170
+ stages = ALL_STAGES if raw_stages == ["all"] else raw_stages
171
+ handler = PipelineHandler(
172
+ conf_path=args.conf, verbose=not args.quiet, log_file=args.log_file
173
+ )
174
+
175
+ try:
176
+ handler.run_stages(stages=stages, targets=args.targets)
177
+ except Exception as exc:
178
+ print(f"[ERROR] Pipeline terminated unexpectedly: {exc}")
179
+ sys.exit(1)
180
+
181
+ if not all(handler.run_success.values()):
182
+ sys.exit(1)
183
+
184
+
185
+ if __name__ == "__main__":
186
+ main()