gwava 0.0.1__py3-none-any.whl

gwava-0.0.1.dist-info/METADATA

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: gwava
+Version: 0.0.1
+Summary: Graviational Wave data plotter
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: matplotlib>=3.11.0
+Requires-Dist: numpy>=2.5
+Requires-Dist: pandas>=3.0.3
+Requires-Dist: PyYAML>=6.0.3
+Requires-Dist: requests>=2.34.2

gwava-0.0.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+gwosc_tools/__init__.py,sha256=jxAZnJKyyN-6y76tl4N9GW5PNOG9xrTgZtuKPyZtYMc,1397
+gwosc_tools/__main__.py,sha256=cVZdpy5q2nBuQhynGmVMJCv0EsCkWGy4k4MkFKUNXgg,86
+gwosc_tools/api.py,sha256=g_keMmZ0elnUJF0bVBiOtM15zR339m4HSJ1YHrQkHTU,2142
+gwosc_tools/cli.py,sha256=Bd8rgA0h6qJy6nGyf6QnLntbJyDRJedPUHVSHxQ01T4,2125
+gwosc_tools/config.py,sha256=oYVB-Zykkk72-ODLxPQp0GL-lv-8mcgQTvYP3vjaPkM,1140
+gwosc_tools/events.py,sha256=RA-8XCsc_2zzi_7gPWvNfyjvhkaHIneVTK2ZFhCQCZE,2373
+gwosc_tools/plotting.py,sha256=2r0rtu_aJK8gZMgHTvzGQhmySoKGCIAPfzPB8Bln5qg,3601
+gwosc_tools/sorting.py,sha256=8yCoXh_pqUFHBDC-MANmVLVXMMuAUzVy4nWemE_CVhE,6506
+gwava-0.0.1.dist-info/METADATA,sha256=d473QbfKNR8OdkdfhPideyO6sMPl0joKNLizPRc-nho,303
+gwava-0.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+gwava-0.0.1.dist-info/top_level.txt,sha256=dqEd17ggbsBSTRIG6Yx7LI4iI3DOiG4dn1F05E6OzVw,12
+gwava-0.0.1.dist-info/RECORD,,

gwava-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gwava-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+gwosc_tools

gwosc_tools/__init__.py

@@ -0,0 +1,50 @@
+"""Utilities for loading GWOSC metadata, querying events, and plotting masses.
+
+The public functions are imported lazily so that YAML and API helpers can be
+used without importing the heavier data-analysis and plotting dependencies.
+"""
+
+from importlib import import_module
+from typing import Any
+
+__all__ = [
+    "event_to_row",
+    "events_to_dataframe",
+    "fetch_all",
+    "fetch_event_versions",
+    "fetch_events_dataframe",
+    "create_peaked_layout",
+    "create_valley_layout",
+    "get_yaml",
+    "load_config",
+    "plot_masses",
+    "SORT_MODES",
+    "sort_events",
+]
+
+_FUNCTION_MODULES = {
+    "event_to_row": ".events",
+    "events_to_dataframe": ".events",
+    "fetch_all": ".api",
+    "fetch_event_versions": ".api",
+    "fetch_events_dataframe": ".events",
+    "create_peaked_layout": ".sorting",
+    "create_valley_layout": ".sorting",
+    "get_yaml": ".config",
+    "load_config": ".config",
+    "plot_masses": ".plotting",
+    "SORT_MODES": ".sorting",
+    "sort_events": ".sorting",
+}
+
+
+def __getattr__(name: str) -> Any:
+    """Load public functions only when they are first requested."""
+    try:
+        module_name = _FUNCTION_MODULES[name]
+    except KeyError as error:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from error
+
+    value = getattr(import_module(module_name, __name__), name)
+    globals()[name] = value
+    return value

gwosc_tools/__main__.py

@@ -0,0 +1,5 @@
+"""Run ``python -m gwosc_tools``."""
+
+from .cli import main
+
+raise SystemExit(main())

gwosc_tools/api.py

@@ -0,0 +1,74 @@
+"""HTTP helpers for the GWOSC API."""
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+from urllib.parse import urljoin
+
+import requests
+
+BASE_URL = "https://gwosc.org"
+EVENT_VERSIONS_PATH = "/api/v2/event-versions"
+DEFAULT_RELEASES = (
+    "GWTC-1-confident",
+    "GWTC-2.1-confident",
+    "GWTC-3-confident",
+    "GWTC-4.1"
+)
+
+
+def fetch_all(
+    path: str,
+    params: Mapping[str, Any] | None = None,
+    *,
+    base_url: str = BASE_URL,
+    session: requests.Session | None = None,
+    timeout: float = 30,
+) -> list[dict[str, Any]]:
+    """Fetch every page from a paginated GWOSC endpoint."""
+    url = urljoin(f"{base_url.rstrip('/')}/", path.lstrip("/"))
+    rows: list[dict[str, Any]] = []
+    client = session or requests.Session()
+    request_params = dict(params) if params is not None else None
+
+    while url:
+        response = client.get(url, params=request_params, timeout=timeout)
+        response.raise_for_status()
+        data = response.json()
+
+        results = data.get("results")
+        if not isinstance(results, list):
+            raise ValueError("GWOSC response does not contain a 'results' list")
+
+        rows.extend(results)
+        next_url = data.get("next")
+        url = urljoin(f"{base_url.rstrip('/')}/", next_url) if next_url else ""
+
+        # The API's next-page URL already contains the query string.
+        request_params = None
+
+    return rows
+
+
+def fetch_event_versions(
+    releases: Sequence[str] = DEFAULT_RELEASES,
+    *,
+    include_default_parameters: bool = True,
+    last_version_only: bool = True,
+    page_size: int = 100,
+    session: requests.Session | None = None,
+    timeout: float = 30,
+) -> list[dict[str, Any]]:
+    """Fetch event versions from the selected GWOSC catalog releases."""
+    params = {
+        "format": "json",
+        "release": ",".join(releases),
+        "lastver": str(last_version_only).lower(),
+        "include-default-parameters": str(include_default_parameters).lower(),
+        "pagesize": page_size,
+    }
+    return fetch_all(
+        EVENT_VERSIONS_PATH,
+        params,
+        session=session,
+        timeout=timeout,
+    )

gwosc_tools/cli.py

@@ -0,0 +1,72 @@
+"""Command-line interface for inspecting the YAML spec and plotting events."""
+
+import argparse
+from collections.abc import Sequence
+from pathlib import Path
+
+from .config import load_config
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Create the command-line argument parser."""
+    parser = argparse.ArgumentParser(
+        description="Load the GWOSC YAML specification and optionally plot event masses."
+    )
+    parser.add_argument("yaml_path", type=Path, help="Path to the YAML specification")
+    parser.add_argument(
+        "--plot-masses",
+        action="store_true",
+        help="Fetch GWOSC events and display the stellar-mass plot",
+    )
+    parser.add_argument(
+        "--save",
+        type=Path,
+        metavar="IMAGE_PATH",
+        help="Save the mass plot to this path",
+    )
+    parser.add_argument(
+        "--no-show",
+        action="store_true",
+        help="Do not open the plot window (useful together with --save)",
+    )
+
+    parser.add_argument(
+        '--sort',
+        default='date',
+        choices=[
+            'date', 
+            'peaked', 
+            'valley'],
+    )
+    return parser
+
+
+def run_argument(argv: Sequence[str] | None = None) -> int:
+    """Run the command-line application."""
+    args = build_parser().parse_args(argv)
+    config = load_config(args.yaml_path)
+
+    info = config.get("info", {})
+    print(f"Loaded YAML: {args.yaml_path}")
+    print(f"API title: {info.get('title', 'unknown')}")
+    print(f"API version: {info.get('version', 'unknown')}")
+    print(f"Documented paths: {len(config.get('paths', {}))}")
+
+    if args.plot_masses or args.save:
+        from .events import fetch_events_dataframe
+        from .plotting import plot_masses
+
+        dataframe = fetch_events_dataframe()
+        figure, _ = plot_masses(dataframe, show=not args.no_show)
+
+        if args.save:
+            args.save.parent.mkdir(parents=True, exist_ok=True)
+            figure.savefig(args.save, dpi=200, bbox_inches="tight")
+            print(f"Saved plot: {args.save}")
+
+    return 0
+
+
+def main() -> int:
+    """CLI entry point."""
+    return run_argument()

gwosc_tools/config.py

@@ -0,0 +1,45 @@
+"""Functions for reading YAML configuration and specification files."""
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def load_config(yaml_path: str | Path) -> dict[str, Any]:
+    """Load a YAML file and return its top-level mapping.
+
+    Parameters
+    ----------
+    yaml_path:
+        Path to the YAML file.
+
+    Raises
+    ------
+    FileNotFoundError
+        If ``yaml_path`` does not exist.
+    ValueError
+        If the YAML document does not contain a mapping at its top level.
+    """
+    path = Path(yaml_path).expanduser()
+
+    if not path.is_file():
+        raise FileNotFoundError(f"YAML file not found: {path}")
+
+    with path.open("r", encoding="utf-8") as file:
+        config = yaml.safe_load(file)
+
+    if config is None:
+        return {}
+    if not isinstance(config, dict):
+        raise ValueError(f"Expected a YAML mapping in {path}, got {type(config).__name__}")
+
+    return config
+
+
+def get_yaml(yaml_path: str | Path) -> dict[str, Any]:
+    """Return the parsed contents of a YAML file.
+
+    This name is kept for compatibility with the original script.
+    """
+    return load_config(yaml_path)

gwosc_tools/events.py

@@ -0,0 +1,76 @@
+"""Transform GWOSC event responses into analysis-ready tables."""
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+import pandas as pd
+import requests
+
+from .api import DEFAULT_RELEASES, fetch_event_versions
+
+
+def event_to_row(event: Mapping[str, Any]) -> dict[str, Any]:
+    """Flatten one GWOSC event and its default parameters into one row."""
+    detectors = event.get("detectors") or []
+    row = {
+        "name": event.get("name"),
+        "shortName": event.get("shortName"),
+        "gps": event.get("gps"),
+        "version": event.get("version"),
+        "catalog": event.get("catalog"),
+        "detectors": ",".join(detectors),
+        "detail_url": event.get("detail_url"),
+    }
+
+    for parameter in event.get("default_parameters") or []:
+        name = parameter.get("name")
+        if not name:
+            continue
+
+        row[name] = parameter.get("best")
+        row[f"{name}_upper_error"] = parameter.get("upper_error")
+        row[f"{name}_lower_error"] = parameter.get("lower_error")
+        row[f"{name}_unit"] = parameter.get("unit")
+
+    return row
+
+
+def events_to_dataframe(
+    events: Sequence[Mapping[str, Any]],
+    *,
+    require_component_masses: bool = True,
+    sort_by_gps: bool = True,
+) -> pd.DataFrame:
+    """Convert GWOSC events into a flattened pandas DataFrame."""
+    dataframe = pd.DataFrame(event_to_row(event) for event in events)
+
+    if dataframe.empty:
+        return dataframe
+
+    if require_component_masses:
+        required_columns = {"mass_1_source", "mass_2_source"}
+        missing = required_columns.difference(dataframe.columns)
+        if missing:
+            names = ", ".join(sorted(missing))
+            raise ValueError(f"Event data is missing required mass columns: {names}")
+        dataframe = dataframe.dropna(subset=sorted(required_columns))
+
+    if sort_by_gps and "gps" in dataframe.columns:
+        dataframe = dataframe.sort_values("gps")
+
+    return dataframe.reset_index(drop=True)
+
+
+def fetch_events_dataframe(
+    releases: Sequence[str] = DEFAULT_RELEASES,
+    *,
+    session: requests.Session | None = None,
+    timeout: float = 30,
+) -> pd.DataFrame:
+    """Fetch GWOSC events and return an analysis-ready DataFrame."""
+    events = fetch_event_versions(
+        releases,
+        session=session,
+        timeout=timeout,
+    )
+    return events_to_dataframe(events)

gwosc_tools/plotting.py

@@ -0,0 +1,135 @@
+"""Visualizations for GWOSC event data."""
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+from matplotlib.lines import Line2D
+
+
+def plot_masses(
+    dataframe: pd.DataFrame,
+    *,
+    show: bool = True,
+) -> tuple[Figure, Axes]:
+    """Plot component and final masses for GWOSC compact-object mergers."""
+    required_columns = {"mass_1_source", "mass_2_source"}
+    missing = required_columns.difference(dataframe.columns)
+    if missing:
+        names = ", ".join(sorted(missing))
+        raise ValueError(f"DataFrame is missing required columns: {names}")
+    if dataframe.empty:
+        raise ValueError("Cannot plot an empty DataFrame")
+
+    blue = "#00a9e0"
+    orange = "#d9901a"
+    gray = "#8a8a8a"
+
+    figure, axis = plt.subplots(figsize=(13, 7), facecolor="black")
+    axis.set_facecolor("black")
+
+    for position, (_, row) in enumerate(dataframe.iterrows()):
+        mass_1 = float(row["mass_1_source"])
+        mass_2 = float(row["mass_2_source"])
+        final_mass = row.get("final_mass_source", np.nan)
+
+        mass_1_color = orange if mass_1 < 3 else blue
+        mass_2_color = orange if mass_2 < 3 else blue
+
+        if pd.notna(final_mass):
+            final_mass = float(final_mass)
+            axis.plot(
+                [position, position],
+                [min(mass_1, mass_2), final_mass],
+                color=gray,
+                alpha=0.65,
+                linewidth=1.2,
+            )
+            axis.scatter(
+                position,
+                final_mass,
+                color=blue,
+                s=90,
+                edgecolor="black",
+                linewidth=0.4,
+                zorder=4,
+            )
+
+        axis.scatter(
+            position,
+            mass_1,
+            color=mass_1_color,
+            s=42,
+            edgecolor="black",
+            linewidth=0.4,
+            zorder=5,
+        )
+        axis.scatter(
+            position,
+            mass_2,
+            color=mass_2_color,
+            s=42,
+            edgecolor="black",
+            linewidth=0.4,
+            zorder=5,
+        )
+
+    axis.set_yscale("log")
+    axis.set_ylim(1, 220)
+    axis.set_xlim(-1, len(dataframe))
+    axis.set_yticks([1, 2, 5, 10, 20, 50, 100, 200, 250])
+    axis.set_yticklabels(
+        ["1", "2", "5", "10", "20", "50", "100", "200", "250"],
+        color="gray",
+    )
+    axis.set_xticks([])
+    axis.set_ylabel("Solar Masses", color="gray", fontsize=14)
+    axis.set_title(
+        "Masses in the Stellar Graveyard",
+        color="white",
+        fontsize=30,
+        pad=22,
+    )
+    axis.grid(axis="y", color="white", alpha=0.18, linewidth=1)
+
+    for spine in axis.spines.values():
+        spine.set_visible(False)
+
+    legend_items = [
+        Line2D(
+            [0],
+            [0],
+            marker="o",
+            color="none",
+            label="LIGO-Virgo-KAGRA Black Holes",
+            markerfacecolor=blue,
+            markersize=9,
+        ),
+        Line2D(
+            [0],
+            [0],
+            marker="o",
+            color="none",
+            label="LIGO-Virgo-KAGRA Neutron Stars",
+            markerfacecolor=orange,
+            markersize=9,
+        ),
+    ]
+    legend = axis.legend(
+        handles=legend_items,
+        loc="upper center",
+        bbox_to_anchor=(0.5, 1.02),
+        ncol=2,
+        frameon=False,
+    )
+
+    for text, color in zip(legend.get_texts(), [blue, orange]):
+        text.set_color(color)
+
+    figure.tight_layout()
+
+    if show:
+        plt.show()
+
+    return figure, axis

gwosc_tools/sorting.py

@@ -0,0 +1,215 @@
+"""Reusable event-ordering functions for GWOSC visualizations.
+
+Sorting is kept separate from plotting so the same ordering can be used by a
+static figure, an interactive widget, or a future web application.
+"""
+
+from typing import Literal
+
+import pandas as pd
+
+SortMode = Literal[
+    "rising",
+    "falling",
+    "peaked",
+    "valley",
+    "random",
+    "date",
+    "distance",
+    "chirp_mass",
+    "chi_eff",
+    "snr",
+]
+
+SORT_MODES: tuple[SortMode, ...] = (
+    "rising",
+    "falling",
+    "peaked",
+    "valley",
+    "random",
+    "date",
+    "distance",
+    "chirp_mass",
+    "chi_eff",
+    "snr",
+)
+
+_COLUMN_BY_MODE = {
+    "date": "gps",
+    "distance": "luminosity_distance",
+    "chirp_mass": "chirp_mass_source",
+    "chi_eff": "chi_eff",
+    "snr": "network_matched_filter_snr",
+}
+
+
+def _normalize_mode(mode: str) -> str:
+    """Normalize user-facing spellings such as ``chirp-mass``."""
+    normalized = mode.strip().lower().replace("-", "_").replace(" ", "_")
+    if normalized not in SORT_MODES:
+        choices = ", ".join(SORT_MODES)
+        raise ValueError(f"Unknown sort mode {mode!r}. Choose one of: {choices}")
+    return normalized
+
+
+def _numeric_column(dataframe: pd.DataFrame, column: str) -> pd.Series:
+    """Return one column as numeric values with invalid entries set to NaN."""
+    if column not in dataframe.columns:
+        raise ValueError(f"Sort mode requires the DataFrame column {column!r}")
+    return pd.to_numeric(dataframe[column], errors="coerce")
+
+
+def _sorting_mass(dataframe: pd.DataFrame) -> pd.Series:
+    """Build the preferred mass used by the visual layout modes.
+
+    The value is selected in this order:
+
+    1. ``final_mass_source``
+    2. ``total_mass_source``
+    3. ``mass_1_source + mass_2_source``
+    """
+    candidates: list[pd.Series] = []
+
+    for column in ("final_mass_source", "total_mass_source"):
+        if column in dataframe.columns:
+            candidates.append(pd.to_numeric(dataframe[column], errors="coerce"))
+
+    component_columns = {"mass_1_source", "mass_2_source"}
+    if component_columns.issubset(dataframe.columns):
+        component_total = (
+            pd.to_numeric(dataframe["mass_1_source"], errors="coerce")
+            + pd.to_numeric(dataframe["mass_2_source"], errors="coerce")
+        )
+        candidates.append(component_total)
+
+    if not candidates:
+        raise ValueError(
+            "Mass sorting requires final_mass_source, total_mass_source, "
+            "or both component-mass columns"
+        )
+
+    values = candidates[0].astype(float)
+    for fallback in candidates[1:]:
+        values = values.where(values.notna(), fallback)
+
+    return values
+
+
+def _linear_order(values: pd.Series, *, ascending: bool) -> list[int]:
+    """Return stable row positions, always placing missing values last."""
+    return values.sort_values(
+        ascending=ascending,
+        na_position="last",
+        kind="stable",
+    ).index.tolist()
+
+
+def _center_weighted_order(
+    values: pd.Series,
+    *,
+    largest_at_center: bool,
+) -> list[int]:
+    """Arrange extrema at the center and the opposite values at the edges."""
+    valid = values[values.notna()]
+    missing_positions = values[values.isna()].index.tolist()
+    sorted_positions = valid.sort_values(
+        ascending=largest_at_center,
+        kind="stable",
+    ).index.tolist()
+
+    # Alternating values between the left and right edges creates a symmetric
+    # peak or valley without changing any event values.
+    arranged = sorted_positions[::2] + sorted_positions[1::2][::-1]
+    return arranged + missing_positions
+
+
+def create_peaked_layout(dataframe: pd.DataFrame) -> pd.DataFrame:
+    """Return a copy with low masses at the edges and high masses at center.
+
+    The mass used for ordering follows the standard fallback sequence:
+    ``final_mass_source``, then ``total_mass_source``, then the sum of
+    ``mass_1_source`` and ``mass_2_source``.
+    """
+    working = dataframe.copy(deep=True).reset_index(drop=True)
+
+    if working.empty:
+        return working
+
+    positions = _center_weighted_order(
+        _sorting_mass(working),
+        largest_at_center=True,
+    )
+    return working.iloc[positions].reset_index(drop=True)
+
+
+def create_valley_layout(dataframe: pd.DataFrame) -> pd.DataFrame:
+    """Return a copy with high masses at the edges and low masses at center.
+
+    The mass used for ordering follows the standard fallback sequence:
+    ``final_mass_source``, then ``total_mass_source``, then the sum of
+    ``mass_1_source`` and ``mass_2_source``.
+    """
+    working = dataframe.copy(deep=True).reset_index(drop=True)
+
+    if working.empty:
+        return working
+
+    positions = _center_weighted_order(
+        _sorting_mass(working),
+        largest_at_center=False,
+    )
+    return working.iloc[positions].reset_index(drop=True)
+
+
+def sort_events(
+    dataframe: pd.DataFrame,
+    mode: str = "date",
+    *,
+    random_seed: int | None = 42,
+) -> pd.DataFrame:
+    """Return a reordered copy of a GWOSC event DataFrame.
+
+    Parameters
+    ----------
+    dataframe:
+        Event table to reorder. The input is never modified.
+    mode:
+        One of :data:`SORT_MODES`. Hyphens and spaces are accepted in names,
+        so ``"chirp-mass"`` and ``"chirp mass"`` both select
+        ``"chirp_mass"``.
+    random_seed:
+        Seed for reproducible random ordering. Use ``None`` for a different
+        random ordering each time.
+
+    Notes
+    -----
+    ``rising``, ``falling``, ``peaked``, and ``valley`` use final mass when
+    available, then total mass, then the sum of the two component masses.
+    Missing sort values are kept and placed at the end.
+    """
+    normalized_mode = _normalize_mode(mode)
+
+    if normalized_mode == "peaked":
+        return create_peaked_layout(dataframe)
+    if normalized_mode == "valley":
+        return create_valley_layout(dataframe)
+
+    working = dataframe.copy(deep=True).reset_index(drop=True)
+
+    if working.empty:
+        return working
+
+    if normalized_mode == "random":
+        return working.sample(frac=1, random_state=random_seed).reset_index(drop=True)
+
+    if normalized_mode in {"rising", "falling"}:
+        values = _sorting_mass(working)
+    else:
+        values = _numeric_column(working, _COLUMN_BY_MODE[normalized_mode])
+
+    if normalized_mode == "falling":
+        positions = _linear_order(values, ascending=False)
+    else:
+        positions = _linear_order(values, ascending=True)
+
+    return working.iloc[positions].reset_index(drop=True)