flits 1.2.0__tar.gz → 1.2.2__tar.gz

{flits-1.2.0/flits.egg-info → flits-1.2.2}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: flits
-Version: 1.2.0
+Version: 1.2.2
 Summary: Browser-based FRB burst analysis software (SIGPROC, PSRFITS, CHIME/FRB HDF5)
 Author: Dirk Kuiper
 License-Expression: GPL-3.0-only
 Project-URL: Homepage, https://github.com/DirkKuiper/flits
-Project-URL: Documentation, https://github.com/DirkKuiper/flits#readme
+Project-URL: Documentation, https://dirkkuiper.github.io/flits/
 Project-URL: Issues, https://github.com/DirkKuiper/flits/issues
 Project-URL: Releases, https://github.com/DirkKuiper/flits/releases
 Project-URL: Repository, https://github.com/DirkKuiper/flits
@@ -64,36 +64,32 @@ including public catalog waterfalls and beamformed `BBData`
 `tiedbeam_power` files. The I/O layer is pluggable — third parties can
 register custom formats via `importlib` entry points without forking.
 
-Every interactive decision is recorded in a JSON session snapshot, and
-`flits replay` re-runs that snapshot headlessly to reproduce the exported
-measurements without a browser.
+The selected analysis state is recorded in a JSON session snapshot. Given
+the snapshot and original data, `flits replay` restores the selections and
+recomputes supported measurements without a browser.
+
+![FLITS aligned viewer showing a GBT burst with its time profile, dynamic spectrum, frequency profile, and selected event, off-pulse, and spectral windows.](docs/assets/guided-workflow/prepared-viewer.png)
+
+The [guided GBT workflow](https://dirkkuiper.github.io/flits/guided-workflow/)
+walks through the selections and results shown in the interface.
 
 ## Why FLITS exists
 
-Turning a detected burst into a number you can defend takes several steps —
-tune the DM, mask interference, place the event and off-pulse windows, choose a
-spectral extent, then measure — and every one of them is a judgement call that
-moves the answer.
-
-The tools that do these steps well do them separately. Search pipelines stop at
-detection; format libraries read data without offering a workflow; and the
-strong single-purpose tools each expect their own input conventions. So a burst
-campaign accumulates per-instrument glue scripts, and the decisions that
-produced the numbers survive only in someone's notebook.
-
-That gets harder for repeating sources, where the same population is observed by
-many telescopes. FLITS was built for a repeater campaign spanning GBT at L and P
-band, Nançay, Westerbork, Onsala, Stockert and CHIME — three file formats,
-sampling times differing by more than an order of magnitude, and instruments
-with different bandwidths, polarization conventions and SEFDs.
-
-FLITS makes the session, rather than the script, the unit of analysis. One
-interface covers every supported instrument, the reader layer absorbs the format
-differences, telescope presets carry the instrument-specific calibration, and
-the snapshot makes the analysis inspectable and replayable afterwards.
-Measurements state their own uncertainty basis: FLITS separates a formal 1-sigma
-uncertainty from a statistical-only one, and will not mark a fluence publishable
-when the SEFD systematic it needs was never supplied.
+Measuring a detected burst involves selecting an event window and noise
+reference, masking interference, choosing a frequency range, and refining the
+dispersion measure (DM). These choices affect the resulting measurements and
+must be preserved to interpret and reproduce them.
+
+FLITS was built for a repeater campaign spanning GBT at L and P band, Nançay,
+Westerbork, Onsala, Stockert, and CHIME. A common reader interface and configurable
+telescope presets support analysis across their formats and calibration
+conventions. The session retains the selected state so collaborators can
+reopen it and recompute supported measurements from the original data.
+
+FLITS builds on specialist search, data-processing, and analysis packages. It
+connects measurements through a shared session model with explicit calibration
+and uncertainty metadata. Flux and fluence estimates without a supplied SEFD
+uncertainty are flagged as having an incomplete uncertainty budget.
 
 FLITS is not a search pipeline — it starts from a burst you already have.
 

{flits-1.2.0 → flits-1.2.2}/README.md

@@ -17,36 +17,32 @@ including public catalog waterfalls and beamformed `BBData`
 `tiedbeam_power` files. The I/O layer is pluggable — third parties can
 register custom formats via `importlib` entry points without forking.
 
-Every interactive decision is recorded in a JSON session snapshot, and
-`flits replay` re-runs that snapshot headlessly to reproduce the exported
-measurements without a browser.
+The selected analysis state is recorded in a JSON session snapshot. Given
+the snapshot and original data, `flits replay` restores the selections and
+recomputes supported measurements without a browser.
+
+![FLITS aligned viewer showing a GBT burst with its time profile, dynamic spectrum, frequency profile, and selected event, off-pulse, and spectral windows.](docs/assets/guided-workflow/prepared-viewer.png)
+
+The [guided GBT workflow](https://dirkkuiper.github.io/flits/guided-workflow/)
+walks through the selections and results shown in the interface.
 
 ## Why FLITS exists
 
-Turning a detected burst into a number you can defend takes several steps —
-tune the DM, mask interference, place the event and off-pulse windows, choose a
-spectral extent, then measure — and every one of them is a judgement call that
-moves the answer.
-
-The tools that do these steps well do them separately. Search pipelines stop at
-detection; format libraries read data without offering a workflow; and the
-strong single-purpose tools each expect their own input conventions. So a burst
-campaign accumulates per-instrument glue scripts, and the decisions that
-produced the numbers survive only in someone's notebook.
-
-That gets harder for repeating sources, where the same population is observed by
-many telescopes. FLITS was built for a repeater campaign spanning GBT at L and P
-band, Nançay, Westerbork, Onsala, Stockert and CHIME — three file formats,
-sampling times differing by more than an order of magnitude, and instruments
-with different bandwidths, polarization conventions and SEFDs.
-
-FLITS makes the session, rather than the script, the unit of analysis. One
-interface covers every supported instrument, the reader layer absorbs the format
-differences, telescope presets carry the instrument-specific calibration, and
-the snapshot makes the analysis inspectable and replayable afterwards.
-Measurements state their own uncertainty basis: FLITS separates a formal 1-sigma
-uncertainty from a statistical-only one, and will not mark a fluence publishable
-when the SEFD systematic it needs was never supplied.
+Measuring a detected burst involves selecting an event window and noise
+reference, masking interference, choosing a frequency range, and refining the
+dispersion measure (DM). These choices affect the resulting measurements and
+must be preserved to interpret and reproduce them.
+
+FLITS was built for a repeater campaign spanning GBT at L and P band, Nançay,
+Westerbork, Onsala, Stockert, and CHIME. A common reader interface and configurable
+telescope presets support analysis across their formats and calibration
+conventions. The session retains the selected state so collaborators can
+reopen it and recompute supported measurements from the original data.
+
+FLITS builds on specialist search, data-processing, and analysis packages. It
+connects measurements through a shared session model with explicit calibration
+and uncertainty metadata. Flux and fluence estimates without a supplied SEFD
+uncertainty are flagged as having an incomplete uncertainty budget.
 
 FLITS is not a search pipeline — it starts from a burst you already have.
 

{flits-1.2.0 → flits-1.2.2}/docs/analysis/dm-optimization.md

@@ -105,6 +105,13 @@ That state is what the session snapshot records.
 
 ## Reading the result
 
+![DMphase score curve and residual arrival time plots from the guided GBT example.](../assets/guided-workflow/dm-sweep.png)
+
+*The DMphase curve peaks near a residual DM of 5.5 on the sampled grid; the
+weighted fit reports about 5.41. The lower plot compares sub-band arrival-time
+residuals at the applied and fitted DMs. See the [GBT guided workflow](../guided-workflow.md)
+for the inputs and interpretation limits of this example.*
+
 | Output | What to look at |
 | --- | --- |
 | Score curve | Should have a clear single maximum. Multiple comparable peaks mean the metric cannot distinguish them. |

{flits-1.2.0 → flits-1.2.2}/docs/analysis/measurements.md

@@ -2,6 +2,13 @@
 
 FLITS reports measurements from the current prepared session state.
 
+![Prepare tab showing selected windows, headline measurements, signal metrics, and uncertainty flags for the GBT tutorial burst.](../assets/guided-workflow/measurement-summary.png)
+
+*The Prepare tab groups selection readiness, headline measurements, timing
+details, and uncertainty flags. These values come from the [GBT guided
+workflow](../guided-workflow.md); its absolute TOA fields are not part of the
+validated reference calculation.*
+
 ## Core outputs
 
 The measurement workflow can report:

{flits-1.2.0 → flits-1.2.2}/docs/analysis/rm-synthesis.md

@@ -83,7 +83,7 @@ print(result.linear_fraction, result.circular_fraction)
 `result.rm_synthesis` holds the full RM-synthesis payload documented below.
 The result also records the basis and what established it, the exact event and
 off-pulse windows, the channels that survived, and the integrated Stokes I, Q, U
-and V spectra — which is what makes it reproducible from the snapshot alone.
+and V spectra — which supports replay from the snapshot and original data.
 
 ### Reading the cube directly
 

{flits-1.2.0 → flits-1.2.2}/docs/analysis/temporal-spectral.md

@@ -53,6 +53,12 @@ is built to remove exactly this S/N dependence.
 
 ## ACF widths are not durations
 
+![Temporal and spectral autocorrelation functions for the guided GBT burst, with a dashed half-maximum reference line.](../assets/guided-workflow/temporal-acf.png)
+
+*The dashed line marks normalized ACF = 0.5. Its intersections with the curves
+give self-similarity widths in time and frequency for the [GBT example](../guided-workflow.md),
+not the manually selected event duration.*
+
 An ACF width is a self-similarity scale. It is a good way to compare coherence
 structure between bursts or between time and frequency, but it is not
 interchangeable with the full burst duration, and the two can differ by a large

flits-1.2.2/docs/assets/session-state.svg

@@ -0,0 +1,42 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1040" height="270" viewBox="0 0 1040 270" role="img" aria-labelledby="title description">
+  <title id="title">How one FLITS session carries selections into analysis and export</title>
+  <desc id="description">A source file and applied DM lead to prepared crop, event, off-pulse, spectral, and mask selections. Those shared selections feed measurements and specialist analysis tabs. Results and selections can then be saved as a session snapshot or exported as products.</desc>
+  <defs>
+    <marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="5" orient="auto">
+      <path d="M1 1 L9 5 L1 9" fill="none" stroke="#5c358a" stroke-width="2"/>
+    </marker>
+  </defs>
+  <rect width="1040" height="270" rx="18" fill="#faf8fd"/>
+  <g font-family="Arial, Helvetica, sans-serif" fill="#252132">
+    <rect x="24" y="56" width="182" height="160" rx="14" fill="#fff" stroke="#d9cfe9" stroke-width="2"/>
+    <text x="44" y="94" font-size="22" font-weight="700">Load</text>
+    <text x="44" y="127" font-size="16">Source file</text>
+    <text x="44" y="152" font-size="16">Applied DM</text>
+    <text x="44" y="177" font-size="16">Preset / calibration</text>
+
+    <rect x="244" y="32" width="245" height="208" rx="14" fill="#f1e9fa" stroke="#9e7ac4" stroke-width="2"/>
+    <text x="264" y="70" font-size="22" font-weight="700">Prepare</text>
+    <text x="264" y="104" font-size="16">Crop + event window</text>
+    <text x="264" y="129" font-size="16">Off-pulse windows</text>
+    <text x="264" y="154" font-size="16">Spectral window</text>
+    <text x="264" y="179" font-size="16">Channel mask</text>
+    <text x="264" y="211" font-size="13" fill="#5c358a">Shared session state</text>
+
+    <rect x="528" y="56" width="232" height="160" rx="14" fill="#fff" stroke="#d9cfe9" stroke-width="2"/>
+    <text x="548" y="94" font-size="22" font-weight="700">Analyze</text>
+    <text x="548" y="127" font-size="16">Compute measurements</text>
+    <text x="548" y="152" font-size="16">DM / Temporal / Drift</text>
+    <text x="548" y="177" font-size="16">Fitting / Polarization</text>
+
+    <rect x="799" y="56" width="217" height="160" rx="14" fill="#fff" stroke="#d9cfe9" stroke-width="2"/>
+    <text x="819" y="94" font-size="22" font-weight="700">Keep results</text>
+    <text x="819" y="127" font-size="16">Save session snapshot</text>
+    <text x="819" y="152" font-size="16">Download JSON</text>
+    <text x="819" y="177" font-size="16">Build export bundle</text>
+  </g>
+  <g fill="none" stroke="#5c358a" stroke-width="2.5" marker-end="url(#arrow)">
+    <path d="M207 136 H236"/>
+    <path d="M490 136 H519"/>
+    <path d="M761 136 H790"/>
+  </g>
+</svg>

flits-1.2.2/docs/developer/joss-submission.md

@@ -0,0 +1,79 @@
+# JOSS manuscript preparation
+
+The manuscript is `paper/paper.md`, with references in `paper/paper.bib` and
+software citation metadata in `CITATION.cff`. The JOSS Paper workflow validates
+these files and builds an official JOSS draft PDF on relevant pull requests.
+
+## Validate the manuscript
+
+From the repository root, in a Python environment:
+
+```bash
+python -m pip install -r paper/requirements.txt
+python paper/check.py
+cffconvert --validate
+```
+
+The checker verifies section coverage, word count, citation keys, ORCID
+checksums, matching title and author identifiers, and unfinished author markers.
+For the final reference audit, also run:
+
+```bash
+python paper/check.py --check-dois
+```
+
+This requires `curl` and network access. It checks DOI resolution and compares
+bibliographic titles, volumes, issues, and pages with Crossref. A resolving DOI
+can still point to the wrong article. Author lists, attribution, and references
+without DOIs also need human review.
+
+## Build the official proof
+
+Download the `paper` artifact from the JOSS Paper workflow, or build locally
+with [Inara](https://github.com/openjournals/inara) and Docker:
+
+```bash
+docker run --rm --volume "$PWD/paper:/data" \
+  --user "$(id -u):$(id -g)" --env JOURNAL=joss openjournals/inara
+```
+
+Inspect `paper/paper.pdf`, including every reference page. The draft watermark
+and placeholder DOI, publication details, and submission date are supplied by
+the journal template and are replaced during the publication process.
+
+## Check the supporting materials
+
+Run the [software checks](testing.md), the
+[GBT reference workflow](../guided-workflow.md), and the
+[RM-synthesis reference example](../analysis/rm-synthesis.md). The Reference
+Workflows action checks the GBT measurements and portable replay on Linux,
+using both the published package and the current checkout with pinned
+dependencies. The example data remain a separate downloadable release asset;
+the reference snapshot and expected results are in `docs/examples/`.
+
+Before submission, the authors should review the final proof and agree on
+authorship, affiliations, contribution credit, funding acknowledgements,
+conflicts of interest, and the AI disclosure. Confirm that its statements about
+human review and scientific decisions accurately describe the work. The
+disclosure names the known assistants and explicitly records the absence of a
+systematic historical model/version record; it does not invent missing details.
+
+The submission form should identify any related science or methods papers,
+including manuscripts in preparation or under review. Retain factual evidence
+of the research uses described in the paper, such as a project report or
+analysis record, in case the editors request it. Confirm credit for any
+additional contributors before submission.
+
+## Submission and the final archive
+
+Follow the current [JOSS submission requirements](https://joss.readthedocs.io/en/latest/submitting.html)
+and [paper guidance](https://joss.readthedocs.io/en/latest/paper.html). The
+manuscript and software must be available together in the public repository;
+a submission branch is allowed. Use the branch containing the final reviewed
+manuscript if it has not yet been merged.
+
+After review, archive the exact final tagged software release with Zenodo or
+figshare and provide its version and archival DOI. A final archive DOI is not
+required for the initial submission. Preserve the example data, provenance,
+and sharing terms in a suitable archive as well; a GitHub release asset alone
+does not establish that a separate archival deposit exists.

{flits-1.2.0 → flits-1.2.2}/docs/developer/testing.md

@@ -59,11 +59,12 @@ They need Playwright and a browser binary:
 ```bash
 python -m pip install pytest-playwright
 python -m playwright install chromium
-python -m pytest tests/test_frontend_e2e.py -q
+python -m pytest tests/test_frontend_e2e.py -q -m e2e
 ```
 
-Without Playwright installed they skip, so the ordinary `pytest` run is
-unaffected. CI runs them in a dedicated job. To skip them explicitly:
+The default test configuration excludes browser and local-observatory-data
+tests. Select `-m e2e` explicitly for the browser run above. Without Playwright
+installed the browser module skips. CI runs them in a dedicated job. To skip them explicitly:
 
 ```bash
 python -m pytest -m "not e2e"

flits-1.2.2/docs/examples/gbt-reference-requirements.txt

@@ -0,0 +1,50 @@
+annotated-doc==0.0.5
+annotated-types==0.8.0
+anyio==4.15.1
+astropy==8.0.1
+astropy-iers-data==0.2026.9.21.0.56.25
+click==8.5.0
+cloudpickle==3.1.2
+contourpy==1.4.0
+cycler==0.12.1
+fastapi==0.139.2
+flits==1.2.0
+fonttools==4.65.0
+h11==0.16.0
+h5py==3.16.0
+idna==3.20
+ImageIO==2.37.4
+jess==0.3.1
+joblib==1.6.0
+kiwisolver==1.5.1
+lazy-loader==0.5
+llvmlite==0.49.0
+markdown-it-py==4.2.0
+matplotlib==3.11.1
+mdurl==0.1.2
+narwhals==2.26.0
+networkx==3.6.1
+numba==0.67.0
+numpy==2.4.6
+packaging==26.3
+pandas==3.0.6
+pillow==12.3.0
+pydantic==2.13.4
+pydantic_core==2.46.4
+pyerfa==2.0.1.5
+Pygments==2.21.0
+pyparsing==3.3.3
+python-dateutil==2.9.0.post0
+PyYAML==6.0.3
+rich==15.0.0
+scikit-image==0.26.0
+scikit-learn==1.9.1
+scipy==1.17.1
+six==1.17.0
+starlette==1.6.0
+threadpoolctl==3.7.0
+tifffile==2026.9.20
+typing-inspection==0.4.4
+typing_extensions==4.16.0
+uvicorn==0.51.0
+your==0.6.7