snr

Author: rinriko

README.md

@@ -1,36 +1,105 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# Interactive Light-Curve Visualization and Analysis Tool
 
-## Getting Started
+## Overview
 
-First, run the development server:
+This program is an interactive, web-based visualization system designed for exploratory analysis of **time-resolved astronomical light-curve data**, with a particular focus on **ZTF J1539 PSF surface-brightness measurements** used in **JWST precision timing studies**. The application enables users to seamlessly switch between **raw observational data** and **statistically averaged representations**, while preserving a direct link between aggregated points and their underlying measurements.
 
-```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
-```
+## Core Functionality
+
+The system renders **dual-panel light curves** using Plotly, displaying **short-wavelength (SW)** and **long-wavelength (LW)** surface brightness measurements simultaneously. Users can:
+
+- Select different data representations (**raw**, **averaged**, or **combined**)
+- Configure binning parameters
+- Choose among multiple x-axis domains:
+  - Phase
+  - MJD
+  - Absolute time
+  - Derived temporal units (days, hours, minutes, seconds)
+
+A central design goal of the tool is **traceability**: every averaged data point retains a mapping to the raw points that contributed to it. This mapping allows users to drill down from a statistical summary to the exact measurements used to compute it.
+
+## Interactive Exploration
+
+The program supports rich, event-driven interaction:
+
+- Clicking an **averaged point** dynamically opens a floating panel displaying all associated raw data points.
+- The raw-data panel is **draggable and resizable**, allowing side-by-side comparison with the main light curve.
+- The raw view overlays the **mean value and uncertainty bands**, enabling visual assessment of scatter and outliers.
+- Users can interactively switch the **raw-data x-axis** (e.g., phase → time → seconds) without recomputing the data.
+
+Hover interactions provide **context-aware tooltips**, showing metadata such as epoch, radial bounds, phase, MJD, and measurement uncertainty, ensuring that scientific context is always available.
+
+## Raw-Data Filtering and Quality Control
+
+To support data-quality assessment, the program includes configurable **raw-point filtering mechanisms**:
+
+- **Percent-based filtering**, which keeps points within a user-defined percentage of the average
+- **Sigma-band filtering**, which selects points within a specified standard-deviation range
+
+Filters can be applied **inside or outside** the selected band, and the accepted range is visually highlighted directly on the plot. Filtered results update both the displayed raw points and the corresponding averaged annotations, enabling rapid sensitivity testing of binning and filtering assumptions.
+
+## Image-Linked Annotations
+
+For datasets with associated observational images, the tool allows users to:
+
+- Click individual raw or averaged points to **attach annotated thumbnails**
+- Maintain a synchronized collection of selected images below the plot
+- Open high-resolution images in a modal view alongside contextual numerical values extracted from the plotted data
+
+This tightly integrates **numerical trends and image-level evidence**, supporting visual validation of astrophysical features or anomalies.
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+## Architecture and Design
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+The system is implemented as a **client-side React / Next.js application**, leveraging:
 
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+- **React Plotly.js** for high-performance interactive plotting
+- A centralized **PlotSettings context** for consistent global state management
+- Modular utilities for trace construction, filtering, and annotation generation
+- Dynamic imports to ensure compatibility with server-side rendering constraints
 
-## Learn More
+The architecture cleanly separates **data processing**, **visual styling**, and **interaction logic**, making the tool extensible to additional targets, wavelength bands, or survey datasets.
 
-To learn more about Next.js, take a look at the following resources:
+## Intended Use
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+This program is intended for astronomers and data analysts who require:
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+- Transparent linkage between averaged results and raw observations
+- Interactive validation of binning, filtering, and uncertainty modeling
+- High-precision timing and variability studies using JWST-related datasets
 
-## Deploy on Vercel
+By combining statistical aggregation with direct access to raw measurements and imagery, the tool bridges the gap between **quantitative analysis** and **visual inspection**, enabling more robust scientific interpretation.
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+## Installation and Getting Started
+
+### Prerequisites
+
+Before installing the project, ensure you have the following installed:
+
+- **Node.js** (version 18 or later recommended)
+- **npm**, **yarn**, or **pnpm** (npm is used in the examples below)
+- A modern web browser (Chrome, Firefox, Edge)
+
+### Installation
+
+1. **Clone the repository**
+
+```bash
+git clone https://github.com/your-org/your-repo-name.git
+cd your-repo-name
+```
+
+2. **Install dependencies**
+```bash
+npm install
+```
+
+3. **Build**
+```bash
+npm run build
+```
+
+4. **Start**
+```bash
+npm run start
+```

src/app/page.tsx

@@ -1,6 +1,17 @@
+'use client';
 import LightCurvePlot from '@/components/LightCurvePlot';
+import { usePlotSettings } from '@/context/PlotSettingsContext';
+import { useEffect } from 'react';
 
 export default function HomePage() {
+
+  const {
+    setSettings
+  } = usePlotSettings();
+  useEffect(() => {
+    setSettings({ dataType: [] })
+  }
+    , []);
   return (
     <main className="min-h-full bg-gray-50 overflow-auto">
       <LightCurvePlot />

src/app/snr/page.tsx

@@ -0,0 +1,21 @@
+'use client';
+import LightCurvePlot from '@/components/LightCurvePlot';
+import { usePlotSettings } from '@/context/PlotSettingsContext';
+import { useEffect } from 'react';
+
+export default function SNR() {
+  const {
+    setSettings
+  } = usePlotSettings();
+  useEffect(() => {
+    setSettings({ dataType: ['snr'] })
+  }
+    , []);
+
+
+  return (
+    <main className="min-h-full bg-gray-50 overflow-auto">
+      <LightCurvePlot />
+    </main>
+  );
+}

src/components/LightCurvePlot.tsx

@@ -498,7 +498,7 @@ function applyRawFilter(
       });
 
     }
-  }, [avgPointRawMap, dataSelection, rawFigure, filterPercent, sigmaK, rawFilterMode, xAxis]);
+  }, [avgPointRawMap, dataSelection, rawFigure, filterPercent, sigmaK, rawFilterMode, xAxis, isRawFilterInside]);
 
 
   useEffect(() => {
@@ -822,35 +822,6 @@ function applyRawFilter(
       handleOriginalPointClick(figure, pt);
     }
   }, [dataType, avgPointRawMap, figure, selectedImages]);
-  // const handlePointClick = useCallback((e: Plotly.PlotMouseEvent) => {
-  //   const pt = e.points[0];
-  //   if (!figure) return;
-
-  //   const hasAverage = dataType.includes('average');
-  //   const hasRaw = dataType.includes('raw');
-  //   const hasBoth = hasAverage && hasRaw;
-
-  //   const dataMode = ((pt.customdata as unknown) as AveragePointCustomData)?.dataMode;
-
-  //   // BLOCK average clicks when both raw+average selected
-  //   if (hasBoth && dataMode === 'average') {
-  //     console.log("Average click blocked because raw+avg selected");
-  //     return;
-  //   }
-
-  //   // normal logic
-  //   if (dataMode === '') {
-  //     if (dataType.includes('average')) {
-  //       handleAveragePointClick(figure, pt);
-  //     } else {
-  //       handleOriginalPointClick(figure, pt);
-  //     }
-  //   } else if (dataMode === 'average') {
-  //     handleAveragePointClick(figure, pt);
-  //   } else if (dataMode === 'raw') {
-  //     handleOriginalPointClick(figure, pt);
-  //   }
-  // }, [dataType, avgPointRawMap, figure, selectedImages]);
 
 
   function clearAll() {

src/components/Navbar/Navbar.tsx

@@ -23,7 +23,7 @@ export default function Navbar() {
   const mainLinks = [
     { name: '2D Plot', href: `${process.env.BASE_PATH}/`, id: '2d-plot-link', disabled: false  },
     { name: 'Matrix', href: `${process.env.BASE_PATH}/matrix/`, id: 'matrix-link', disabled: false  },
-    { name: 'Signal-to-noise', href: `${process.env.BASE_PATH}/noise`, id: 'noise-link', disabled: true },
+    { name: 'Signal-to-Noise Ratio', href: `${process.env.BASE_PATH}/snr`, id: 'noise-link', disabled: false },
   ]
   // const settingsLink = { name: 'Settings', href: '#', id: 'settings-link' }
 

src/components/Sidebar/Sidebar.tsx

@@ -15,6 +15,14 @@ const visibilityByPath: Record<string, Partial<Record<string, boolean>>> = {
     xAxis: true,
     errorBars: true,
   },
+  '/snr/': {
+    dataType: false,
+    selectedSeries: true,
+    dataSelection: true,
+    averageConfig: true,
+    xAxis: true,
+    errorBars: true,
+  },
   '/matrix/': {
     dataType: false,
     selectedSeries: true,
@@ -38,7 +46,7 @@ type RawFilterMode = "none" | "percent" | "sigma";
 
 export default function Sidebar() {
   const {
-    dataType, dataSelection, xAxis, errorBars, noOfBins, noOfDataPoint, colorBy, filterPercent, isRawFilterInside, selectedSeries,
+    dataType, dataSelection, xAxis, errorBars, noOfBins, noOfDataPoint, filterPercent, isRawFilterInside, selectedSeries,
     sigmaK,
     rawFilterMode,
     setSettings,
@@ -74,6 +82,7 @@ export default function Sidebar() {
   const dataTypeOptions = [
     { value: 'average', label: 'Average' },
     { value: 'raw', label: 'Raw' },
+    // { value: 'snr', label: 'Signal-to-Noise Ratio' },
   ];
 
   const xAxisOptions = [

src/utils/traces.ts

@@ -14,6 +14,18 @@ function toHomogeneousX(x: Array<number | string | Date>): number[] | string[] |
     return x.map(v => v instanceof Date ? v.toISOString() : String(v));
 }
 
+export function computeSNR(flux: number[], fluxErr: number[]) {
+    const y = flux.map((v, i) =>
+        fluxErr[i] > 0 ? v / fluxErr[i] : NaN
+    );
+
+    // Optional: SNR has no natural "error bar"
+    // If you want one, you could set err = 1 or 0
+    const err = fluxErr.map(() => 0);
+
+    return { y, err };
+}
+
 export function processForTrace({
     wave,
     json,
@@ -34,6 +46,7 @@ export function processForTrace({
     let err: number[] = [];
     let customdata: AveragePointCustomData[] = [];
 
+    const isSNR = mode === 'snr';
     if (mode === 'average') {
         if (axis === 'phase') {
             const flux: number[] = Array.isArray(json.psf_flux_phase) ? json.psf_flux_phase : [];
@@ -78,11 +91,13 @@ export function processForTrace({
             for (let i = 0; i < noOfBins; i++) {
                 if (!bins[i].length) continue;
                 const [avg, avgErr] = weightedAvg(bins[i], berr[i]);
+                const yVal = isSNR && avgErr > 0 ? avg / avgErr : avg;
+                const errVal = isSNR ? 0 : avgErr;
                 const center = centers[i];
 
                 x.push(center);
-                y.push(avg);
-                err.push(avgErr);
+                y.push(yVal);
+                err.push(errVal);
                 customdata.push({ type, epoch, r_in, r_out, phase: center.toFixed(5), avgErr });
 
                 const rawPoints = bins[i].map((yVal, j) => ({
@@ -130,11 +145,14 @@ export function processForTrace({
                 if (!tc.length) return;
 
                 const [avg, avgErr] = weightedAvg(fc, ec);
+                
+                const yVal = isSNR && avgErr > 0 ? avg / avgErr : avg;
+                const errVal = isSNR ? 0 : avgErr;
                 const center = tc.reduce((a, b) => a + b, 0) / tc.length;
 
                 x.push(center);
-                y.push(avg);
-                err.push(avgErr);
+                y.push(yVal);
+                err.push(errVal);
                 customdata.push({ type, epoch, r_in, r_out, phase: center.toFixed(5), avgErr });
 
                 const rawPoints = fc.map((yVal, j) => ({
@@ -158,15 +176,16 @@ export function processForTrace({
             for (let i = 0; i < n; i++) doRange(i * chunkSize, (i + 1) * chunkSize);
             if (n * chunkSize < flux.length) doRange(n * chunkSize, flux.length);
         }
-    } else {
+    }
+    else {
         // RAW
         const isPhase = axis === 'phase';
         const rawX = json[isPhase ? 'phase_values_phase' : timeKey];
         x = Array.isArray(rawX) ? (rawX as number[]) : [];
-        y = isPhase
+        const flux = isPhase
             ? (Array.isArray(json.psf_flux_phase) ? (json.psf_flux_phase as number[]) : [])
             : (Array.isArray(json.psf_flux_time) ? (json.psf_flux_time as number[]) : []);
-        err = isPhase
+        const fluxErr = isPhase
             ? (Array.isArray(json.psf_flux_unc_phase) ? (json.psf_flux_unc_phase as number[]) : [])
             : (Array.isArray(json.psf_flux_unc_time) ? (json.psf_flux_unc_time as number[]) : []);
         customdata = isPhase
@@ -175,6 +194,14 @@ export function processForTrace({
         //   as AveragePointCustomData[];
         // console.log(json)
         // console.log(customdata)
+        if (isSNR) {
+            const snr = computeSNR(flux, fluxErr);
+            y = snr.y;
+            err = snr.err;
+        } else {
+            y = flux;
+            err = fluxErr;
+        }
 
         if (isPhase) {
             x = x.concat((x as number[]).map(v => v + 1));