arguslib.radar package

class arguslib.radar.RadarData(campaign, scan_type='rhi')

Bases: object

get_filepath(dt)

Finds the filepath of a radar scan that contains the given datetime ‘dt’. It searches all files for the day of ‘dt’, then checks their actual scan start and end times by reading the file metadata. Returns the path to the first suitable file found (sorted by filename).

Return type:

str

get_gridded_data_time(dt, var)

Return type:

DataArray

get_next_time(dt, max_gap_hrs=48)

Get the next available time for the radar data. This method might need review if its definition of “next time” should also consider scans crossing hour boundaries more explicitly, but for now, it finds the next file start time.

get_pyart_radar(dt)

Return type:

Radar

class arguslib.radar.Radar(beamwidth, *args, **kwargs)

Bases: Instrument

annotate_intersections(positions, ages, dt, ax, **kwargs)

Calculates and annotates where a given path intersects the radar scan.

annotate_positions(positions, dt, ax, *args, plotting_method=None, label=None, **kwargs)

Annotates one or more geographical positions on the instrument’s plot.

Parameters:

• positions (list[Position]) – A list of Position objects to annotate.

• dt (datetime.datetime) – The datetime for which the view is valid.

• ax (matplotlib.axes.Axes) – The axis (or axes) to plot on.

• **kwargs – Keyword arguments passed to the underlying plotting function (e.g., ax.plot or ax.scatter).

Returns:

The updated axis (or axes).

Return type:

matplotlib.axes.Axes

beam(radar_elevation, radar_azimuth, radar_distances)

classmethod from_config(campaign, **kwargs)

initialise_data_loader()

class arguslib.radar.RadarInterface(radar, camera)

Bases: PlottableInstrument, ProvidesRadarScanTime

Combines a radar and a plottable instrument (e.g., Camera) for synchronized visualization.

This class facilitates the creation of plots that show a camera’s view (or another instrument’s view) side-by-side with a corresponding radar scan. It also handles overlaying radar-derived information, such as the scan volume or individual beams, onto the camera’s display.

The core functionality is provided by the show method, which generates the combined plot.

radar

The radar instrument instance.

Type:

Radar

camera

The camera or other instrument to plot alongside the radar.

Type:

PlottableInstrument

annotate_intersections(positions, ages, dt, ax, **kwargs)

annotate_positions(positions, dt, ax, cam_kwargs={}, radar_kwargs={}, **kwargs)

Annotates geographical positions on both the camera and radar plots.

Parameters:

• positions (list[Position]) – A list of Position objects to annotate.

• dt (datetime.datetime) – The datetime for the annotation.

• ax (tuple[Axes, Axes]) – A tuple of the two axes (ax_camera, ax_radar) to plot on.

• cam_kwargs (dict, optional) – Keyword arguments passed specifically to camera.annotate_positions. Defaults to {}.

• radar_kwargs (dict, optional) – Keyword arguments passed specifically to radar.annotate_positions. Defaults to {}.

• **kwargs – Keyword arguments passed to both annotation methods.

Returns:

The updated camera and radar axes.

Return type:

tuple[Axes, Axes]

classmethod from_campaign(campaign, camstr)

get_scan_time_bounds(dt)

Returns the UTC start and end time of the radar scan corresponding to dt. This method makes the class conform to the ProvidesRadarScanTime protocol.

Return type:

tuple[datetime, datetime]

show(dt, ax=None, var='DBZ', kwargs_camera=None, kwargs_radar_scan=None, kwargs_radar_beams=None, annotate_beams=True, beam_type='start_end', ranges_km_for_beams=None, annotate_scan_box=True, kwargs_scan_box=None, show_legend=False, **kwargs)

Displays the camera view and radar scan side-by-side for a specific time.

This is the primary method for this class. It creates a figure with two subplots: one for the camera/target instrument’s view and one for the radar scan (e.g., an RHI or PPI plot). It can also orchestrate the annotation of radar beams and scan boundaries on the camera view.

Parameters:

• dt (datetime.datetime) – The datetime for the visualization. This time must correspond to an available radar scan.

• ax (tuple[Axes, Axes], optional) – A tuple of two Matplotlib axes (ax_camera, ax_radar) to plot on. If None, new axes are created. Defaults to None.

• var (str, optional) – The radar variable to plot (e.g., ‘DBZ’). Defaults to “DBZ”.

• kwargs_camera (dict, optional) – Keyword arguments passed to the camera.show() method. Defaults to None.

• kwargs_radar_scan (dict, optional) – Keyword arguments passed to the radar.show() method. Defaults to None.

• kwargs_radar_beams (dict, optional) – Keyword arguments for plotting radar beams on the camera, passed to annotate_radar_beams. Defaults to None.

• annotate_beams (bool, optional) – If True, overlays radar beams on the camera view. Defaults to True.

• beam_type (str, optional) – Type of beams to show (‘start_end’, ‘active’). Defaults to ‘start_end’.

• ranges_km_for_beams (list, optional) – Distances along the beam to plot. Defaults to None.

• annotate_scan_box (bool, optional) – If True, overlays the scan extent on the camera view. Defaults to True.

• kwargs_scan_box (dict, optional) – Keyword arguments for plotting the scan box. Defaults to None.

• show_legend (bool, optional) – If True, attempts to display a legend on the camera plot. Defaults to False.

• **kwargs – Additional keyword arguments passed to radar.show().

show_camera(dt, show_legend=False, ax=None, kwargs_beam={}, **kwargs)

class arguslib.radar.RadarOverlayInterface(radar, target_instrument)

Bases: PlottableInstrument

An interface to overlay radar-derived information (like beams or scan locations) onto another PlottableInstrument’s display (e.g., a Camera).

annotate_positions(positions, dt, ax=None, *args, **kwargs)

Annotates arbitrary positions onto the target instrument’s display. Delegates to the target instrument’s annotate_positions method.

annotate_radar_beams(dt, ax=None, ranges_km=None, beam_type='start_end', **kwargs)

Annotates radar beams onto the target instrument’s display.

Parameters:

• dt (datetime) – Datetime for the radar scan/beam.

• ax (any) – Matplotlib axes (or None for DirectCamera).

• ranges_km (ndarray) – Array of distances (km) along the beam for annotation points. If None, uses radar’s max range or a default.

• beam_type (str) – Type of beam(s) to annotate: ‘start_end’: Annotate the first and last beams of the scan (default). ‘active’: Annotate the single ray closest to ‘dt’. ‘all_sweeps’: Annotate the first ray of each sweep.

• **kwargs – Additional arguments passed to target_instrument.annotate_positions().

annotate_scan_box(dt, ax=None, range_km=10.0, **kwargs)

Annotates a box representing the cross-scan extent.

classmethod from_campaign(campaign, target_instrument_config)

Factory method to create RadarOverlayInterface. The radar is always the default radar for the campaign. The target_instrument is created based on target_instrument_config.

property image

show(dt, ax=None, **kwargs)

Shows the target instrument’s display. Radar overlays are added via separate annotation methods. If this RadarOverlayInterface’s show() method is called with kwargs to control beam/box annotations, it will perform them after showing the target instrument.

Parameters:

• dt (datetime) – Datetime for the display.

• ax (any) – Matplotlib axes to plot on (if target_instrument uses them). Expected to be None if target_instrument is a DirectCamera.

• **kwargs (any) – Arguments for target_instrument.show() and for controlling radar annotations (e.g., annotate_beams, beam_type, kwargs_radar_beams, annotate_scan_box, range_km_scan_box, kwargs_scan_box).

Returns:

The axes object returned by target_instrument.show() (or None).

to_image_array(time=True)

If the target_instrument supports to_image_array (e.g., is a DirectCamera), this method calls its to_image_array() method.