Metadata-Version: 2.5
Name: cosmit
Version: 0.1.0
Summary: Cosmic-ray tools for AstroSat/UVIT
Project-URL: Homepage, https://github.com/prajwel/cosmit
Project-URL: Issues, https://github.com/prajwel/cosmit/issues
Author-email: Prajwel Joseph <prajwel.pj@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Requires-Dist: astropy
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: scipy
Description-Content-Type: text/markdown

## ⚠️ Work in progress

> [!WARNING]
> **Cosmit is a work in progress.** Many changes are expected as development continues.


# Cosmit

**Cosmic-ray tools for AstroSat/UVIT**

Cosmit identifies UVIT event-list frames with unusually high event counts, flags them as candidate cosmic-ray-affected frames, and removes the events associated with those frames. It then updates the exposure maps and regenerates count-rate images, error images, and diagnostic products.


## Features

- **Robust frame rejection:** flags frames using the median and normal-scaled median absolute deviation (NMAD) of the valid-event counts.
- **Cleaned event lists:** removes all event-list rows associated with flagged frame times.
- **Updated exposure maps:** scales exposure maps by the fraction of inspected frames retained.
- **Regenerated images:** creates detector-coordinate and astronomical-coordinate count-rate images and their corresponding error images.
- **Diagnostics:** records frame counts and flags in a CSV catalogue, saves diagnostic plots, and writes a processing log.


## Requirements

- Python 3.9 or later
- AstroSat/UVIT Level 2 products from UVIT Pipeline Version 7 or later, or PSF improved products generated by Resolvit


## Installation

Install Cosmit with `pip`:

```bash
pip install cosmit
```


## Usage

Run Cosmit on an observation directory. For example:

```bash
cosmit 20160101_A01_123T01_0123456789_level2
```

By default, Cosmit searches recursively for event lists under directories named `data_products`.

### Process Resolvit products

To process products under `resolvit_data_products`, specify the input source:

```bash
cosmit 20160101_A01_123T01_0123456789_level2 --input-source resolvit
```

### Change the rejection threshold

Cosmit uses a default threshold factor of `10.0`. Set a different value with `--threshold-factor`:

```bash
cosmit 20160101_A01_123T01_0123456789_level2 --threshold-factor 8
```

A smaller factor generally makes rejection more aggressive; a larger factor generally makes it more conservative. The threshold is calculated independently for each event list.

### Other command-line options

Display the installed version:

```bash
cosmit --version
```

Display the full command-line help:

```bash
cosmit --help
```


## Python API

Cosmit can also be called from Python:

```python
from cosmit import process_observation

results = process_observation(
    "20160101_A01_123T01_0123456789_level2",
    input_source="v7",
    threshold_factor=10.0,
)
```

`process_observation()` returns a list of `(paths, summary)` pairs, one for each processed event list. Use `input_source="resolvit"` to process Resolvit products.


## Input data

Cosmit recursively searches the supplied observation directory for files matching `AS1*l2ce.fits` under the selected input-source directory.

| `--input-source` | Input directory |
| --- | --- |
| `v7` (default) | `data_products` |
| `resolvit` | `resolvit_data_products` |


## Output products

Cosmit writes results to a sibling directory named `cosmit_data_products`.

For each event list, the products include:

| Product | Filename pattern | Description |
| --- | --- | --- |
| Cleaned event list | `*_l2ce.fits` | Event list with rows from flagged frame times removed |
| Detector-coordinate count-rate image | `*I_l2img.fits` | Regenerated detector-coordinate image |
| Detector-coordinate count-rate error image | `*I_l2err.fits` | Corresponding error image |
| Astronomical-coordinate count-rate image | `*A_l2img.fits` | Regenerated astronomical-coordinate image |
| Astronomical-coordinate count-rate error image | `*A_l2err.fits` | Corresponding error image |
| Detector exposure map | `*I_l2exp.fits` | Exposure map scaled by the retained-frame fraction |
| Astronomical exposure map | `*A_l2exp.fits` | Exposure map scaled by the retained-frame fraction |

Cosmit also creates a diagnostics directory for each product:

`cosmit_data_products/<relative_parent>/diagnostics/<product_id>/`

It contains:

- `cosmit.log` — input and output paths, run information, threshold statistics, and summary metrics.
- `cosmic_ray_catalogue.csv` — `MJD_L2`, valid-event count, and the `CR_flag` flag for each inspected frame.
- `unique_frametime_counts.png` — distribution of events per frame, with the rejection threshold.
- `unique_frametime_counts_vs_time.png` — frame event counts versus time, with flagged frames highlighted.
