YAML Configuration Reference¶

AstroFlow is configured with one YAML file passed to the astroflow command:

astroflow search.yaml

Most searches need four groups of settings: input/output, compute resources, search grid, and plotting.

Minimal Single-File Example¶

input: FRB180417.fil
output: frb180417
mode: single

dedgpu: 0
detgpu: 0
cputhread: 8
plotworker: 1

modelname: yolov11n
confidence: 0.4
timedownfactor: 1
gencand: true
savedmt: false

rfi:
  use_mask: false
  use_zero_dm: false
  use_iqrm: true

iqrm:
  mode: 1
  radius_frac: 0.1
  nsigma: 10.0
  geofactor: 1.5
  win_sec: 0
  hop_sec: 0.5
  include_tail: true

tsample:
  - name: t0
    t: 0.5

dm_limt:
  - name: dm_all
    dm_low: 0
    dm_high: 800

dmrange:
  - name: dm_10_600
    dm_low: 10
    dm_high: 600
    dm_step: 1

freqrange:
  - name: fullband
    freq_start: 1130
    freq_end: 1465

dmtconfig:
  minpercentile: 0
  maxpercentile: 99.99

specconfig:
  minpercentile: 0.1
  maxpercentile: 99.9
  tband: 120
  mode: subband
  subfreq: 128
  subtsamp: 2
  dtrend: false
  norm: true
  savetype: png

Top-Level Options¶

Option	Type	Required	Default	Description
`input`	string	Yes	none	Input `.fil`/`.fits` file, input directory, or dataset directory depending on `mode`.
`output`	string	Yes	none	Output directory for logs, cached products, candidate images, and candidate CSV files. Created automatically.
`mode`	string	Yes	none	Processing mode. One of `single`, `directory`, `muti`, `monitor`, `dataset`. `muti` is retained as a compatibility alias for directory processing.
`candpath`	string	Dataset mode only	none	Candidate CSV path for ground-truth matching in `dataset` mode.
`psrfitsbackend`	string	No	`cpp`	PSRFITS reader backend. One of `cpp`, `python`.
`gencand`	boolean	No	`false`	Write `astroflow_cands.csv` candidate summaries beside candidate outputs.
`onlycand`	boolean	No	`false`	Save candidate metrics without generating full candidate plots. Useful when metrics are needed but image products are not.
`fastcand`	boolean	No	`false`	Use the lightweight candidate-output path and reduce plotting overhead. Recommended for high-throughput benchmarks.
`savedmt`	boolean	No	`false`	Save detected candidate DMT images and label files for model finetune.
`include_last`	boolean	No	`false`	Include the final partial processing chunk when enabled.
`minfileage`	number	No	`0`	In monitor mode, only process files older than this many seconds. Helps avoid reading files that are still being written.

Processing And GPU Options¶

Option	Type	Default	Description
`dedgpu`	integer	`0`	GPU device index for dedispersion.
`detgpu`	integer	`0`	GPU device index for AI detection.
`cputhread`	integer	`16`	CPU worker/thread count. Also sets `OMP_NUM_THREADS`.
`plotworker`	integer	`2`	Number of plotting worker processes.
`batchsize`	integer	`128`	Detection batch size.
`timedownfactor`	integer or null	none	Time-axis downsampling factor passed into search configuration. Set explicitly for normal runs.

Detection Options¶

Option	Type	Required	Default	Description
`modelname`	string	Yes	none	Detector model name. Currently only `yolov11n` is supported for standard searches.
`modelpath`	string	No	auto-downloaded bundled model	Path to model weights. If omitted, AstroFlow downloads and verifies the default YOLO model under `~/.config/astroflow`.
`confidence`	number	Recommended	none	Detector confidence threshold. Typical value: `0.4`.
`snrhold`	number	No	`-100`	SNR threshold for candidate filtering.

Search Grid Options¶

`tsample`¶

List of time chunk definitions.

Field	Type	Description
`name`	string	Label used in output names/logs.
`t`	number	Time span in seconds for each detection slice.

tsample:
  - name: t0
    t: 0.5

Shorter t values can help narrow pulses but increase the number of chunks; wider values are often more robust for broader or scattered pulses.

`dmrange`¶

Actual DM trial grid used for dedispersion.

Field	Type	Description
`name`	string	Label used in output names/logs.
`dm_low`	number	Lower DM bound in pc cm^-3.
`dm_high`	number	Upper DM bound in pc cm^-3.
`dm_step`	number	DM trial spacing.

dmrange:
  - name: dm_10_600
    dm_low: 10
    dm_high: 600
    dm_step: 1

For FRB searches, use enough trials to cover the expected source DM and keep the number of DM trials large enough for stable detector behavior.

`dm_limt`¶

Candidate DM acceptance ranges. The configuration key is dm_limt for compatibility with existing AstroFlow configuration files.

Field	Type	Description
`name`	string	Label for the candidate DM range.
`dm_low`	number	Lower candidate DM bound.
`dm_high`	number	Upper candidate DM bound.

dm_limt:
  - name: valid_frb_dm
    dm_low: 0
    dm_high: 800

If omitted, the detector receives None for the candidate DM limits.

`freqrange`¶

Frequency windows in MHz.

Field	Type	Description
`name`	string	Label used in output names/logs.
`freq_start`	number	Start frequency in MHz.
`freq_end`	number	End frequency in MHz.

freqrange:
  - name: fullband
    freq_start: 1130
    freq_end: 1465

Multiple tsample, dmrange, and freqrange entries are combined as a Cartesian product, so the number of runs grows quickly.

RFI Options¶

rfi:
  use_mask: false
  use_zero_dm: false
  use_iqrm: true

iqrm:
  mode: 1
  radius_frac: 0.1
  nsigma: 10.0
  geofactor: 1.5
  win_sec: 0
  hop_sec: 0.5
  include_tail: true

Option	Type	Default	Description
`rfi.use_mask`	boolean	`false`	Apply external bad-channel masks. Requires `maskfile` or `maskdir`.
`rfi.use_zero_dm`	boolean	`false`	Apply zero-DM filtering. This can suppress broadband RFI but may affect bright astrophysical signals.
`rfi.use_iqrm`	boolean	`false` unless set	Enable IQRM-based RFI mitigation.
`maskfile`	string	empty	Single bad-channel mask file. The file must exist when configured.
`maskdir`	string	none	Directory containing masks named like `<basename>_your_rfi_mask.bad_chans`.

`iqrm`¶

iqrm is required when rfi.use_iqrm: true and must contain every field below.

Field	Type	Description
`mode`	integer	IQRM statistic mode. Use `0` for mean-based statistics and `1` for the alternate robust statistic supported by the backend.
`radius_frac`	number	Radius as a fraction of channel count for lag selection.
`nsigma`	number	Outlier threshold. Higher values are more conservative.
`geofactor`	number	Geometric progression factor for lag selection.
`win_sec`	number	Window length in seconds. `0` means use the full data block.
`hop_sec`	number	Sliding-window hop in seconds.
`include_tail`	boolean	Process the remaining tail window when the data length is not an exact multiple of the hop.

Plotting Options¶

`dmtconfig`¶

Option	Type	Default	Description
`minpercentile`	number	`0.1`	Lower percentile for DM-time image scaling.
`maxpercentile`	number	`99.99`	Upper percentile for DM-time image scaling.

Older examples may include meadianbulr and guassion. These options are preserved for backward compatibility; new configurations only need the percentile controls above.

`specconfig`¶

Option	Type	Default	Description
`minpercentile`	number	`0.1`	Lower percentile for dynamic-spectrum image scaling.
`maxpercentile`	number	`99.99`	Upper percentile for dynamic-spectrum image scaling.
`tband`	number	`300.0`	Dynamic-spectrum time window in milliseconds.
`mode`	string	`subband`	Spectrum display mode. Supported values are `subband`, `standard`, and `detrend`; `std` is normalized to `standard`.
`subtsamp`	integer	`4`	Time aggregation factor used in subband plotting.
`subfreq`	integer	`128`	Number of output frequency subbands. Values less than or equal to zero use all channels.
`dtrend`	boolean	`false`	Apply linear detrending in `subband` mode. Alias: `detrend`.
`norm`	boolean	`true`	Normalize subbands before plotting.
`savetype`	string	`png`	Candidate image format. Use `png` or `jpg`.
`snr_boxcar_max_ms`	number or null	`30.0`	Maximum boxcar width for SNR estimation in milliseconds. Alias: `boxcar_max_ms`. Use `null` for the default 30-sample path, or `<= 0` to disable the cap.
`onlyspec`	boolean	`false`	Save spectrum-only output instead of the full candidate panel in supported plotting paths.
`gc_collect_every_files`	integer	`10`	Run garbage collection after this many plotted files. Use `0` to disable.

Mode Behavior¶

Mode	`input` must be	Behavior
`single`	File	Search one `.fil` or `.fits` file.
`directory`	Directory	Search supported files in a directory.
`muti`	Directory	Compatibility alias for multi-file directory search.
`monitor`	Directory	Watch a directory and process new files. CLI options `--check-interval` and `--stop-file` control polling.
`dataset`	Directory	Search files and compare detections with `candpath` ground truth.

Output Layout¶

A typical run creates:

output/
├── astroflow.log
├── background/
├── cached/
├── candidate/
├── detect/
├── frb/
└── astroflow_cands.csv

The exact folders depend on the selected mode and whether candidate plotting or CSV generation is enabled.

AstroFlow

Navigation

Related Topics

YAML Configuration Reference¶

Minimal Single-File Example¶

Top-Level Options¶

Processing And GPU Options¶

Detection Options¶

Search Grid Options¶

`tsample`¶

`dmrange`¶

`dm_limt`¶

`freqrange`¶

RFI Options¶

`iqrm`¶

Plotting Options¶

`dmtconfig`¶

`specconfig`¶

Mode Behavior¶

Output Layout¶

YAML Configuration Reference¶

Minimal Single-File Example¶

Top-Level Options¶

Processing And GPU Options¶

Detection Options¶

Search Grid Options¶

tsample¶

dmrange¶

dm_limt¶

freqrange¶

RFI Options¶

iqrm¶

Plotting Options¶

dmtconfig¶

specconfig¶

Mode Behavior¶

Output Layout¶

`tsample`¶

`dmrange`¶

`dm_limt`¶

`freqrange`¶

`iqrm`¶

`dmtconfig`¶

`specconfig`¶