A package to aid in the forced extraction of pre-processed grism data. The full documentation can be found at https://pygrife.readthedocs.io, with a brief summary below.

In all cases, it is strongly recommended to install PyGriFE into a new virtual environment, to minimise dependency conflicts (see Requirements).

To clone the latest GitHub repository, use this command:

git clone https://github.com/PJ-Watson/PyGriFE.git

To build and install PyGriFE, run (from the root of the source tree):

pip install .

Alternatively, if grizli and sep are not already installed in the environment, they can be installed by running:

pip install .[grizli,sep]

PyGriFE is designed to work with pre-processed grism data, specifically the output from grizli. If you do not have the following files, PyGriFe will not run:

• "*GrismFLT.fits" and "*GrismFLT.pkl" files, containing the grism exposures, contamination models, blotted segmentation maps, and direct images.
• The (un-blotted) segmentation map, used to derive the contamination models ( e.g. "nis-wfss-ir_seg.fits" ).
• The direct images used to create the reference catalogue ( e.g. "nis-wfss-ir_drz_sci.fits", "nis-wfss-{f}_drz_sci.fits" for filters f).

First, begin by importing the main class.

from pygrife import GrismExtractor

To instantiate the GrismExtractor object, we need to supply the root_name of the processed files, their current location (see Necessary Files), and the output directory. PyGriFE copies the relevant files to the output directory, to preserve the originals and prevent any unexpected modifications.

ge = GrismExtractor(
    field_root="nis-wfss",
    in_dir="probably/called/Prep",
    out_dir="use/a/new/name/for/this",
)

Next, we need to load the original segmentation map.

ge.load_orig_seg_map(
    "/path/to/nis-wfss-ir_seg.fits",
)

We can now begin modifying the segmentation map to our liking. ge.seg_map is a 2D numpy array, and can be modified using any relevant operation. Several convenience methods are also built into GrismExtractor, such as the ability to read in a regions file written by DS9.

new_id = ge.add_reg_obj(
    reg_path="/some/path/to/targets_ds9_A2744_03.reg",
)

Alternatively, we could extract an object within a particular radius of a point (with many different ways to express this; see the documentation for further details).

import numpy as np
import astropy.units as u

new_ids = np.append(
    new_id,
    ge.add_circ_obj(
        ra=3.61066,
        dec=-30.39560,
        unit="deg",
        radius=3*u.arcsec,
    ),
)

Now we've modified the segmentation map, we need to regenerate the object catalogue, and load the processed grism data.

ge.regen_multiband_catalogue()
ge.load_grism_files(cpu_count=6)

Any objects can then be extracted, by supplying an array of IDs, and specifying the redshift range to search through.

ge.extract_spectra(
    new_ids,
    z_range=[0.25,0.35],
)

If the sources are in a heavily contaminated part of the field, the contamination model can be refined using the best-fit spectra, and the process repeated.

ge.refine_contam_model_with_fits(
    fit_files=[ge.out_dir / f"{ge.field_root}_{o_id:0>5}.full.fits" for o_id in new_ids],
)
ge.extract_spectra(
    new_ids,
    z_range=[0.25,0.35],
)

PyGriFE also includes a graphical interface, to view and modify the segmentation map. This feature is under active development, but can be run after installing the optional dependencies (see below for more details):

pip install .[GUI]

The GUI itself can be used by running the following:

from pygrife.GUI import run_GUI

run_GUI()

Note that even when feature complete, at least one thread will be dedicated to running the GUI, and so the method detailed above in Example will be slightly more performant.

PyGriFE currently has the following requirements:

• Python 3.10 or later
• Astropy 5.3 or later
• NumPy 1.24 or later
• Matplotlib 3.6 or later
• tqdm 4.66 or later
• regions 0.8 or later

To extract objects, a working installation of grizli is required. PyGriFE modifies some of the grizli class methods in order to extract arbitrary regions, and cannot be guaranteed to work with every version (if PyGriFE encounters any compatibility problems, please raise an issue here, rather than bothering the grizli developers). The current tested version is grizli==1.11.

Both PyGriFE and grizli rely on SEP, the Python implementation of Source Extractor (Bertin & Arnouts 1996). Unfortunately, since the original repository no longer appears to be maintained, it is necessary to install the fork maintained at PJ-Watson/sep. This includes the functionality necessary to rebuild a catalogue from an existing segmentation map.

To run the GUI, the following packages are also required:

• PyQt6 6.6 or later
• qimage2ndarray 1.10 or later

PyGriFE has been tested with Python 3.10, and is developed primarily on Python 3.11.