modeltool — sky model management

modeltool manages sky models in LSMTool / BBS format for NenuFAR direction-dependent calibration with DP3.

build — fetch sky model from catalog

Downloads sources from a radio catalog within a given radius of the Measurement Set phase centre and writes an intrinsic sky model in LSMTool BBS format.

Usage

modeltool build obs.MS

By default this fetches all sources brighter than 0.5 Jy (at 74 MHz) within 20° of the phase centre from the LCS165 catalog and writes catalog.skymodel. Adjust the field with --radius, --min_flux, and --out_file.

Use --catalog specfind for the SPECFIND catalog instead: it covers a wider frequency range and may give better spectral indices for some fields, but has fewer sources than LCS165 at NenuFAR frequencies.

Reference

modeltool build

Build an intrinsic sky model from catalog

Usage

modeltool build [OPTIONS] MS_FILE

Options

-c, --catalog <catalog>

The catalog to fetch data from

Options:

specfind | lcs165

-m, --min_flux <min_flux>

Min Flux of the catalog at 74 MHz in Jy

Default:

0.5

-r, --radius <radius>

Radius around the phase center

Default:

20

-o, --out_file <out_file>

Output filename

Default:

'catalog.skymodel'

Arguments

MS_FILE

Required argument

attenuate / deattentuate — apply and remove the NenuFAR beam

attenuate converts an intrinsic sky model to an apparent sky model by multiplying each source flux by the NenuFAR beam response at the source position. It also filters out sources and patches that fall below a flux threshold or that are below the horizon during the observation.

deattentuate is the inverse: it divides source fluxes by the beam to recover the intrinsic model from an apparent one. This is used after a calibration/subtraction step where the pipeline has modified the apparent model and you need to propagate those changes back to intrinsic fluxes.

Both commands read the observation time samples and frequency range from the Measurement Set to compute the beam accurately.

attenuate

modeltool attenuate obs.MS catalog.skymodel

Produces apparent.skymodel with all sources attenuated by the beam and patches below 20 Jy removed. Multiple input models are concatenated before the beam is applied, so the field and A-Team models can be combined in one pass:

modeltool attenuate obs.MS catalog.skymodel ateam.skymodel --out_file apparent.skymodel

Filtering is controlled by --min_flux, --min_flux_patch, and --min_elevation; --keep and --remove force specific patches in or out regardless of flux.

deattentuate

modeltool deattentuate obs.MS residual_apparent.skymodel --out_file residual_intrinsic.skymodel

Divides source fluxes back out by the beam to recover the intrinsic model. A floor of --min_beam 0.01 (1 % of peak beam) prevents division by zero for heavily attenuated sources; raise it if faint-source fluxes come out noisy.

Reference

modeltool attenuate

Make apparent sky model from intrinsic beam model

Usage

modeltool attenuate [OPTIONS] MS_FILE INPUT_MODELS...

Options

-m, --min_flux <min_flux>

Minimum flux of the apparent sky model

Default:

0.5

-p, --min_flux_patch <min_flux_patch>

Minimum patch flux

Default:

20

-e, --min_elevation <min_elevation>

Minimum elevation in degree

Default:

10

-k, --keep <keep>

Always keep specified patch

-r, --remove <remove>

Always remove specified patch

-o, --out_file <out_file>

Output filename

Default:

'apparent.skymodel'

--beamsquint_frequency_mhz <beamsquint_frequency_mhz>

Beam squint frequency in MHz

Default:

70

Arguments

MS_FILE

Required argument

INPUT_MODELS

Required argument(s)

modeltool deattentuate

Convert apparent sky model back to intrinsic by removing beam attenuation

Usage

modeltool deattentuate [OPTIONS] MS_FILE INPUT_MODELS...

Options

-o, --out_file <out_file>

Output filename

Default:

'intrinsic.skymodel'

--beamsquint_frequency_mhz <beamsquint_frequency_mhz>

Beam squint frequency in MHz

Default:

70

--min_beam <min_beam>

Beam floor to prevent division by zero for heavily attenuated sources

Default:

0.01

Arguments

MS_FILE

Required argument

INPUT_MODELS

Required argument(s)

concatenate — merge multiple sky models

Concatenates two or more sky model files into one and then applies flux and elevation filtering. This is useful when the main field model and an A-Team model are kept as separate files and need to be combined before clustering.

Unlike attenuate, no beam is applied — source fluxes are left as they are in the input files.

Usage

modeltool concatenate obs.MS catalog.skymodel ateam.skymodel --out_file combined.skymodel

Sources from all inputs are merged into one model. Faint patches are trimmed with --min_flux_patch, and --keep forces a named patch to survive regardless of its flux.

Reference

modeltool concatenate

Concatenate multiple sky models file into one

Usage

modeltool concatenate [OPTIONS] MS_FILE INPUT_MODELS...

Options

-m, --min_flux <min_flux>

Minimum flux of the apparent sky model

Default:

0.5

-p, --min_flux_patch <min_flux_patch>

Minimum patch flux

Default:

20

-e, --min_elevation <min_elevation>

Minimum elevation in degree

Default:

10

-k, --keep <keep>

Always keep specified patch

-r, --remove <remove>

Always remove specified patch

-o, --out_file <out_file>

Output filename

Default:

'apparent.skymodel'

Arguments

MS_FILE

Required argument

INPUT_MODELS

Required argument(s)

filter — filter a sky model by flux, patch, or elevation

Removes sources and patches from a sky model based on flux thresholds, patch names, and optionally the elevation of each patch during an observation. No beam is applied and no Measurement Set is required unless elevation filtering is needed.

Usage

modeltool filter apparent.skymodel --min-flux 1 --out-file filtered.skymodel

Removes sources below the flux threshold. Patch-level cuts use --min-flux-patch; --keep forces a patch to survive and --remove drops a named patch outright.

Elevation filtering needs a Measurement Set — without --ms it is skipped. With one, patches whose maximum elevation during the observation falls below the threshold are also removed:

modeltool filter apparent.skymodel --ms obs.MS --min-elevation 20 --out-file filtered.skymodel

Reference

modeltool filter

Filter a sky model by flux, patch, and optionally elevation.

Without –ms: applies flux and patch-name filters only.
With –ms: also removes patches whose maximum elevation during the
observation is below –min-elevation.

Usage

modeltool filter [OPTIONS] INPUT_MODEL

Options

-f, --min-flux <min_flux>

Remove individual components below this Stokes I flux (Jy).

Default:

0.5

-p, --min-flux-patch <min_flux_patch>

Remove patches whose total flux is below this value (Jy). 0 disables.

Default:

0.0

-k, --keep <keep>

Always keep this patch (even if below flux threshold).

-r, --remove <remove>

Always remove this patch.

--ms <ms>

Measurement Set for elevation-based filtering. Omit to skip elevation cuts.

--min-elevation <min_elevation>

Remove patches whose max elevation is below this value in degrees (requires –ms).

Default:

10.0

-o, --out-file <out_file>

Output sky model filename.

Default:

'filtered.skymodel'

Arguments

INPUT_MODEL

Required argument

cluster — group sources into calibration directions

Groups sky model sources into direction patches suitable for DP3 direction-dependent calibration (DDECal). Three algorithms are available, all implemented via LSMTool’s grouping operations:

Algorithm

LSMTool operation

When to use

cluster

group('cluster', numClusters=N)

Fixed number of directions; K-means on (RA, Dec)

tessellate

group('tessellate', targetFlux=F)

Equal total-flux groups; N determined by the sky model

voronoi

group('voronoi', targetFlux=F)

Voronoi facets; sources brighter than F become facet centres

After grouping, a summary table is printed showing the position, component count, total Stokes I flux, and brightest component flux of each direction (--summary_file saves it to a text file).

Usage

K-means clustering into a fixed number of directions

modeltool cluster apparent.skymodel --n-clusters 20 --out_file clustered.skymodel

Patch     RA              Dec          N_components  Total_I_Jy  Max_I_Jy
--------- --------------- ------------ ------------  ----------  --------
Patch_03  12:34:56.1      +52:30:00    142           312.45      85.20
Patch_07  13:02:11.4      +55:14:00     98           204.10      62.33
...

Choose --n-clusters based on the number of DP3 DDECal directions your calibration setup can handle. K-means minimises the total within-cluster angular distance, so clusters are roughly equal in sky area but not in flux.

Equal-flux tessellation

modeltool cluster apparent.skymodel \
    --algorithm tessellate \
    --target-flux 100 \
    --out_file clustered.skymodel

LSMTool’s tessellate groups sources so that each direction contains approximately --target-flux Jy of total Stokes I flux. The number of directions is determined automatically. Good choice when you want roughly equal SNR per direction.

Voronoi facets around bright sources

modeltool cluster apparent.skymodel \
    --algorithm voronoi \
    --target-flux 50 \
    --out_file clustered.skymodel

LSMTool’s voronoi uses all sources brighter than --target-flux as facet centres; every remaining source is assigned to its nearest centre. This works well when a small number of strong sources dominate the field.

Reference

modeltool cluster

Cluster a sky model into direction groups for DD calibration.

Three algorithms:
cluster K-means by position, fixed N directions (–n-clusters required)
tessellate equal-flux groups, N driven by sky model (–target-flux required)
voronoi Voronoi facets around bright sources (–target-flux required)

Prints a summary table with patch name, mean position, component count, and total Stokes I flux per direction.

Usage

modeltool cluster [OPTIONS] INPUT_MODEL

Options

-a, --algorithm <algorithm>

Clustering algorithm.

Default:

'cluster'

Options:

cluster | tessellate | voronoi

-n, --n-clusters <n_clusters>

Number of direction groups (required for –algorithm=cluster).

-t, --target-flux <target_flux>

Target flux per group in Jy (required for –algorithm=tessellate or voronoi).

-o, --out_file <out_file>

Output sky model filename.

Default:

'clustered.skymodel'

-s, --summary_file <summary_file>

Write the cluster summary table to this text file.

Arguments

INPUT_MODEL

Required argument

inspect — inspect a grouped sky model

Reads a grouped sky model and outputs one of three things depending on --mode:

Mode

Output

summary (default)

Human-readable table: patch name, position, component count, total flux, brightest component

dp3-directions

DP3 DDECal.directions string ready to paste into a parset

dp3-solints

DP3 per-direction solution interval string, flux-scaled

Usage

Generate the DP3 directions string

modeltool inspect clustered.skymodel --mode dp3-directions

[['Patch_03'],['Patch_07'],['Patch_01'],...]

Paste this directly into your DP3 parset as DDECal.directions.

Exclude a patch (e.g. an A-Team source handled separately):

modeltool inspect clustered.skymodel --mode dp3-directions --exclude CasA

Generate per-direction solution intervals

modeltool inspect clustered.skymodel --mode dp3-solints --solint 30

[1,30,15,10,30,5,...]

Each value is a divisor of --solint chosen proportionally to the patch flux evaluated at --target-freq-mhz (default 66.5 MHz). Brighter patches receive larger solints; the Main patch is always assigned 1. Paste this into your DP3 parset as DDECal.solutions_per_direction.

The flux normalisation is tuned with --max-flux, --min-flux, and --target-freq-mhz.

Reference

modeltool inspect

Inspect a grouped sky model: print a summary or generate DP3 calibration strings.

Output modes:
summary Human-readable table of patches with positions, fluxes, etc.
dp3-directions DP3-ready sourcedb.sourcenames string: [[‘P0’],[‘P1’],…]
dp3-solints Per-direction solution intervals string: [30,15,10,…]

Usage

modeltool inspect [OPTIONS] INPUT_MODEL

Options

-m, --mode <mode>

Output mode.

Default:

'summary'

Options:

summary | dp3-directions | dp3-solints

-e, --exclude <exclude>

Patch name(s) to exclude (dp3-directions only).

--solint <solint>

Base solution interval in time steps (dp3-solints only).

Default:

30

--max-flux <max_flux>

Flux ceiling for solint normalisation in Jy (dp3-solints only).

Default:

50.0

--min-flux <min_flux>

Flux floor for solint normalisation in Jy (dp3-solints only).

Default:

30.0

--target-freq-mhz <target_freq_mhz>

Frequency in MHz at which to evaluate source fluxes (dp3-solints only).

Default:

66.5

-s, --summary-file <summary_file>

Write summary table to this text file (summary mode only).

Arguments

INPUT_MODEL

Required argument

plot — visualise a sky model

Plots source positions on the sky with one colour per patch. Useful for checking cluster assignments after modeltool cluster or verifying which sources survive after filtering.

Usage

modeltool plot clustered.skymodel

Opens an interactive window with each patch in a distinct colour and marker size scaled by source flux, so the dominant components stand out.

Pass --out-file directions.png to save instead of showing (any Matplotlib format works — PNG, PDF, SVG). --no-scale-flux gives uniform markers, and --min-flux 5 plots only sources above 5 Jy — useful for checking which sources drive the bright-patch assignments after tessellate or voronoi.

Reference

modeltool plot

Plot a sky model: one color per patch, sources at their RA/Dec positions.

Usage

modeltool plot [OPTIONS] INPUT_MODEL

Options

-o, --out-file <out_file>

Output image file (PNG, PDF, SVG…). Shows interactively if not given.

--scale-flux, --no-scale-flux

Scale marker size by source flux.

Default:

True

-m, --min-flux <min_flux>

Exclude sources below this Stokes I flux (Jy).

Arguments

INPUT_MODEL

Required argument

set_patch_name — rename all patches to a single name

Renames every source in the sky model to the same patch. This is typically used to reset a sky model to a single-patch state before re-clustering, or to set the Main patch name expected by downstream tools such as modeltool inspect --mode dp3-solints.

Usage

Reset a clustered model to a single patch before re-clustering

modeltool set_patch_name clustered.skymodel Main --out_file reset.skymodel

Rename in place

When --out_file is omitted the input file is overwritten:

modeltool set_patch_name catalog.skymodel Main

Reference

modeltool set_patch_name

Set a single patch name in the sky model

Usage

modeltool set_patch_name [OPTIONS] INPUT_MODEL PATCH_NAME

Options

-o, --out_file <out_file>

Output filename

Arguments

INPUT_MODEL

Required argument

PATCH_NAME

Required argument