jolly-roger 0.0.2__py3-none-any.whl

jolly_roger/__init__.py

@@ -0,0 +1,11 @@
+"""
+Copyright (c) 2025 Alec Thomson. All rights reserved.
+
+jolly-roger: The pirate flagger
+"""
+
+from __future__ import annotations
+
+from ._version import version as __version__
+
+__all__ = ["__version__"]

jolly_roger/_version.py

@@ -0,0 +1,21 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '0.0.2'
+__version_tuple__ = version_tuple = (0, 0, 2)

jolly_roger/_version.pyi

@@ -0,0 +1,4 @@
+from __future__ import annotations
+
+version: str
+version_tuple: tuple[int, int, int] | tuple[int, int, int, str, str]

jolly_roger/baselines.py

@@ -0,0 +1,156 @@
+"""Routines and structures to describe antennas, their
+XYZ and baseline vectors"""
+
+from __future__ import annotations
+
+from argparse import ArgumentParser
+from dataclasses import dataclass
+from itertools import combinations
+from pathlib import Path
+
+import astropy.units as u
+import matplotlib.pyplot as plt
+import numpy as np
+from casacore.tables import table
+
+from jolly_roger.logging import logger
+
+
+@dataclass
+class Baselines:
+    """Container representing the antennas found in some measurement set, their
+    baselines and associated mappings. Only the upper triangle of
+    baselines are formed, e.g. 1-2 not 2-1.
+    """
+
+    ant_xyz: np.ndarray
+    """Antenna (X,Y,Z) coordinates taken from the measurement set"""
+    b_xyz: np.ndarray
+    """The baseline vectors formed from each antenna-pair"""
+    b_idx: np.ndarray
+    """Baselihe indices representing a pair of antenna"""
+    b_map: dict[tuple[int, int], int]
+    """A mapping between two antennas to their baseline index"""
+    ms_path: Path
+    """The measurement set used to construct some instance of `Baseline`"""
+
+
+def get_baselines_from_ms(ms_path: Path) -> Baselines:
+    """Extract the antenna positions from the nominated measurement
+    set and constructed the set of baselines. These are drawn from
+    the ANTENNA table in the measurement set.
+
+    Args:
+        ms_path (Path): The measurement set to extract baseliens from
+
+    Returns:
+        Baselines: The corresponding set of baselines formed.
+    """
+
+    logger.info(f"Creating baseline instance from {ms_path=}")
+    with table(str(ms_path / "ANTENNA"), ack=False) as tab:
+        ants_idx = np.arange(len(tab), dtype=int)
+        b_idx = np.array(list(combinations(list(ants_idx), 2)))
+        xyz = tab.getcol("POSITION")
+        b_xyz = xyz[b_idx[:, 0]] - xyz[b_idx[:, 1]]
+
+    b_map = {tuple(k): idx for idx, k in enumerate(b_idx)}
+
+    logger.info(f"ants={len(ants_idx)}, baselines={b_idx.shape[0]}")
+    return Baselines(
+        ant_xyz=xyz * u.m, b_xyz=b_xyz * u.m, b_idx=b_idx, b_map=b_map, ms_path=ms_path
+    )
+
+
+@dataclass
+class BaselinePlotPaths:
+    """Names for plots for baseline visualisations"""
+
+    antenna_path: Path
+    """Output for the antenna XYZ plot"""
+    baseline_path: Path
+    """Output for the baselines vector plot"""
+
+
+def make_plot_names(ms_path: Path) -> BaselinePlotPaths:
+    """Construct the output paths of the diagnostic plots
+
+    Args:
+        ms_path (Path): The measurement set the plots are created for
+
+    Returns:
+        BaselinePlotPaths: The output paths for the plot names
+    """
+
+    basename = ms_path.parent / ms_path.stem
+
+    antenna_path = Path(f"{basename!s}-antenna.pdf")
+    baseline_path = Path(f"{basename!s}-baseline.pdf")
+
+    return BaselinePlotPaths(antenna_path=antenna_path, baseline_path=baseline_path)
+
+
+def plot_baselines(baselines: Baselines) -> BaselinePlotPaths:
+    """Create basic diagnostic plots for a set of baselines. This
+    includes the antenna positions and the baseline vectors.
+
+    Args:
+        baselines (Baselines): The loaded instance of the baselines from a measurement set
+
+    Returns:
+        BaselinePlotPaths: The output paths of the plots created
+    """
+
+    plot_names = make_plot_names(ms_path=baselines.ms_path)
+
+    # Make the initial antenna plot
+    fig, ax = plt.subplots(1, 1)
+
+    ax.scatter(baselines.b_xyz[:, 0], baselines.b_xyz[:, 1], label="Baseline")
+
+    ax.set(xlabel="X (meters)", ylabel="Y (meters)", title="ASKAP Baseline Vectors")
+    ax.legend()
+
+    fig.tight_layout()
+    fig.savefig(plot_names.baseline_path)
+
+    # Now plot the antennas
+    fig, ax = plt.subplots(1, 1)
+
+    ax.scatter(baselines.ant_xyz[:, 0], baselines.ant_xyz[:, 1], label="Antenna")
+
+    ax.set(xlabel="X (meters)", ylabel="Y (meters)", title="ASKAP Antenna positions")
+    ax.legend()
+    fig.tight_layout()
+    fig.savefig(plot_names.antenna_path)
+
+    return plot_names
+
+
+def get_parser() -> ArgumentParser:
+    parser = ArgumentParser(
+        description="Extract and plot antenna dna baseline information from a measurement set"
+    )
+
+    sub_parsers = parser.add_subparsers(dest="mode")
+
+    plot_parser = sub_parsers.add_parser(
+        "plot", description="Basic plots around baselines"
+    )
+    plot_parser.add_argument("ms_path", type=Path, help="Path to the measurement set")
+
+    return parser
+
+
+def cli() -> None:
+    parser: ArgumentParser = get_parser()
+
+    args = parser.parse_args()
+
+    if args.mode == "plot":
+        baselines = get_baselines_from_ms(ms_path=args.ms_path)
+        plot_baselines(baselines=baselines)
+
+
+if __name__ == "__main__":
+    cli()

jolly_roger/flagger.py

@@ -0,0 +1,101 @@
+"""Flagging utility for a MS"""
+
+from __future__ import annotations
+
+from argparse import ArgumentParser
+from dataclasses import dataclass
+from pathlib import Path
+
+import astropy.units as u
+
+from jolly_roger.baselines import get_baselines_from_ms
+from jolly_roger.hour_angles import make_hour_angles_for_ms
+from jolly_roger.logging import logger
+from jolly_roger.uvws import uvw_flagger, xyz_to_uvw
+
+
+@dataclass
+class JollyRogerFlagOptions:
+    """Specifications of the flagging to carry out"""
+
+    min_scale_deg: float = 0.075
+    """Minimum angular scale to project to UVW"""
+    min_horizon_limit_deg: float = -3
+    """The minimum elevation for the sun projected baselines to be considered for flagging"""
+    max_horizon_limit_deg: float = 90
+    """The minimum elevation for the sun projected baselines to be considered for flagging"""
+    dry_run: bool = False
+    """Do not apply the flags"""
+
+
+def flag(ms_path: Path, flag_options: JollyRogerFlagOptions) -> Path:
+    # Trust no one
+    logger.debug(f"{flag_options=}")
+
+    ms_path = Path(ms_path)
+    logger.info(f"Flagging {ms_path=}")
+
+    baselines = get_baselines_from_ms(ms_path=ms_path)
+    hour_angles = make_hour_angles_for_ms(ms_path=ms_path, position="sun")
+
+    uvws = xyz_to_uvw(baselines=baselines, hour_angles=hour_angles)
+    ms_path = uvw_flagger(
+        computed_uvws=uvws,
+        min_horizon_lim=flag_options.min_horizon_limit_deg * u.deg,
+        max_horizon_lim=flag_options.max_horizon_limit_deg * u.deg,
+        min_sun_scale=flag_options.min_scale_deg * u.deg,
+        dry_run=flag_options.dry_run,
+    )
+    logger.info(f"Finished processing {ms_path=}")
+
+    return ms_path
+
+
+def get_parser() -> ArgumentParser:
+    parser = ArgumentParser(
+        description="Flag a measurement set based on properties of the Sun"
+    )
+    parser.add_argument("ms_path", type=Path, help="The measurement set to flag")
+
+    parser.add_argument(
+        "--min-scale-deg",
+        type=float,
+        default=0.075,
+        help="The minimum scale required for flagging",
+    )
+    parser.add_argument(
+        "--min-horizon-limit-deg",
+        type=float,
+        default=-3,
+        help="The minimum elevation of the centroid of the object (e.g. sun) for uvw flagging to be activated",
+    )
+    parser.add_argument(
+        "--max-horizon-limit-deg",
+        type=float,
+        default=-3,
+        help="The maximum elevation of the centroid of the object (e.g. sun) for uvw flagging to be activated",
+    )
+    parser.add_argument(
+        "--dry-run", action="store_true", help="Do not apply the computed flags"
+    )
+
+    return parser
+
+
+def cli() -> None:
+    parser = get_parser()
+
+    args = parser.parse_args()
+
+    flag_options = JollyRogerFlagOptions(
+        min_scale_deg=args.min_scale_deg,
+        min_horizon_limit_deg=args.min_horizon_limit_deg,
+        max_horizon_limit_deg=args.max_horizon_limit_deg,
+        dry_run=args.dry_run,
+    )
+
+    flag(ms_path=args.ms_path, flag_options=flag_options)
+
+
+if __name__ == "__main__":
+    cli()

jolly_roger/hour_angles.py

@@ -0,0 +1,159 @@
+"""Utilities to construct properties that scale over hour angle"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+import astropy.units as u
+import numpy as np
+from astropy.coordinates import EarthLocation, SkyCoord, get_sun
+from astropy.time import Time
+from casacore.tables import table
+
+from jolly_roger.logging import logger
+
+# Default location with XYZ based on mean of antenna positions
+ASKAP_XYZ_m = np.array([-2556146.66356375, 5097426.58592797, -2848333.08164107]) * u.m
+ASKAP = EarthLocation(*ASKAP_XYZ_m)
+
+
+@dataclass
+class PositionHourAngles:
+    """Represent time, hour angles and other quantities for some
+    assumed sky position. Time intervals are intended to represent
+    those stored in a measurement set."""
+
+    hour_angle: u.rad
+    """The hour angle across sampled time intervales of a source for a Earth location"""
+    time_mjds: np.ndarray
+    """The MJD time in seconds from which other quantities are evalauted against. Should be drawn from a measurement set."""
+    location: EarthLocation
+    """The location these quantities have been derived from."""
+    position: SkyCoord
+    """The sky-position that is being used to calculate quantities towards"""
+    elevation: np.ndarray
+    """The elevation of the ``position` direction across time"""
+    time: Time
+    """Representation of the `time_mjds` attribute"""
+    time_map: dict[float, int]
+    """Index mapping of time steps described in `time_mjds` to an array index position.
+    This is done by selecting all unique `time_mjds` and ordering in this 'first seen'
+    position"""
+
+
+def _process_position(
+    position: SkyCoord | Literal["sun"] | None = None,
+    ms_path: Path | None = None,
+    times: Time | None = None,
+) -> SkyCoord:
+    """Acquire a SkyCoord object towards a specified position. If
+    a known string position is provided this will be looked up and
+    may required the `times` (e.g. for the sun). Otherwise is position
+    is None it will be drawn from the PHASE_DIR in the provided measurement
+    set
+
+    Args:
+        position (SkyCoord | Literal["sun"] | None, optional): The position to be considered. Defaults to None.
+        ms_path (Path | None, optional): The path with the PHASE_DIR to use should `position` be None. Defaults to None.
+        times (Time | None, optional): Times to used if they are required in the lookup. Defaults to None.
+
+    Raises:
+        ValueError: Raised if a string position is provided without a `times`
+        ValueError: Raised is position is None and no ms_path provided
+        ValueError: Raised if no final SkyCoord is constructed
+
+    Returns:
+        SkyCoord: The position to use
+    """
+
+    if isinstance(position, str):
+        if times is None:
+            msg = f"{times=}, but needs to be set when position is a name"
+            raise ValueError(msg)
+        if position == "sun":
+            logger.info("Getting sky-position of the sun")
+            position = get_sun(times)
+
+    if position is None:
+        if ms_path is None:
+            msg = f"{position=}, so default position can't be drawn. Provide a ms_path="
+            raise ValueError(msg)
+
+        with table(str(ms_path / "FIELD")) as tab:
+            logger.info(f"Getting the sky-position from PHASE_DIR of {ms_path=}")
+            field_positions = tab.getcol("PHASE_DIR")
+            position = SkyCoord(field_positions[0] * u.rad)
+
+    if isinstance(position, SkyCoord):
+        return position
+
+    # Someone sea dog is having a laugh
+    msg = "Something went wrong in the processing of position"
+    raise ValueError(msg)
+
+
+def make_hour_angles_for_ms(
+    ms_path: Path,
+    location: EarthLocation = ASKAP,
+    position: SkyCoord | str | None = None,
+    whole_day: bool = False,
+) -> PositionHourAngles:
+    """Calculate hour-angle and time quantities for a given position using time information
+    encoded in a nominated measurement set at a nominated location
+
+    Args:
+        ms_path (Path): Measurement set to usefor time and sky-position information
+        location (EarthLocation, optional): The location to use when calculate LST. Defaults to ASKAP.
+        position (SkyCoord | str | None, optional): The sky-direction hour-angles will be calculated towards. Defaults to None.
+        whole_day (bool, optional): Calaculate for a 24 hour persion starting from the first time step. Defaults to False.
+
+    Returns:
+        PositionHourAngle: Compute hour angles, normalised times and elevation
+    """
+
+    logger.info(f"Computing hour angles for {ms_path=}")
+    with table(str(ms_path), ack=False) as tab:
+        logger.info("Extracting timesteps and constructing time mapping")
+        times_mjds = tab.getcol("TIME_CENTROID")
+
+        # get unique time steps and make sure they are in their first appeared order
+        times_mjds, indices = np.unique(times_mjds, return_index=True)
+        sorted_idx = np.argsort(indices)
+        times_mjds = times_mjds[sorted_idx]
+        time_map = {k: idx for idx, k in enumerate(times_mjds)}
+
+    if whole_day:
+        logger.info(f"Assuming a full day from {times_mjds} MJD (seconds)")
+        time_step = times_mjds[1] - times_mjds[0]
+        times_mjds = times_mjds[0] + time_step * np.arange(
+            int(60 * 60 * 24 / time_step)
+        )
+
+    times = Time(times_mjds / 60 / 60 / 24, format="mjd")
+
+    sky_position: SkyCoord = _process_position(
+        position=position, times=times, ms_path=ms_path
+    )
+
+    lst = times.sidereal_time("apparent", longitude=location.lon)
+    hour_angle = lst - sky_position.ra
+    mask = hour_angle > 12 * u.hourangle
+    hour_angle[mask] -= 24 * u.hourangle
+
+    logger.info("Creatring elevation curve")
+    sin_alt = np.arcsin(
+        np.sin(location.lat) * np.sin(sky_position[0].dec.rad)
+        + np.cos(location.lat) * np.cos(sky_position.dec.rad) * np.cos(hour_angle)
+    ).to(u.rad)
+
+    return PositionHourAngles(
+        hour_angle=hour_angle,
+        time_mjds=times_mjds,
+        location=location,
+        position=sky_position,
+        elevation=sin_alt,
+        time=times,
+        time_map=time_map,
+    )

jolly_roger/logging.py

@@ -0,0 +1,48 @@
+"""Basic python logging setup"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, ClassVar
+
+# Create logger
+logging.captureWarnings(True)
+logger = logging.getLogger("jolly_rodger")
+logger.setLevel(logging.INFO)
+
+# Create console handler and set level to debug
+ch = logging.StreamHandler()
+ch.setLevel(logging.DEBUG)
+
+
+class CustomFormatter(logging.Formatter):
+    """A custom logger formatter"""
+
+    grey = "\x1b[38;20m"
+    blue = "\x1b[34;20m"
+    green = "\x1b[32;20m"
+    yellow = "\x1b[33;20m"
+    red = "\x1b[31;20m"
+    bold_red = "\x1b[31;1m"
+    reset = "\x1b[0m"
+    format_str = "%(asctime)s.%(msecs)03d: %(message)s"
+
+    FORMATS: ClassVar = {
+        logging.DEBUG: f"{blue}%(levelname)s{reset} {format_str}",
+        logging.INFO: f"{green}%(levelname)s{reset} {format_str}",
+        logging.WARNING: f"{yellow}%(levelname)s{reset} {format_str}",
+        logging.ERROR: f"{red}%(levelname)s{reset} {format_str}",
+        logging.CRITICAL: f"{bold_red}%(levelname)s{reset} {format_str}",
+    }
+
+    def format(self, record: Any) -> Any:
+        log_fmt = self.FORMATS.get(record.levelno)
+        formatter = logging.Formatter(log_fmt, "%Y-%m-%d %H:%M:%S")
+        return formatter.format(record)
+
+
+# Add formatter to ch
+ch.setFormatter(CustomFormatter())
+
+# Add ch to logger
+logger.addHandler(ch)

jolly_roger/uvws.py

@@ -0,0 +1,289 @@
+"""Calculating the UVWs for a measurement set towards a direction"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import astropy.units as u
+import numpy as np
+from astropy.constants import c as speed_of_light
+from casacore.tables import table, taql
+from tqdm import tqdm
+
+from jolly_roger.baselines import Baselines
+from jolly_roger.hour_angles import PositionHourAngles
+from jolly_roger.logging import logger
+
+
+@dataclass
+class UVWs:
+    """A small container to represent uvws"""
+
+    uvws: np.ndarray
+    """The (U,V,W) coordinates"""
+    hour_angles: PositionHourAngles
+    """The hour angle information used to construct the UVWs"""
+    baselines: Baselines
+    """The set of antenna baselines used for form the UVWs"""
+
+
+def xyz_to_uvw(
+    baselines: Baselines,
+    hour_angles: PositionHourAngles,
+) -> UVWs:
+    """Generate the UVWs for a given set of baseline vectors towards a position
+    across a series of hour angles.
+
+    Args:
+        baselines (Baselines): The set of baselines vectors to use
+        hour_angles (PositionHourAngles): The hour angles and position to generate UVWs for
+
+    Returns:
+        UVWs: The generated set of UVWs
+    """
+    b_xyz = baselines.b_xyz
+
+    # Getting the units right is important, mate
+    ha = hour_angles.hour_angle
+    ha = ha.to(u.rad)
+
+    declination = hour_angles.position.dec
+    declination = declination.to(u.rad)
+
+    # This is necessary for broadcastung in the matrix to work.
+    # Should the position be a solar object like the sub its position
+    # will change throughout the observation. but it will have
+    ## been created consistently with the hour angles. If it is fixed
+    # then the use of the numpy ones like will ensure the same shape.
+    declination = (np.ones(len(ha)) * declination).decompose()
+
+    # Precompute the repeated terms
+    sin_ha = np.sin(ha)
+    sin_dec = np.sin(declination)
+    cos_ha = np.cos(ha)
+    cos_dec = np.cos(declination)
+    zeros = np.zeros_like(sin_ha)
+
+    # Conversion from baseline vectors to UVW
+    mat = np.array(
+        [
+            [sin_ha, cos_ha, zeros],
+            [-sin_dec * cos_ha, sin_dec * sin_ha, cos_dec],
+            [
+                np.cos(declination) * np.cos(ha),
+                np.cos(declination) * np.sin(ha),
+                np.sin(declination),
+            ],
+        ]
+    )
+
+    # Every time this confuses me and I need the first mate to look over.
+    # b_xyz shape: (baselines, coord) where coord is XYZ
+    # mat shape: (3, 3, timesteps)
+    # uvw shape: (baseline, coord, timesteps) where coord is UVW
+    uvw = np.einsum("ijk,lj->lik", mat, b_xyz, optimize=True)  # codespell:ignore lik
+
+    # Make order (coord, baseline, timesteps)
+    uvw = np.swapaxes(uvw, 0, 1)
+    logger.debug(f"{uvw.shape=}")
+
+    return UVWs(uvws=uvw, hour_angles=hour_angles, baselines=baselines)
+
+
+@dataclass
+class SunScale:
+    """Describes the (u,v)-scales sensitive to angular scales of the Sun"""
+
+    min_scale_chan_lambda: u.Quantity
+    """The distance that corresponds to an angular scale scaled to each channel set using the minimum angular scale"""
+    chan_lambda: u.Quantity
+    """The wavelength of each channel"""
+    min_scale_deg: float
+    """The minimum angular scale used for baseline flagging"""
+
+
+def get_sun_uv_scales(
+    ms_path: Path,
+    min_scale: u.Quantity = 0.075 * u.deg,
+) -> SunScale:
+    """Compute the angular scales and the corresponding (u,v)-distances that
+    would be sensitive to them.
+
+    Args:
+        ms_path (Path): The measurement set to consider, where frequency information is extracted from
+        min_scale (u.Quantity, optional): The minimum angular scale that will be projected and flgged. Defaults to 0.075*u.deg.
+
+    Returns:
+        SunScale: The sun scales in distances
+    """
+
+    with table(str(ms_path / "SPECTRAL_WINDOW")) as tab:
+        chan_freqs = tab.getcol("CHAN_FREQ")[0] * u.Hz
+
+    chan_lambda_m = np.squeeze((speed_of_light / chan_freqs).to(u.m))
+
+    sun_min_scale_chan_lambda = chan_lambda_m / min_scale.to(u.rad).value
+
+    return SunScale(
+        min_scale_chan_lambda=sun_min_scale_chan_lambda,
+        chan_lambda=chan_lambda_m,
+        min_scale_deg=min_scale,
+    )
+
+
+@dataclass
+class BaselineFlagSummary:
+    """Container to capture the flagged baselines statistics"""
+
+    uvw_flag_perc: float
+    """The percentage of flags to add based on the uv-distance cut"""
+    elevation_flag_perc: float
+    """The percentage of flags to add based on the elevation cut"""
+    jolly_flag_perc: float
+    """The percentage of new to add based on both criteria"""
+
+
+def log_summaries(
+    summary: dict[tuple[int, int], BaselineFlagSummary],
+    min_horizon_lim: u.Quantity,
+    max_horizon_lim: u.Quantity,
+    min_sun_scale: u.Quantity,
+    dry_run: bool = False,
+) -> None:
+    """Log the flagging statistics made throughout the `uvw_flagger`.
+
+    Args:
+        summary (dict[tuple[int, int], BaselineFlagSummary]): Collection of flagging statistics accumulated when flagging
+        min_horizon_lim (u.Quantity): The minimum horizon limit applied to the flagging.
+        max_horizon_lim (u.Quantity): The maximum horizon limit applied to the flagging.
+        min_sun_scale (u.Quantity): The sun scale used to compute the uv-distance limiter.
+        dry_run (bool, optional): Indicates whether the flags were applied. Defaults to False.
+
+    """
+    logger.info("----------------------------------")
+    logger.info("Flagging summary of modified flags")
+    logger.info(f"Minimum Horizon Limit: {min_horizon_lim}")
+    logger.info(f"Maximum Horizon Limit: {max_horizon_lim}")
+    logger.info(f"Minimum Sun Scale: {min_sun_scale}")
+    if dry_run:
+        logger.info("(Dry run, not applying)")
+    logger.info("----------------------------------")
+
+    for ants, baseline_summary in summary.items():
+        logger.info(
+            f"({ants[0]:3d},{ants[1]:3d}): uvw {baseline_summary.uvw_flag_perc:>6.2f}% & elev. {baseline_summary.elevation_flag_perc:>6.2f}% = Applied {baseline_summary.jolly_flag_perc:>6.2f}%"
+        )
+
+    logger.info("\n")
+
+
+def uvw_flagger(
+    computed_uvws: UVWs,
+    min_horizon_lim: u.Quantity = -3 * u.deg,
+    max_horizon_lim: u.Quantity = 90 * u.deg,
+    min_sun_scale: u.Quantity = 0.075 * u.deg,
+    dry_run: bool = False,
+) -> Path:
+    """Flag visibilities based on the (u, v, w)'s and assumed scales of
+    the sun. The routine will compute ht ebaseline length affected by the Sun
+    and then flagged visibilities where the projected (u,v)-distance towards
+    the direction of the Sun and presumably sensitive.
+
+    Args:
+        computed_uvws (UVWs): The pre-computed UVWs and associated meta-data
+        min_horizon_lim (u.Quantity, optional): The lower horixzon limit required for flagging to be applied. Defaults to -3*u.deg.
+        max_horizon_lim (u.Quantity, optional): The upper horixzon limit required for flagging to be applied. Defaults to 90*u.deg.
+        min_sun_scale (u.Quantity, options): The minimum angular scale to consider when flagging the projected baselines. Defaults to 0.075*u.deg.
+        dry_run (bool, optional): Do not apply the flags to the measurement set. Defaults to False.
+
+
+    Returns:
+        Path: The path to the flagged measurement set
+    """
+    hour_angles = computed_uvws.hour_angles
+    baselines = computed_uvws.baselines
+    ms_path = computed_uvws.baselines.ms_path
+
+    sun_scale = get_sun_uv_scales(
+        ms_path=ms_path,
+        min_scale=min_sun_scale,
+    )
+
+    # A list of (ant1, ant2) to baseline index
+    antennas_for_baselines = baselines.b_map.keys()
+    logger.info(f"Will be considering {len(antennas_for_baselines)} baselines")
+
+    elevation_curve = hour_angles.elevation
+
+    # Used to capture the baseline and additional flags added
+    summary: dict[tuple[int, int], BaselineFlagSummary] = {}
+
+    logger.info(f"Opening {ms_path=}")
+    with table(str(ms_path), ack=False, readonly=False) as ms_tab:
+        for ant_1, ant_2 in tqdm(antennas_for_baselines):
+            logger.debug(f"Processing {ant_1=} {ant_2=}")
+
+            # Keeps the ruff from complaining about and unused varuable wheen
+            # it is used in the table access command below
+            _ = ms_tab
+
+            # TODO: It is unclear to TJG whether the time-order needs
+            # to be considered when reading in per-baseline at a time.
+            # initial version operated on a row basis so an explicit map
+            # to the t_idx of computed_uvws.uvws was needed (or useful?)
+
+            # Get the UVWs and for the baseline and calculate the uv-distance
+            b_idx = baselines.b_map[(ant_1, ant_2)]
+            uvws_bt = computed_uvws.uvws[:, b_idx]
+            uv_dist = np.sqrt((uvws_bt[0]) ** 2 + (uvws_bt[1]) ** 2).to(u.m).value
+
+            # The max angular scale corresponds to the shortest uv-distance
+            # The min angular scale corresponds to the longest uv-distance
+            flag_uv_dist = (
+                uv_dist[:, None]
+                <= sun_scale.min_scale_chan_lambda.to(u.m).value[None, :]
+            )
+            flag_elevation = (min_horizon_lim < elevation_curve)[:, None] & (
+                elevation_curve <= max_horizon_lim
+            )[:, None]
+
+            all_flags = flag_uv_dist & flag_elevation
+
+            # Only need to interact with the MS if there are flags to update
+            if not np.any(all_flags):
+                continue
+
+            baseline_summary = BaselineFlagSummary(
+                uvw_flag_perc=np.sum(flag_uv_dist)
+                / np.prod(flag_uv_dist.shape)
+                * 100.0,
+                elevation_flag_perc=np.sum(flag_elevation)
+                / np.prod(flag_elevation.shape)
+                * 100.0,
+                jolly_flag_perc=np.sum(all_flags) / np.prod(all_flags.shape) * 100.0,
+            )
+            summary[(ant_1, ant_2)] = baseline_summary
+
+            # Do not apply the flags mattteee
+            if dry_run:
+                continue
+
+            with taql(
+                "select from $ms_tab where ANTENNA1 == $ant_1 and ANTENNA2 == $ant_2",
+            ) as subtab:
+                flags = subtab.getcol("FLAG")[:]
+                total_flags = flags | all_flags[..., None]
+
+                subtab.putcol("FLAG", total_flags)
+                subtab.flush()
+
+    log_summaries(
+        summary=summary,
+        min_horizon_lim=min_horizon_lim,
+        max_horizon_lim=max_horizon_lim,
+        min_sun_scale=min_sun_scale,
+        dry_run=dry_run,
+    )
+
+    return ms_path

jolly_roger-0.0.2.dist-info/METADATA

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: jolly-roger
+Version: 0.0.2
+Summary: The pirate flagger
+Project-URL: Homepage, https://github.com/flint-crew/jolly-roger
+Project-URL: Bug Tracker, https://github.com/flint-crew/jolly-roger/issues
+Project-URL: Discussions, https://github.com/flint-crew/jolly-roger/discussions
+Project-URL: Changelog, https://github.com/flint-crew/jolly-roger/releases
+Author-email: Alec Thomson <alec.thomson@csiro.au>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: astropy
+Requires-Dist: numpy>=2.0.0
+Requires-Dist: python-casacore>=3.6.0
+Requires-Dist: tqdm
+Description-Content-Type: text/markdown
+
+# jolly-roger
+
+[![Actions Status][actions-badge]][actions-link]
+[![Documentation Status][rtd-badge]][rtd-link]
+
+[![PyPI version][pypi-version]][pypi-link]
+<!-- [![Conda-Forge][conda-badge]][conda-link] -->
+[![PyPI platforms][pypi-platforms]][pypi-link]
+
+<!-- [![GitHub Discussion][github-discussions-badge]][github-discussions-link] -->
+
+<!-- SPHINX-START -->
+
+<!-- prettier-ignore-start -->
+[actions-badge]:            https://github.com/flint-crew/jolly-roger/workflows/CI/badge.svg
+[actions-link]:             https://github.com/flint-crew/jolly-roger/actions
+[conda-badge]:              https://img.shields.io/conda/vn/conda-forge/jolly-roger
+[conda-link]:               https://github.com/conda-forge/jolly-roger-feedstock
+[github-discussions-badge]: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github
+[github-discussions-link]:  https://github.com/flint-crew/jolly-roger/discussions
+[pypi-link]:                https://pypi.org/project/jolly-roger/
+[pypi-platforms]:           https://img.shields.io/pypi/pyversions/jolly-roger
+[pypi-version]:             https://img.shields.io/pypi/v/jolly-roger
+[rtd-badge]:                https://readthedocs.org/projects/jolly-roger/badge/?version=latest
+[rtd-link]:                 https://jolly-roger.readthedocs.io/en/latest/?badge=latest
+
+<!-- prettier-ignore-end -->
+
+The pirate flagger!
+
+# Installation
+
+`pip install jolly-roger`
+
+# About
+
+This package attempts to flag visibilities that are contaminated by the Sun and uses a fairly simple heuristic based on the geometry of an interferometer.
+
+In short, `jolly_roger` flags based on the projected baseline length should the array be tracking the Sun. The projected baseline length between some phased direction being tracked and the Sun can be significantly different. `jolly_roger` attempts to leverage this by only flagging data where the projected baseline length is between some nominal range that corresponds to angular scales associated with the Sun.
+
+`jolly_roger` makes no guarentess about removing all contaminated visibilities, nor does it attempt to peel/subtract the Sun from the visibility data.
+
+## How does it work?
+
+`jolly_roger` will recompute the (u,v,w)-coordinates of a measurement set as if it were tracking the Sun, from which (u,v)-distances are derieved for each baseline and timestep. An updated `FLAG` column can then be inserted into the measurement set suppressing visibilities that would be sensitive to a nominated range of angular scales.
+
+## Example
+
+`jolly_roger` has a CLI entry point that can be called as:
+
+```
+jolly_flagger scienceData.EMU_1141-55.SB47138.EMU_1141-55.beam00_averaged_cal.leakage.ms --min-horizon-limit-deg '-2' --max-horizon-limit-deg 30 --min-scale-deg 0.075
+```
+
+Here we are flagging visibilities that correspond to instances where:
+- the Sun has an elevation between -2 and 30 degrees, and
+- they are sensitive to angular scales between 0.075 and 1.0 segrees.

jolly_roger-0.0.2.dist-info/RECORD

@@ -0,0 +1,14 @@
+jolly_roger/__init__.py,sha256=7xiZLdeY-7sgrYGQ1gNdCjgCfqnoPXK7AeaHncY_DGU,204
+jolly_roger/_version.py,sha256=wO7XWlZte1hxA4mMvRc6zhNdGm74Nhhn2bfWRAxaKbI,511
+jolly_roger/_version.pyi,sha256=j5kbzfm6lOn8BzASXWjGIA1yT0OlHTWqlbyZ8Si_o0E,118
+jolly_roger/baselines.py,sha256=C_vC3v_ciU2T_si31oS0hUmsMNTQA0USxrm4118vYvY,4615
+jolly_roger/flagger.py,sha256=tlC-M_MpLpqOvkF544zw2EvOUpbSpasO2zlMlXMcxSs,3034
+jolly_roger/hour_angles.py,sha256=ChWTy69dkRN0R2HWEknHagv6W3xTXuSJJn9sAqBABCc,6160
+jolly_roger/logging.py,sha256=04YVHnF_8tKDkXNtXQ-iMyJ2BLV-qowbPAqqMFDxYE4,1338
+jolly_roger/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+jolly_roger/uvws.py,sha256=8G2E7bq8y5EEc2wQW5nli1WKsebZbBEHN8fhPzlinWk,10558
+jolly_roger-0.0.2.dist-info/METADATA,sha256=BtHEC57mNeu12PI6_pnDSkD8i767av0kQfTr_vINWuI,4172
+jolly_roger-0.0.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+jolly_roger-0.0.2.dist-info/entry_points.txt,sha256=ZwEZAe4DBn5nznVI0tP0a1wUinYouwXxxcZP6p7Pkvk,58
+jolly_roger-0.0.2.dist-info/licenses/LICENSE,sha256=7G-TthaPSOehr-pdj4TJydXj3eIUmerMbCUSatMr8hc,1522
+jolly_roger-0.0.2.dist-info/RECORD,,

jolly_roger-0.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

jolly_roger-0.0.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+jolly_flagger = jolly_roger.flagger:cli

jolly_roger-0.0.2.dist-info/licenses/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Alec Thomson.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the vector package developers nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.