Cookbook
---------

HostSub_GP adopts preprocessed 2D spectra from upstream pipelines, such as PypeIt. It then rectifies the 2D spectra onto a regular grid in wavelength and spatial direction and coadds multiple exposures. With GPs it models the 2D galaxy spectrum and provides estimates of the local background at the transient position in the original 2D spectra.

Run with PypeIt
~~~~~~~~~~~~~~~~

.. note::

   HostSub_GP has been tested on PypeIt v1.17, but should work with v1.14 and later.

1. Install HostSub_GP by following the instructions in :doc:`installation`.
2. Make sure that your spectrograph is supported by HostSub_GP (see :doc:`reference/spectrographs`) and PypeIt (see `Spectrographs <https://pypeit.readthedocs.io/en/stable/spectrographs/spectrographs.html>`_).
3. Reduce your longslit data with PypeIt, following the instructions in the `PypeIt documentation <https://pypeit.readthedocs.io/en/stable/>`_. A couple of special setups are recommended:

   * Lower the significance threshold for arcs to be used in tracing wavelength tilts (to bump up the number of lines used to model the tilts and improve the 2D wavelength solution).
   * Turn off the internal local sky modeling of PypeIt (bright pixels from the host galaxy can be identified as cosmic rays and mistakenly masked).

   You can include these settings in your PypeIt configuration file,

    .. code-block:: ini
        
        [calibrations]
            [[tilts]]
                tracethresh = 5.0
        [reduce]
            [[skysub]]
                no_local_sky = True

    .. note::
   
       With ``no_local_sky`` turned on, PypeIt may have trouble finding and tracing the transient, especially if the trace is significantly curved. Please carefully inspect the ``spec2d`` objects.

4. In the PypeIt output directory, run

   .. code-block:: shell
        
        hostsub_setup pypeit -c YOUR_PYPEIT_FILE.pypeit --target TARGET
        
   This will read your ``.pypeit`` file and generate a folder named ``HostSub_OBJ`` containing a template input file ``hostsub.txt``. See :doc:`reference/input_file` for details of the input file format and parameters.

5. Edit the input file ``hostsub.txt`` for a couple of key parameters. As a minimum, you need to specify:

    * The coordinates of the target (``ra`` and ``dec``) -- in some spectrographs, the coordinates in the header may be incorrect (e.g., LRIS).
    * The spatial resolution, i.e., seeing (``spat_resln``), otherwise the FWHM of the standard star will be used.
    * The path to the raw data (``raw_dir``).
    * In ``[host_prior]``, the survey and filters of the archival images to be used (by default, ``survey = PS1``, ``filters = grizy``).
    * In ``[host_emission]``, a rough redshift of the host (``z``).

6. Run the main processing script

   .. code-block:: shell
        
        hostsub hostsub.txt

   This will
    * Download archival images of the host galaxy from the specified survey (e.g., Pan-STARRS1, Legacy Surveys, and SDSS) and save them in ``SURVEY_cutout/`` (``SURVEY = ps1``, ``ls``, or ``sdss``).
    * Conduct the modeling and throw a bunch of QA plots in ``QA/``.
    * Save the background-subtracted 2D spectra in the ``Science/`` folder generated by PypeIt, with the suffix ``_hostsub.fits``.

   This concludes the main HostSub_GP processing.

7. Coming back to PypeIt, coadd the ``*_hostsub.fits`` files and a 1D spectrum and will be automatically extracted from the coadded 2D spectrum. With that you can proceed with your usual analysis.

   .. note::

      ``pypeit_coadd_2dspec`` sometimes complains about the ``*_hostsub.fits`` files not having the right objects to be used in the frame alignment. In this case, add

        .. code-block:: ini
    
            [coadd2d]
                offsets = 0,0,0

      to your ``coadd2d`` configuration file, assuming you have three exposures to be coadded.

Other Pipelines
~~~~~~~~~~~~~~~~~~~~~

Support under development. Please raise an issue if you are interested in using HostSub_GP with other upstream pipelines.