README.md

# Pipeline for source injection on CSST images

## Installation

Create or update the `csst-injection` Conda environment, install SExtractor,
PSFEx, and this package with:

```
    ./install.sh
 ```

The native tools are installed from conda-forge as
`astromatic-source-extractor` and `astromatic-psfex`. To update the environment
without reinstalling the editable project manually, rerun the same command.
The installer also migrates environments created by older versions from
`cfitsio=3.*` to the compatible `cfitsio=4.6.4` release.

## Usage
### Run L1 Detrending pipeline (optional)
* If the L1 images are not available, we need first to run the CSST detrending pipeline on the raw images to get the L1 calibrated products. Otherwise this step can be ignored.
* This step removes all the instrumental related effects as well as cosmoic rays
* modify the corresponding ```config_detrending.yaml``` file to configure all running options
```
    run_csst_detrending /path/to/config_detrending.yaml
```
* Products:
    * L1 calibrated images (detrended + cosmic rays removed)
    * Weight maps
    * Flag maps

### Run Source Injection
* Inject souces onto the L1 calibrated images
* Modify the corresponding ```config_injection.yaml``` file to configure all running options
* An object catalog class which inherits from ```observation_sim.mock_objects.CatalogBase``` needs to be implemented and imported in ```injection.injection_pipeline.py```. This is to construct a list of to be injected ```observation_sim.mock_objects.MockObject```.
```
    run_csst_injection /path/to/config_injection.yaml
```
* Products:
    * L1 calibrated images with synthetic sources injected
    * Truth catalogs for injected sources

### Run L1 Detection & Photometry pipeline
* CSST detection and photometry pipeline, can be used to:
    * Detect and do photometry measurements on the L1 calibrated images
    * Re-detect and redo photometry measurements on the injected images
* modify the corresponding ```config_photometry.yaml``` file to configure all running options
    * Injected multi-extension L1 products are consumed directly from their
      `IMAGE`, `IVAR`, and `FLAG` extensions.
    * Use `input_image_list` for flat injection outputs, or the pointing and
      chip settings for products stored below pointing directories.
```
    run_csst_photometry /path/to/config_photometry.yaml
```
* Products:
    * Detection catalogs with photometric information
    * Flux maps
    * PSF models (in psfex format)
    * Segmentation maps
    * Sky maps

### Evaluation
* ```evaluation```package provided tools and example notebooks for evaluating:
    * Injected objects
    * Detection completeness
    * Photometric accuracy
* ```evaluation/measurement_catalog_evaluation.ipynb``` demonstrates one-to-one
  cross-matching and completeness/photometry evaluation for newly generated
  ```measurement_pipeline``` catalogs.