radiapy 0.1.0__py3-none-any.whl

radiapy/__init__.py

@@ -0,0 +1,20 @@
+"""
+Radiapy — Interactive visualization of radiation experiments.
+
+Quick start::
+
+    from radiapy import RadViz
+
+    rv = RadViz("dataset_geiger.csv")
+    rv.generate_dashboard("dashboard.html")
+
+Or visualize a single plot::
+
+    fig = rv.plot_attenuation()
+    fig.show()
+"""
+
+from radiapy.core import RadViz
+
+__version__ = "0.1.0"
+__all__ = ["RadViz"]

radiapy/__main__.py

@@ -0,0 +1,82 @@
+"""Entry point for ``python -m radiapy CSV_FILE [options]``.
+
+Usage
+-----
+    python -m radiapy demo/dataset_geiger.csv
+    python -m radiapy demo/dataset_geiger.csv --output my_report.html
+    python -m radiapy demo/dataset_geiger.csv --report-only
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+
+def _parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        prog="python -m radiapy",
+        description="Radiapy — interactive radiation experiment visualizer",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+examples:
+  python -m radiapy demo/dataset_geiger.csv
+  python -m radiapy demo/dataset_geiger.csv --output report.html
+  python -m radiapy demo/dataset_geiger.csv --report-only
+        """,
+    )
+    p.add_argument("csv_file", metavar="CSV_FILE", help="Geiger-counter CSV dataset")
+    p.add_argument(
+        "--output", "-o",
+        default="dashboard.html",
+        metavar="FILE",
+        help="Output HTML dashboard path (default: dashboard.html)",
+    )
+    p.add_argument(
+        "--report-only",
+        action="store_true",
+        help="Print the physics report to stdout without generating HTML",
+    )
+    return p.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parse_args(argv)
+    csv_path = Path(args.csv_file)
+
+    if not csv_path.exists():
+        print(f"ERROR: file not found — {csv_path}", file=sys.stderr)
+        return 1
+
+    from radiapy.core import RadViz
+
+    print("=" * 60)
+    print("  Radiapy v0.1.0 — Radiation Experiment Visualizer")
+    print("=" * 60)
+
+    rv = RadViz(csv_path)
+
+    print(f"\nDataset loaded:  {csv_path}")
+    print(f"  Isotopes   : {', '.join(rv.dataset.isotopes)}")
+    print(f"  Distances  : {rv.dataset.distances} cm")
+    print(f"  Materials  : {', '.join(rv.dataset.materials)}")
+    print(f"  Total rows : {len(rv.dataset.raw)}")
+    print()
+
+    print(rv.physics_report())
+
+    if args.report_only:
+        return 0
+
+    out = rv.generate_dashboard(args.output)
+    size_kb = out.stat().st_size // 1024
+    print(f"\nDashboard saved : {out.resolve()}")
+    print(f"File size       : {size_kb} KB")
+    print(f"\nOpen in browser :")
+    print(f"  open {out}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

radiapy/cli.py

@@ -0,0 +1,70 @@
+"""Command-line interface for Radiapy."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from radiapy.core import RadViz
+
+
+@click.group()
+@click.version_option(package_name="radiapy")
+def main() -> None:
+    """Radiapy — radiation experiment visualizer."""
+
+
+@main.command()
+@click.argument("input", metavar="CSV_FILE", type=click.Path(exists=True, dir_okay=False))
+@click.option(
+    "--output", "-o",
+    default="dashboard.html",
+    show_default=True,
+    help="Path for the output HTML dashboard.",
+)
+def dashboard(input: str, output: str) -> None:
+    """Generate an interactive HTML dashboard from CSV_FILE."""
+    rv = RadViz(input)
+    path = rv.generate_dashboard(output)
+    click.echo(f"\nOpen in browser: {path.resolve()}")
+
+
+@main.command()
+@click.argument("input", metavar="CSV_FILE", type=click.Path(exists=True, dir_okay=False))
+def report(input: str) -> None:
+    """Print a physics report (fits, μ values, discrepancies) to stdout."""
+    rv = RadViz(input)
+    click.echo(rv.physics_report())
+
+
+@main.command()
+@click.option("--isotope", default="Am241", show_default=True, help="Isotope key.")
+@click.option("--material", default="Pb", show_default=True, help="Absorber material.")
+@click.option(
+    "--output", "-o",
+    default="particles.html",
+    show_default=True,
+    help="Output HTML file.",
+)
+def simulate(isotope: str, material: str, output: str) -> None:
+    """Export the animated particle simulation (no CSV required)."""
+    import plotly.io as pio
+    from radiapy.visualizers.particle_viz import plot_particles
+
+    click.echo(f"Simulating {isotope} through {material} …")
+    fig = plot_particles(isotope=isotope, material=material)
+    out = Path(output)
+    pio.write_html(fig, out, include_plotlyjs=True, full_html=True)
+    click.echo(f"Saved: {out.resolve()}")
+
+
+# Backward-compatible alias: `radviz --input FILE --output FILE`
+@click.command(name="radviz", hidden=True)
+@click.option("--input", "-i", required=True, type=click.Path(exists=True), help="Input CSV file.")
+@click.option("--output", "-o", default="dashboard.html", help="Output HTML path.")
+def radviz_legacy(input: str, output: str) -> None:
+    """Legacy single-command interface: radviz --input FILE --output FILE."""
+    rv = RadViz(input)
+    rv.generate_dashboard(output)

radiapy/core.py

@@ -0,0 +1,263 @@
+"""Core RadViz class: one-stop interface for parsing, physics, and visualization."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import plotly.graph_objects as go
+
+from radiapy.parsers.base_parser import ParsedDataset
+from radiapy.parsers.csv_parser import CSVParser
+from radiapy.physics import (
+    fit_inverse_square,
+    fit_attenuation,
+    transmission_from_ratio_stats,
+)
+from radiapy.physics.nist_data import (
+    MU_LINEAR,
+    FILTER_THICKNESS_CM,
+    expected_transmission,
+    ISOTOPE_DESCRIPTION,
+)
+from radiapy.visualizers.attenuation_viz import plot_attenuation, plot_attenuation_spectrum
+from radiapy.visualizers.distance_viz import plot_inverse_square, plot_inverse_square_normalized
+from radiapy.visualizers.comparison_viz import plot_comparison, plot_heatmap, plot_mu_comparison
+from radiapy.visualizers.particle_viz import plot_particles
+from radiapy.exporters.html_exporter import export_dashboard
+
+
+class RadViz:
+    """Main Radiapy interface.
+
+    Load an experimental CSV, compute physics fits, and generate interactive
+    Plotly visualizations or a standalone HTML dashboard.
+
+    Parameters
+    ----------
+    csv_path : str or Path
+        Path to the Geiger-counter experiment CSV file.
+    schema : dict, optional
+        Column mapping for non-standard CSV files. See ``CSVParser.DEFAULT_SCHEMA``.
+
+    Examples
+    --------
+    >>> from radiapy import RadViz
+    >>> rv = RadViz("radviz/demo/dataset_geiger.csv")
+    >>> rv.generate_dashboard("dashboard.html")
+    """
+
+    def __init__(self, csv_path: str | Path, schema: dict | None = None) -> None:
+        self.csv_path = Path(csv_path)
+        self.dataset: ParsedDataset = CSVParser(self.csv_path, schema).parse()
+        self._fits: dict[str, Any] = {}
+        self._compute_fits()
+
+    # ------------------------------------------------------------------ #
+    # Physics
+    # ------------------------------------------------------------------ #
+
+    def _compute_fits(self) -> None:
+        """Run all physics fits and cache results."""
+        ds = self.dataset
+
+        # Inverse-square fits per isotope
+        for iso in ds.isotopes:
+            gs_list = sorted(
+                [gs for gs in ds.group_stats if gs.isotope == iso],
+                key=lambda g: g.distance_cm,
+            )
+            if len(gs_list) < 2:
+                continue
+            distances = np.array([g.distance_cm for g in gs_list])
+            counts = np.array([g.counts_free_mean for g in gs_list])
+            sems = np.array([g.counts_free_sem for g in gs_list])
+            self._fits[f"isq_{iso}"] = fit_inverse_square(distances, counts, sems, isotope=iso)
+
+        # Attenuation fits: we back-calculate μ per (isotope, material) from T_mean
+        for iso in ds.isotopes:
+            for mat in ds.materials:
+                x = FILTER_THICKNESS_CM.get(mat)
+                mu_nist = MU_LINEAR.get(iso, {}).get(mat)
+                if x is None or mu_nist is None:
+                    continue
+                # Use all distances: collect (x_eff, counts_filtered, counts_free)
+                thicknesses, counts_filt, counts_free, sems = [], [], [], []
+                for gs in ds.group_stats:
+                    if gs.isotope != iso:
+                        continue
+                    T = gs.transmission.get(mat)
+                    T_sem = gs.transmission_sem.get(mat, 0.0)
+                    I0 = gs.counts_free_mean
+                    if T is not None and I0 > 0:
+                        thicknesses.append(x)
+                        counts_filt.append(T * I0)
+                        counts_free.append(I0)
+                        sems.append(T_sem * I0 if T_sem else None)
+
+                if len(thicknesses) >= 1:
+                    self._fits[f"att_{iso}_{mat}"] = fit_attenuation(
+                        np.array(thicknesses, dtype=float),
+                        np.array(counts_filt, dtype=float),
+                        I0_estimate=float(np.mean(counts_free)),
+                        mu_nist=mu_nist,
+                        material=mat,
+                        isotope=iso,
+                        sigma=None,
+                    )
+
+    def physics_report(self) -> str:
+        """Return a human-readable text summary of all physics fits."""
+        lines = ["=" * 70, "Radiapy Physics Report", "=" * 70, ""]
+
+        lines.append("--- Inverse-Square Law Fits ---")
+        for iso in self.dataset.isotopes:
+            key = f"isq_{iso}"
+            if key in self._fits:
+                lines.append(f"  {self._fits[key].summary()}")
+        lines.append("")
+
+        lines.append("--- Attenuation Fits vs NIST ---")
+        for iso in self.dataset.isotopes:
+            for mat in self.dataset.materials:
+                key = f"att_{iso}_{mat}"
+                if key in self._fits:
+                    lines.append(f"  {self._fits[key].summary()}")
+        lines.append("")
+
+        lines.append("--- Expected Transmissions (NIST Beer-Lambert) ---")
+        for iso in self.dataset.isotopes:
+            for mat in self.dataset.materials:
+                t = expected_transmission(iso, mat)
+                mu = MU_LINEAR.get(iso, {}).get(mat, float("nan"))
+                x = FILTER_THICKNESS_CM.get(mat, float("nan"))
+                lines.append(
+                    f"  {iso}/{mat}: T_NIST = {t:.4f}  (μ = {mu:.3f} cm⁻¹, x = {x} cm)"
+                )
+
+        return "\n".join(lines)
+
+    # ------------------------------------------------------------------ #
+    # Individual visualizations
+    # ------------------------------------------------------------------ #
+
+    def plot_attenuation(
+        self,
+        isotope: str | None = None,
+        distance_cm: float | None = None,
+        show_nist: bool = True,
+    ) -> go.Figure:
+        """Grouped bar chart of experimental transmission per material.
+
+        Parameters
+        ----------
+        isotope     : Restrict to one isotope. None → all (side-by-side).
+        distance_cm : Restrict to one distance. None → average over all.
+        show_nist   : Draw Beer-Lambert reference lines.
+        """
+        return plot_attenuation(self.dataset, isotope=isotope, distance_cm=distance_cm, show_nist=show_nist)
+
+    def plot_attenuation_spectrum(self, materials: list[str] | None = None) -> go.Figure:
+        """NIST μ/ρ vs energy for Al, Cu, Pb (shows Pb K-edge)."""
+        return plot_attenuation_spectrum(materials)
+
+    def plot_inverse_square(self, isotope: str | None = None) -> go.Figure:
+        """Counts vs distance scatter with 1/r² fit overlay."""
+        return plot_inverse_square(self.dataset, isotope=isotope)
+
+    def plot_inverse_square_normalized(self) -> go.Figure:
+        """Counts × r² vs distance — flat → confirms inverse-square law."""
+        return plot_inverse_square_normalized(self.dataset)
+
+    def plot_heatmap(self) -> go.Figure:
+        """2-D heatmap of transmission: rows = material, columns = (isotope, distance)."""
+        return plot_heatmap(self.dataset)
+
+    def plot_mu_comparison(self) -> go.Figure:
+        """Bar chart of experimental vs NIST μ with discrepancy %."""
+        return plot_mu_comparison(self.dataset)
+
+    def plot_comparison(self, distance_cm: float | None = None) -> go.Figure:
+        """Cd109 vs Am241 overlay for each material."""
+        return plot_comparison(self.dataset, distance_cm=distance_cm)
+
+    def plot_particles(
+        self,
+        isotope: str = "Am241",
+        material: str = "Pb",
+        thickness_levels: list[float] | None = None,
+    ) -> go.Figure:
+        """Animated photon simulation with absorber-thickness slider.
+
+        Parameters
+        ----------
+        isotope          : Source isotope.
+        material         : Absorber material.
+        thickness_levels : List of thicknesses (cm) for the slider.
+        """
+        return plot_particles(isotope=isotope, material=material, thickness_levels=thickness_levels)
+
+    # ------------------------------------------------------------------ #
+    # Dashboard
+    # ------------------------------------------------------------------ #
+
+    def generate_dashboard(self, output_path: str | Path = "dashboard.html") -> Path:
+        """Build and export a full interactive HTML dashboard.
+
+        Parameters
+        ----------
+        output_path : Destination HTML file path.
+
+        Returns
+        -------
+        Path to the generated file.
+        """
+        output_path = Path(output_path)
+        print(f"Building Radiapy dashboard → {output_path} …")
+
+        figures: dict = {}
+
+        print("  [1/8] Attenuation bar charts …")
+        figures["attenuation"] = self.plot_attenuation()
+
+        print("  [2/8] NIST μ/ρ spectrum …")
+        figures["spectrum"] = self.plot_attenuation_spectrum()
+
+        print("  [3/8] Inverse-square law …")
+        figures["distance"] = self.plot_inverse_square()
+
+        print("  [4/8] 1/r² diagnostic …")
+        figures["distance_norm"] = self.plot_inverse_square_normalized()
+
+        print("  [5/8] Transmission heatmap …")
+        figures["heatmap"] = self.plot_heatmap()
+
+        print("  [6/8] μ comparison …")
+        figures["mu_compare"] = self.plot_mu_comparison()
+
+        print("  [7/8] Multi-isotope comparison …")
+        figures["comparison"] = self.plot_comparison()
+
+        print("  [8/8] Particle animation …")
+        figures["particles"] = self.plot_particles()
+
+        # Summary stats for header cards
+        n_rows = len(self.dataset.raw)
+        n_isotopes = len(self.dataset.isotopes)
+        n_distances = len(self.dataset.distances)
+        n_materials = len(self.dataset.materials)
+        n_replicates = n_rows // (n_isotopes * n_distances) if n_isotopes * n_distances else 0
+
+        dataset_summary = {
+            "isotopes": (n_isotopes, "Isotopes"),
+            "distances": (n_distances, "Distances"),
+            "materials": (n_materials, "Materials"),
+            "replicates": (n_replicates, "Replicates / condition"),
+            "rows": (n_rows, "Total measurements"),
+        }
+
+        path = export_dashboard(figures, output_path, dataset_summary=dataset_summary)
+        size_kb = path.stat().st_size // 1024
+        print(f"\nDashboard generated: {path}  ({size_kb} KB)")
+        return path

radiapy/exporters/__init__.py

@@ -0,0 +1,5 @@
+"""Exporters sub-package."""
+
+from radiapy.exporters.html_exporter import export_dashboard
+
+__all__ = ["export_dashboard"]