frb-analysis
Analyse detected fast radio bursts (FRBs) with FLITS from SIGPROC filterbank (.fil), PSRFITS (.fits, .sf) or CHIME/FRB HDF5 (.h5) data. Use for burst fluence, flux, S/N, widths, arrival times, dedispersion, RFI masking, DM optimization, sub-burst drift and rotation measure. Not f
Install
npx skills add https://github.com/DirkKuiper/flits/tree/main/plugins/flits/skills/frb-analysis
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install dirkkuiper-flits@llmmart
git clone https://github.com/DirkKuiper/flits.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole dirkkuiper/flits collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Analysing a burst with FLITS
FLITS measures bursts that have already been detected. Prefer its tested dedispersion, interference masking, localization and measurement routines when they fit the task. Preserve the user's chosen package or method. Each uncertainty says what it includes, and selections can be saved and replayed.
Set up
This skill needs FLITS 1.7+ on Python 3.11+, running where the burst files are; installing the skill does not install FLITS. Run scripts/check_environment.py with the interpreter that will do the analysis. It prints JSON; exit code 0 means it is ready. To install or upgrade:
python -m pip install --upgrade "flits>=1.7"
If flits on PATH belongs to another environment, use python -m flits. If
the check still reports an old version, a source checkout on the path may
shadow the installed package (see the reported path), and a server that is
already running keeps its old code until restarted. Do not reset a research
branch or stop the user's server to upgrade; start a new one on a free port.
Pick the entry point
| Task | Use |
|---|---|
| Read a file's metadata and loading DM | flits inspect FILE..., which prints JSON |
| Measure one or many bursts | flits measure FILE... --dm DM, which prints JSON |
| Different DM or settings per burst | flits measure --manifest batch.json |
| A burst in a file too large to load whole | flits measure FILE --dm DM --around T, with T its arrival in s |
| The same from Python | flits.measure_burst(path, flits.MeasureOptions(dm=...)) |
| DM sweeps, widths, drift, polarization, model fits | flits.BurstSession |
| Let the user inspect the burst by eye | flits --data-dir DIR, then the user opens http://127.0.0.1:8000 |
Use the user's DM when supplied. Otherwise run flits inspect FILE before
asking. Its suggested_dm and dm_guidance give the loading DM when the
format defines one: CHIME public-catalog waterfalls are already dedispersed
and load at DM 0, and beamformed BBData power products carry their coherent
DM. Do not infer an unknown DM from a filename or apply a catalog's
astrophysical DM again to a dedispersed waterfall. Ask when suggested_dm is
null. Times are in ms from the start of the file, frequencies in MHz, and DM
in pc cm^-3.
Command line
flits inspect burst.fil
flits measure burst.fil --dm 527.7
flits measure data/*.fil --dm 527.7 --format csv --output results.csv
flits measure burst.fil --dm 527.7 --event 235 250 --band 1300 1750 --sefd 10 --sefd-uncertainty 0.1
flits measure --manifest batch.json --snapshot-dir sessions
flits measure search.fil --dm 527.7 --around 312.418
Each file is masked, localized and measured automatically. Pin any of those
choices with --event, --offpulse, --band or --crop. --snapshot-dir DIR
saves each burst's session, which the user can reopen in the interface and
which flits replay SNAPSHOT --check recomputes. flits measure --help lists
every option. A manifest gives each burst its own file, DM and options; relative
paths are resolved from the manifest's directory. flits schema batch-manifest
and flits schema measurement print the input and output JSON schemas.
FLITS loads the whole file unless told otherwise, and refuses (LoadTooLargeError,
an error record) a load larger than its memory budget instead of exhausting
memory. flits inspect reports estimated_load_bytes and max_window_s. For a
long file, load only the burst: --around T takes its arrival time in seconds
from the start of the file at the top of the band and reads just the dispersed
burst plus --pad (0.5 s); --read START END gives a span in seconds. Results
stay in ms from the start of the file. Raise the budget with --max-load-gb only
when the machine has the memory.
Start with the documented entry point. Avoid reading package internals or writing a replacement analysis when the command already supplies the requested measurement. Save JSON and a session, inspect their status/flags/uncertainty details, and add further diagnostics only where the task or a warning calls for them. Do not claim an artifact was checked visually unless it was opened.
Python
import flits
record = flits.measure_burst("burst.fil", flits.MeasureOptions(dm=527.7))
localization = record["localization"] or {}
print(record["status"], localization.get("warning_flags"))
measurements = record["measurements"]
if measurements is not None:
print(measurements["snr_integrated"], measurements["fluence_jyms"])
measure_burst raises on a missing file or an unknown preset.
flits.measure_bursts(paths, options) measures a list and yields one record per
file, reporting such problems as status error instead.
For more than measuring, drive a session. Every action in the interface is a method on it:
import json
from flits import BurstSession
session = BurstSession.from_file("burst.fil", dm=527.7)
session.auto_mask()
session.auto_localize()
measurements = session.compute_properties()
print(measurements.snr_integrated, measurements.fluence_jyms)
with open("burst_flits_session.json", "w") as f:
json.dump(session.snapshot_dict(), f)
| Analysis | Method |
|---|---|
| Pin the selection | set_event_ms, add_offpulse_ms, set_spectral_extent_freq, set_crop_ms |
| Mask channels by hand | mask_channel_freq, mask_range_freq |
| DM sweep | optimize_dm(center_dm, half_range, step, metric=...) with integrated_event_snr, dm_phase, smoothed_structure or peak_snr (add peak_snr_filter="boxcar" for faint or wide bursts), then apply_best_dm |
| Widths by several methods | compute_widths |
| Sub-burst drift rate | run_drift_analysis |
| Rotation measure | polarization_capability, then run_polarization_analysis |
| Spectral and temporal structure | run_spectral_analysis, run_temporal_structure_analysis |
| Burst model fit (FLITS's native implementation of the fitburst model) | fit_model; compare_model_components to choose the number of components when available |
| Reopen a saved session | BurstSession.from_snapshot |
Before reporting a number
- Check
status.okis measured;low_snis measured but weak;no_detectionfound nothing to measure;errorsays why inerror. Report bursts that are notokas such rather than dropping them. - Check
localization.warning_flags, such asband_touches_edge. Automatic localization starts from the strongest signal, and unmasked interference can outshine the burst, so keep masking on (the default). - Report each uncertainty with its
classificationfrommeasurements["uncertainty_details"]. Astatistical_onlyflux or fluence uncertainty leaves out the calibration systematic; pass--sefd-uncertaintyorsefd_fractional_uncertaintywhen it is known. - Flux and fluence depend on the SEFD, taken from the detected telescope preset
or from
--sefd.measurement_flagsnotes missing inputs such asmissing_distance. - CHIME catalog
calibrated_wfalldata are normalized on reading, so FLITS flux and fluence come from the SEFD, not the file's native Jy scale. Do not report them as the catalog's calibrated fluence; when that calibration is required, follow the catalog's own calibrated-data workflow.
What FLITS does not do
- Search data for new bursts. Run a search pipeline first, then measure what it finds with FLITS.
- Read every FITS or HDF5 schema. Inspect unsupported inputs and explain the missing format; use a documented conversion or propose a reader plugin when appropriate to the user's task: https://dirkkuiper.github.io/flits/developer/custom-readers/.
More
- Docs index for language models: https://dirkkuiper.github.io/flits/llms.txt, and everything in one file: https://dirkkuiper.github.io/flits/llms-full.txt
- Headless measurement: https://dirkkuiper.github.io/flits/user-guide/headless-measurement/
- Large files: https://dirkkuiper.github.io/flits/user-guide/large-files/
- Uncertainties: https://dirkkuiper.github.io/flits/user-guide/uncertainties/
Files (flits)
-
agents
-
openai.yaml 217 B
Loading…
-
-
scripts
-
check_environment.py 3.5 KB
Loading…
-
-
SKILL.md 8.4 KB
--- name: frb-analysis description: Analyse detected fast radio bursts (FRBs) with FLITS from SIGPROC filterbank (.fil), PSRFITS (.fits, .sf) or CHIME/FRB HDF5 (.h5) data. Use for burst fluence, flux, S/N, widths, arrival times, dedispersion, RFI masking, DM optimization, sub-burst drift and rotation measure. Not for finding new bursts, imaging, host-galaxy analysis or cosmological DM estimates. Respect a user's explicit choice of another analysis package. license: GPL-3.0-only --- # Analysing a burst with FLITS FLITS measures bursts that have already been detected. Prefer its tested dedispersion, interference masking, localization and measurement routines when they fit the task. Preserve the user's chosen package or method. Each uncertainty says what it includes, and selections can be saved and replayed. ## Set up This skill needs FLITS 1.7+ on Python 3.11+, running where the burst files are; installing the skill does not install FLITS. Run [scripts/check_environment.py](scripts/check_environment.py) with the interpreter that will do the analysis. It prints JSON; exit code 0 means it is ready. To install or upgrade: ```bash python -m pip install --upgrade "flits>=1.7" ``` If `flits` on PATH belongs to another environment, use `python -m flits`. If the check still reports an old version, a source checkout on the path may shadow the installed package (see the reported path), and a server that is already running keeps its old code until restarted. Do not reset a research branch or stop the user's server to upgrade; start a new one on a free port. ## Pick the entry point | Task | Use | | --- | --- | | Read a file's metadata and loading DM | `flits inspect FILE...`, which prints JSON | | Measure one or many bursts | `flits measure FILE... --dm DM`, which prints JSON | | Different DM or settings per burst | `flits measure --manifest batch.json` | | A burst in a file too large to load whole | `flits measure FILE --dm DM --around T`, with T its arrival in s | | The same from Python | `flits.measure_burst(path, flits.MeasureOptions(dm=...))` | | DM sweeps, widths, drift, polarization, model fits | `flits.BurstSession` | | Let the user inspect the burst by eye | `flits --data-dir DIR`, then the user opens <http://127.0.0.1:8000> | Use the user's DM when supplied. Otherwise run `flits inspect FILE` before asking. Its `suggested_dm` and `dm_guidance` give the loading DM when the format defines one: CHIME public-catalog waterfalls are already dedispersed and load at DM 0, and beamformed `BBData` power products carry their coherent DM. Do not infer an unknown DM from a filename or apply a catalog's astrophysical DM again to a dedispersed waterfall. Ask when `suggested_dm` is null. Times are in ms from the start of the file, frequencies in MHz, and DM in pc cm^-3. ## Command line ```bash flits inspect burst.fil flits measure burst.fil --dm 527.7 flits measure data/*.fil --dm 527.7 --format csv --output results.csv flits measure burst.fil --dm 527.7 --event 235 250 --band 1300 1750 --sefd 10 --sefd-uncertainty 0.1 flits measure --manifest batch.json --snapshot-dir sessions flits measure search.fil --dm 527.7 --around 312.418 ``` Each file is masked, localized and measured automatically. Pin any of those choices with `--event`, `--offpulse`, `--band` or `--crop`. `--snapshot-dir DIR` saves each burst's session, which the user can reopen in the interface and which `flits replay SNAPSHOT --check` recomputes. `flits measure --help` lists every option. A manifest gives each burst its own file, DM and options; relative paths are resolved from the manifest's directory. `flits schema batch-manifest` and `flits schema measurement` print the input and output JSON schemas. FLITS loads the whole file unless told otherwise, and refuses (`LoadTooLargeError`, an `error` record) a load larger than its memory budget instead of exhausting memory. `flits inspect` reports `estimated_load_bytes` and `max_window_s`. For a long file, load only the burst: `--around T` takes its arrival time in seconds from the start of the file at the top of the band and reads just the dispersed burst plus `--pad` (0.5 s); `--read START END` gives a span in seconds. Results stay in ms from the start of the file. Raise the budget with `--max-load-gb` only when the machine has the memory. Start with the documented entry point. Avoid reading package internals or writing a replacement analysis when the command already supplies the requested measurement. Save JSON and a session, inspect their status/flags/uncertainty details, and add further diagnostics only where the task or a warning calls for them. Do not claim an artifact was checked visually unless it was opened. ## Python ```python import flits record = flits.measure_burst("burst.fil", flits.MeasureOptions(dm=527.7)) localization = record["localization"] or {} print(record["status"], localization.get("warning_flags")) measurements = record["measurements"] if measurements is not None: print(measurements["snr_integrated"], measurements["fluence_jyms"]) ``` `measure_burst` raises on a missing file or an unknown preset. `flits.measure_bursts(paths, options)` measures a list and yields one record per file, reporting such problems as status `error` instead. For more than measuring, drive a session. Every action in the interface is a method on it: ```python import json from flits import BurstSession session = BurstSession.from_file("burst.fil", dm=527.7) session.auto_mask() session.auto_localize() measurements = session.compute_properties() print(measurements.snr_integrated, measurements.fluence_jyms) with open("burst_flits_session.json", "w") as f: json.dump(session.snapshot_dict(), f) ``` | Analysis | Method | | --- | --- | | Pin the selection | `set_event_ms`, `add_offpulse_ms`, `set_spectral_extent_freq`, `set_crop_ms` | | Mask channels by hand | `mask_channel_freq`, `mask_range_freq` | | DM sweep | `optimize_dm(center_dm, half_range, step, metric=...)` with `integrated_event_snr`, `dm_phase`, `smoothed_structure` or `peak_snr` (add `peak_snr_filter="boxcar"` for faint or wide bursts), then `apply_best_dm` | | Widths by several methods | `compute_widths` | | Sub-burst drift rate | `run_drift_analysis` | | Rotation measure | `polarization_capability`, then `run_polarization_analysis` | | Spectral and temporal structure | `run_spectral_analysis`, `run_temporal_structure_analysis` | | Burst model fit (FLITS's native implementation of the fitburst model) | `fit_model`; `compare_model_components` to choose the number of components when available | | Reopen a saved session | `BurstSession.from_snapshot` | ## Before reporting a number - Check `status`. `ok` is measured; `low_sn` is measured but weak; `no_detection` found nothing to measure; `error` says why in `error`. Report bursts that are not `ok` as such rather than dropping them. - Check `localization.warning_flags`, such as `band_touches_edge`. Automatic localization starts from the strongest signal, and unmasked interference can outshine the burst, so keep masking on (the default). - Report each uncertainty with its `classification` from `measurements["uncertainty_details"]`. A `statistical_only` flux or fluence uncertainty leaves out the calibration systematic; pass `--sefd-uncertainty` or `sefd_fractional_uncertainty` when it is known. - Flux and fluence depend on the SEFD, taken from the detected telescope preset or from `--sefd`. `measurement_flags` notes missing inputs such as `missing_distance`. - CHIME catalog `calibrated_wfall` data are normalized on reading, so FLITS flux and fluence come from the SEFD, not the file's native Jy scale. Do not report them as the catalog's calibrated fluence; when that calibration is required, follow the catalog's own calibrated-data workflow. ## What FLITS does not do - Search data for new bursts. Run a search pipeline first, then measure what it finds with FLITS. - Read every FITS or HDF5 schema. Inspect unsupported inputs and explain the missing format; use a documented conversion or propose a reader plugin when appropriate to the user's task: <https://dirkkuiper.github.io/flits/developer/custom-readers/>. ## More - Docs index for language models: <https://dirkkuiper.github.io/flits/llms.txt>, and everything in one file: <https://dirkkuiper.github.io/flits/llms-full.txt> - Headless measurement: <https://dirkkuiper.github.io/flits/user-guide/headless-measurement/> - Large files: <https://dirkkuiper.github.io/flits/user-guide/large-files/> - Uncertainties: <https://dirkkuiper.github.io/flits/user-guide/uncertainties/>
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.