Claude Skill

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

LLM Mart · 0 points · 0 views 1 listing impressions 0 install-command copies
Download dirkkuiper-flits-plugins_flits_skills_frb-analysis-b2f2ad2.zip · 5 KB

Install

skills CLI npx skills add https://github.com/DirkKuiper/flits/tree/main/plugins/flits/skills/frb-analysis
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install dirkkuiper-flits@llmmart
Git 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. 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

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.

No comments yet.

Reviews (0)

No reviews yet.