Add model card (README)

README.md

@@ -1,3 +1,290 @@
----
-license: apache-2.0
----
+---
+language:
+- en
+license: gpl-2.0
+tags:
+- astronomy
+- fast-radio-bursts
+- frb
+- pulsar
+- instance-segmentation
+- mask-rcnn
+- hrnet
+- radio-astronomy
+- signal-processing
+library_name: pytorch
+pipeline_tag: image-segmentation
+datasets:
+- CRAFTS-FRT
+metrics:
+- recall
+- precision
+---
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/BinZhang109/FRTSearch/main/logo2.svg" width="100%" alt="FRTSearch Banner">
+</div>
+
+# FRTSearch: Fast Radio Transient Detection Model
+
+🚀 **Unified Detection and Parameter Inference of Fast Radio Transients using Instance Segmentation** 🚀
+
+[![Paper](https://img.shields.io/badge/Paper-AASTeX-blue.svg)](https://doi.org/10.57760/sciencedb.Fastro.00038) 
+[![Dataset](https://img.shields.io/badge/Dataset-CRAFTS--FRT-yellow.svg)](https://doi.org/10.57760/sciencedb.Fastro.00038) 
+[![GitHub](https://img.shields.io/badge/GitHub-FRTSearch-black.svg)](https://github.com/BinZhang109/FRTSearch)
+[![Python](https://img.shields.io/badge/Python-3.10+-green.svg)](https://www.python.org/) 
+[![License](https://img.shields.io/badge/License-GPL--2.0-grey.svg)](https://github.com/BinZhang109/FRTSearch/blob/main/LICENSE)
+
+---
+
+## Model Description
+
+**FRTSearch** is an end-to-end deep learning framework for detecting and characterizing Fast Radio Transients (FRTs), including:
+- **Fast Radio Bursts (FRBs)**
+- **Pulsars**
+- **Rotating Radio Transients (RRATs)**
+
+### Architecture
+
+- **Backbone**: HRNet-W32 (High-Resolution Network)
+- **Detection Head**: Mask R-CNN
+- **Training Epoch**: 36
+- **Input Dimensions**: 256 (frequency channels) × 8192 (time samples)
+- **Model Size**: 381.75 MB
+
+### Key Innovation
+
+FRTSearch reframes FRT detection as a **pattern recognition problem** by exploiting the morphological universality of dispersive trajectories in time-frequency dynamic spectra ($t \propto \nu^{-2}$).
+
+The model combines:
+1. **Mask R-CNN Detection**: Deep learning model trained on pixel-level annotated data for precise trajectory segmentation
+2. **IMPIC Algorithm**: Physics-driven Iterative Mask-based Parameter Inference and Calibration for direct DM (Dispersion Measure) and ToA (Time of Arrival) inference
+
+---
+
+## Training Data
+
+**CRAFTS-FRT Dataset**: The first pixel-level annotated dataset for Fast Radio Transients
+
+| Property | Value |
+|----------|-------|
+| **Total Instances** | 2,392 |
+| **Pulsars** | 2,115 |
+| **RRATs** | 15 |
+| **FRBs** | 262 |
+| **Source Telescope** | FAST 19-beam L-band receiver |
+| **Frequency Range** | 1000-1500 MHz |
+| **Dataset DOI** | [10.57760/sciencedb.Fastro.00038](https://doi.org/10.57760/sciencedb.Fastro.00038) |
+
+The wide training range enables FRTSearch to handle both **drift scan short-term observations** and **tracking long-term observation data** processing.
+
+---
+
+## Model Performance
+
+Benchmarked on **FAST-FREX** dataset (600 FRB bursts):
+
+| Metric | Value |
+|--------|-------|
+| **Recall** | 98.0% |
+| **False Positives Per Image (FPPI)** | 4.1 |
+| **Speedup vs PRESTO** | 25.5× |
+| **Cross-facility Generalization** | 100% (19/19 ASKAP FRBs detected) |
+
+### Key Advantages
+
+- ✅ **High Sensitivity**: 98.0% recall on benchmark dataset
+- ✅ **Low False Positives**: Reduces false positives by >99.9% vs traditional methods
+- ✅ **Cross-Telescope Robustness**: Successfully generalizes to FAST, Parkes, and SKA without retraining
+- ✅ **Efficiency**: Up to 25.5× faster than traditional pipelines
+- ✅ **Unified Framework**: Eliminates redundant DM-width grid searches
+
+---
+
+## Supported Data Formats
+
+- **PSRFITS** (`.fits`) - Standard format for pulsar data
+- **Sigproc Filterbank** (`.fil`) - Legacy filterbank format
+
+### Supported Bit Depths
+
+- 1-bit quantization
+- 2-bit quantization
+- 4-bit quantization
+- 8-bit quantization
+
+---
+
+## Test Samples
+
+This repository includes 7 test samples from 3 different telescopes to demonstrate cross-facility performance:
+
+### FAST Telescope (3 samples)
+- FRB 20121102 (repeating FRB, DM=565.0 pc cm⁻³)
+- FRB 20180301 (DM=420.0 pc cm⁻³)
+- FRB 20201124 (repeating FRB, DM=525.0 pc cm⁻³)
+
+### Parkes Telescope (1 sample)
+- FRB 110220 (low-frequency, DM=944.0 pc cm⁻³)
+
+### SKA/ASKAP (3 samples)
+- FRB 20180119 (DM=400.0 pc cm⁻³)
+- FRB 20180212 (DM=167.7 pc cm⁻³)
+- FRB 20220610A (host galaxy localized, DM=1457.6 pc cm⁻³)
+
+See [DATA_DESCRIPTION.md](DATA_DESCRIPTION.md) for detailed information about each test sample.
+
+---
+
+## Installation & Usage
+
+### Quick Start
+
+```bash
+# Clone the repository
+git clone https://github.com/BinZhang109/FRTSearch.git
+cd FRTSearch
+
+# Install MMDetection (required)
+pip install -U openmim
+mim install mmcv-full
+pip install mmdet
+
+# Install dependencies
+pip install -r requirements.txt
+```
+
+### Download Model Weights
+
+```python
+from huggingface_hub import hf_hub_download
+
+# Download model weights
+model_path = hf_hub_download(
+    repo_id="waterfall109/FRTSearch",
+    filename="models/hrnet_epoch_36.pth"
+)
+```
+
+Or download directly from [Files and versions](https://huggingface.co/waterfall109/FRTSearch/tree/main).
+
+### Run Detection
+
+```bash
+python FRTSearch.py data.fits config.py --slide-size 128
+```
+
+**Arguments:**
+- `data.fits`: Observation data file (.fits or .fil format)
+- `config.py`: Model configuration file (see `configs/` directory)
+- `--slide-size`: Number of sub-integrations per batch (default: 128)
+
+### Example Configuration
+
+```python
+# configs/detector_FAST.py
+data_cfg = dict(
+    freq_range=[1000.0, 1500.0],  # MHz
+    downsample_time=1,
+    downsample_freq=16
+)
+
+model_cfg = dict(
+    detector_cfg='path/to/detector_config.py',
+    score_thr=0.3,
+    detector_model='models/hrnet_epoch_36.pth'
+)
+
+aug_cfg = dict(
+    type='dm_filtering',
+    threshold=3.0  # Filter candidates with DM < 3.0
+)
+```
+
+---
+
+## Hyperparameter Tuning
+
+### Model Input Constraint
+
+The model is trained on input dimensions of **256 (freq) × 8192 (time)**. This wide training range enables FRTSearch to handle both drift scan short-term observations and tracking long-term observation data processing.
+
+### Tuning Guidelines
+
+**Key Parameters:**
+- `freq_range`: **CRITICAL** - Must match your observation frequency range
+- `downsample_time`: Time downsampling factor
+- `downsample_freq`: Frequency downsampling factor
+- `--slide-size`: Batch size for processing long observations
+
+**Critical Rules:**
+1. Time dimension after downsampling must be ≤ 8192
+2. Frequency dimension should target ≈ 256 bins (can be higher, avoid very low values)
+3. Always update `freq_range` to match your data
+
+See [test_sample/README.md](test_sample/README.md) for telescope-specific tuning strategies.
+
+---
+
+## Telescope Coverage
+
+Successfully tested on:
+
+| Telescope | Frequency Range | Time Resolution | Channels | Samples |
+|-----------|----------------|-----------------|----------|---------|
+| **FAST** | 1000-1500 MHz | 49-98 μs | 4096 | 3 FRBs |
+| **Parkes** | 190-240 MHz | 122 μs | 512 | 1 FRB |
+| **SKA/ASKAP** | 1260-1870 MHz | 1266 μs | 336 | 3 FRBs |
+
+**Total Coverage:**
+- Time resolution range: 26× (49 μs to 1266 μs)
+- Frequency coverage: 190 MHz to 1870 MHz
+- DM range: 167.7 to 1457.6 pc cm⁻³
+- Bit depths: 1-bit, 2-bit, 8-bit
+
+---
+
+## Citation
+
+If you use FRTSearch or the CRAFTS-FRT dataset in your research, please cite:
+
+```bibtex
+@article{zhang2025frtsearch,
+  title={FRTSearch: Unified Detection and Parameter Inference of Fast Radio Transients using Instance Segmentation},
+  author={Zhang, Bin and Wang, Yabiao and Xie, Xiaoyao and others},
+  journal={Draft version (AASTeX631)},
+  year={2025}
+}
+```
+
+### Test Sample References
+
+When using the test samples, please also cite the original observations:
+
+- **FAST samples**: [Guo et al. (2025)](https://doi.org/10.3847/1538-4365/adf42d)
+- **Parkes sample**: [Keane et al. (2015)](https://doi.org/10.1093/mnras/stu2650)
+- **SKA samples**: [Shannon et al. (2018)](https://doi.org/10.1038/s41586-018-0588-y), [Ryder et al. (2022)](https://doi.org/10.1126/science.adf2678)
+
+---
+
+## License
+
+This project is based on [PRESTO](https://github.com/scottransom/presto) and modified components are licensed under GNU General Public License v2.0.
+
+See [LICENSE](https://github.com/BinZhang109/FRTSearch/blob/main/LICENSE) for details.
+
+---
+
+## Acknowledgments
+
+- **Dataset**: CRAFTS-FRT from FAST telescope observations
+- **Framework**: Built on [MMDetection](https://github.com/open-mmlab/mmdetection)
+- **Base Code**: Modified from [PRESTO](https://github.com/scottransom/presto)
+
+---
+
+<div align="center">
+  <sub>Exploring the dynamic universe with AI 🌌📡</sub>
+  <br>
+  <sub>For questions and issues: <a href="https://github.com/BinZhang109/FRTSearch/issues">GitHub Issues</a></sub>
+</div>