Welcome to the pykoala-tutorials repository! This repository is designed to provide a comprehensive set of tutorials to help you get started with the pykoala Python library. pykoala is a powerful tool for performing data reduction and manipulation tasks with integral field spectroscopic data.
The pykoala library is designed to facilitate the processing and analysis of integral field spectroscopic (IFS) data. These data are essential in various fields of astronomy and astrophysics, providing spatially resolved spectra that allow for detailed studies of astronomical objects.
Reducing IFS data involves several steps to ensure that the raw data are transformed into scientifically useful spectra. Here is an outline of these steps:
-
Raw exposures preprocessing
a. Bad pixels: identify and remove/flag cosmic ray hits or bad pixels from the frames.
b. Bias Subtraction: remove the electronic noise by subtracting the bias frame from all science and calibration frames.
c. Dark Subtraction: remove the thermal noise by subtracting the dark frame from all science and calibration frames.
d. Flat Field Correction: correct for pixel-to-pixel sensitivity variations by dividing the science frames by a (detector) flat field frame.
-
Fiber (Tramline) Extraction
Identify and extract individual fiber spectra from the raw exposures. This involves mapping the detector pixels to specific fibers based on the instrument's layout, usually using a trace solution derived from a fiber flat field or a dedicated tramline map.
The resulting product is the so-called Raw Stacked Spectra (RSS) containing the individual spectra of each fibre.
-
Wavelength Calibration
a. Arc Lamp Calibration: use arc lamp RSS spectra to identify known emission lines and create a wavelength solution.
b. Sky Line Calibration: fine-tune the wavelength calibration using sky emission lines, if available.
-
Fiber Throughput
a. Fiber Throughput Correction: correct for variations in fiber throughput by comparing the relative intensities of a uniformly illuminated source: e.g. a dome/twilight flat exposure or a selection of sky emission lines (estimated for each invidual frame).
-
Atmospheric effects
a. Sky Emission Subtraction: subtract the sky emission by using dedicated sky frames, sky fibres or by identifying sky-dominated regions within the field of view.
b. Telluric Absorption Correction: observe a telluric standard star or use an atmospheric model (e.g. Molecfit) to correct for absorption features introduced by the Earth's atmosphere.
c. Atmospheric Extinction Correction: correct for atmospheric extinction using the standard star observation or a model of the atmospheric extinction.
-
Flux Calibration
a. Spectrograph Response Function: use observations of standard stars with known spectral energy distribution to calibrate the spectrograph walenght-dependent sensitivity function.
-
Astrometry Correction
a RSS frames registration: estimate the astrometric offset between individual RSS exposures by cross-correlating them or using external ancillary data.
b Absolute Astrometric Calibration: if required, use reference catalogs to provide an absolute calibration.
-
Data Cube Construction
a. Combine Individual RSS Exposures: combine multiple exposures of the same target into a 3D data cube. This is essential for:
- Increasing the signal-to-noise ratio
- Removing cosmic rays / outliers
- Accounting for gaps between fibres of individual exposures and improve spatial sampling.
-
Final Calibration
a. Final Flux Calibration: apply the final flux calibration to the entire data cube using the observed standard stars.
-
Quality Assessment
a. Check for Artifacts: inspect the data cube for any residual artifacts, such as imperfect sky subtraction or cosmic ray hits.
b. Signal-to-Noise Ratio: evaluate the signal-to-noise ratio across the field and spectrum to ensure data quality.
Currently, the entry point of pykoala are wavelength-calibrated Raw Stacked Spectra (RSS) data, althought the wavelength calibration accuracy doesn't need to be perfect, since pykoala includes tools for correcting fibre-to-fibre wavelength offsets.
The library provides processing tools covering points [2-9] of the previous section:
- Wavelength offset corrections
- Fibre throughput
- Atmospheric corrections (sky emission, telluric absorption and atmospheric extinction)
- Flux calibration using standard stars
- Astrometric calibrations either relative or absolute (using external data)
- Data cube interpolation
- Quality control visualization tools
This repository contains a series of tutorials aimed at demonstrating how to effectively use pykoala to handle IFS data. Each tutorial focuses on different aspects of the data reduction and analysis process, from basic setup to advanced spectral analysis and visualization techniques.
To get started with the tutorials, you will need to have pykoala installed on your system. Detailed installation instructions can be found in the documentation page, or in the Github repository.
To clone this repository and get access to all the tutorials, use the following command:
git clone https://github.com/pykoala/pykoala-tutorials.git
cd pykoala-tutorials- Python 3.8 or higher
pykoalalibrary- Additional dependencies as listed in each tutorial
We provide a comprehensive guide to pykoala's utilities, helping users prepare for reducing their own data. The guide is divided into three main sections:
-
This section covers the basic concepts of the library, including the main classes and architecture, I/O features, verbosity, and logging facilities.
-
Learn how to process calibration exposures, which are essential for reducing science data.
-
Detailed instructions on how to reduce science frames, turning RSS data into scientifically useful results.
We highly recommend following the tutorials in the specified order. Each tutorial builds on the previous ones, using products or features derived from earlier steps without re-explanation.
Some algorithms or techniques are complicated, and might turn more difficult to use. These tutorials aim to go one step further and delve deep into the use of advanced DR functions.
We welcome contributions to enhance the tutorials and the pykoala library. If you would like to contribute, please follow these steps:
- Fork the repository
- Create a new branch (
git checkout -b feature/YourFeature) - Commit your changes (
git commit -m 'Add some feature') - Push to the branch (
git push origin feature/YourFeature) - Open a pull request
Please make sure to update tests as appropriate.
This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.
If you have any questions, suggestions, or feedback, feel free to open an issue or contact the maintainers directly.
Happy coding and exploring the universe with pykoala!