Skip to content

Commit 3fa3035

Browse files
tpeulentpeulen
committed
fix(docs): commit missing docs-coverage scripts, guides, and gallery examples
The 'Build Documentation' CI job failed with exit code 2 because tools/check_docs_pages.py (invoked without '|| true' in ci.yml) was never committed. The follow-on check_docs_coverage.py step and several user-guide pages / gallery examples referenced by committed toctrees and doc/api-coverage.yml were likewise untracked. Add the full uncommitted docs batch: - tools/{check_docs_pages,check_docs_coverage,update_docs_versions}.py - doc/api-coverage.yml and the guide pages it lists as source_pages (workflows, tttr-core, burst-analysis, pda-guide, fcs-correlation, clsm-flim-guide, fit-guide) plus docs-warning-burndown - doc/tune_toc.rst and doc/includes/big_toc_css.rst (.. include:: targets) - gallery examples plot_fit_helpers.py and plot_pda_synthetic.py
1 parent 04d1a07 commit 3fa3035

16 files changed

Lines changed: 1909 additions & 0 deletions

‎doc/api-coverage.yml‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
{
2+
"version": 1,
3+
"domains": [
4+
{
5+
"name": "TTTR core and photon selections",
6+
"source_pages": ["workflows.rst", "tttr-core.rst", "tttr.rst"],
7+
"html_pages": ["workflows.html", "tttr-core.html", "tttr.html"],
8+
"examples": [
9+
"examples/beginner/plot_01_reading_files.py",
10+
"examples/beginner/plot_03_selections.py",
11+
"examples/beginner/plot_04_writing_files.py",
12+
"examples/tttr/plot_tttr_header.py",
13+
"examples/tttr/plot_tttr_microtime_histogram.py",
14+
"examples/tttr/plot_tttr_transcode.py"
15+
],
16+
"symbols": ["TTTR", "TTTRHeader", "TTTRMask", "TTTRSelection", "TTTRRange"]
17+
},
18+
{
19+
"name": "Selections, masks, and ranges",
20+
"source_pages": ["workflows.rst", "tttr-core.rst", "burst-analysis.rst"],
21+
"html_pages": ["workflows.html", "tttr-core.html", "burst-analysis.html"],
22+
"examples": [
23+
"examples/beginner/plot_03_selections.py",
24+
"examples/single_molecule/plot_burstfilter_with_selection.py",
25+
"examples/single_molecule/plot_microtime_selection_example.py"
26+
],
27+
"symbols": ["TTTRMask", "TTTRSelection", "TTTRRange"]
28+
},
29+
{
30+
"name": "File I/O and transcoding",
31+
"source_pages": ["workflows.rst", "tttr-core.rst"],
32+
"html_pages": ["workflows.html", "tttr-core.html"],
33+
"examples": [
34+
"examples/beginner/plot_01_reading_files.py",
35+
"examples/beginner/plot_04_writing_files.py",
36+
"examples/tttr/plot_tttr_header.py",
37+
"examples/tttr/plot_tttr_files.py",
38+
"examples/tttr/plot_tttr_transcode.py",
39+
"examples/tttr/plot_tttr_write.py"
40+
],
41+
"symbols": ["TTTR", "TTTRHeader"]
42+
},
43+
{
44+
"name": "Single-molecule burst analysis",
45+
"source_pages": ["workflows.rst", "burst-analysis.rst", "single_molecule.rst"],
46+
"html_pages": ["workflows.html", "burst-analysis.html", "single_molecule.html"],
47+
"examples": [
48+
"examples/single_molecule/plot_01_burst_analysis.py",
49+
"examples/single_molecule/plot_burst_analysis_with_filter.py",
50+
"examples/single_molecule/plot_burstfilter_with_selection.py",
51+
"examples/single_molecule/plot_complete_burst_analysis_pipeline.py",
52+
"examples/single_molecule/plot_fret_burst_analysis.py"
53+
],
54+
"symbols": ["BurstFilter", "BurstFeatureExtractor", "TTTRRange", "TTTRSelection"]
55+
},
56+
{
57+
"name": "Photon Distribution Analysis",
58+
"source_pages": ["workflows.rst", "pda-guide.rst"],
59+
"html_pages": ["workflows.html", "pda-guide.html", "modules/pda.html"],
60+
"examples": [
61+
"examples/single_molecule/plot_pda_synthetic.py",
62+
"examples/single_molecule/plot_single_molecule_pda_1.py",
63+
"examples/single_molecule/plot_single_molecule_pda_2.py"
64+
],
65+
"symbols": ["Pda", "PdaCallback", "PDA_DEFAULT", "PDA_OPTIMIZED"]
66+
},
67+
{
68+
"name": "FCS and correlation",
69+
"source_pages": ["workflows.rst", "fcs-correlation.rst"],
70+
"html_pages": ["workflows.html", "fcs-correlation.html", "modules/fcs.html", "modules/correlation.html"],
71+
"examples": [
72+
"examples/correlation/plot_normal_correlation.py",
73+
"examples/correlation/plot_full_correlation.py",
74+
"examples/correlation/plot_gated_correlation.py",
75+
"examples/correlation/plot_sliced_correlation.py",
76+
"examples/correlation/plot_confocor3_two_ch_correlation.py",
77+
"examples/image_correlation/plot_imaging_ics_tttrlib.py"
78+
],
79+
"symbols": ["Correlator", "CorrelatorPhotonStream"]
80+
},
81+
{
82+
"name": "Image correlation spectroscopy",
83+
"source_pages": ["workflows.rst", "fcs-correlation.rst", "clsm-flim-guide.rst"],
84+
"html_pages": ["workflows.html", "fcs-correlation.html", "clsm-flim-guide.html"],
85+
"examples": [
86+
"examples/image_correlation/plot_imaging_ics_tttrlib.py",
87+
"examples/image_correlation/plot_imaging_ics_numpy.py",
88+
"examples/image_correlation/plot_imaging_ics_fit.py",
89+
"examples/image_correlation/plot_imaging_ics_benchmark.py"
90+
],
91+
"symbols": ["CLSMImage", "Correlator", "compute_ics"]
92+
},
93+
{
94+
"name": "CLSM, FLIM, and image analysis",
95+
"source_pages": ["workflows.rst", "clsm-flim-guide.rst", "imaging.rst"],
96+
"html_pages": ["workflows.html", "clsm-flim-guide.html", "imaging.html", "modules/imaging.html", "modules/imaging_mle.html"],
97+
"examples": [
98+
"examples/beginner/plot_05_microscopy.py",
99+
"examples/flim/plot_read_clsm_data.py",
100+
"examples/flim/plot_intensity_image.py",
101+
"examples/flim/plot_mean_lifetime.py",
102+
"examples/flim/plot_phasor.py",
103+
"examples/flim/plot_mle_lifetime.py",
104+
"examples/flim/plot_segmentation_based_decays.py",
105+
"examples/image_correlation/plot_imaging_ics_tttrlib.py"
106+
],
107+
"symbols": [
108+
"CLSMSettings",
109+
"CLSMImage",
110+
"CLSMFrame",
111+
"CLSMLine",
112+
"CLSMPixel",
113+
"CLSMISM",
114+
"CLSM_DEFAULT",
115+
"CLSM_SP5",
116+
"CLSM_SP8",
117+
"CLSM_BH_SPC130"
118+
]
119+
},
120+
{
121+
"name": "Image localization",
122+
"source_pages": ["workflows.rst", "localization-guide.rst"],
123+
"html_pages": ["workflows.html", "localization-guide.html", "auto_examples/microscopy_localization/plot_image_localization.html"],
124+
"examples": [
125+
"examples/microscopy_localization/plot_image_localization.py"
126+
],
127+
"symbols": ["ImageLocalizer", "GaussianFitResult"]
128+
},
129+
{
130+
"name": "Phasor and mean-lifetime analysis",
131+
"source_pages": ["workflows.rst", "clsm-flim-guide.rst", "fit-guide.rst"],
132+
"html_pages": ["workflows.html", "clsm-flim-guide.html", "fit-guide.html"],
133+
"examples": [
134+
"examples/flim/plot_phasor.py",
135+
"examples/flim/plot_mean_lifetime.py",
136+
"examples/flim/plot_lifetime_moments.py",
137+
"examples/flim/plot_lifetime_moments_bg.py"
138+
],
139+
"symbols": ["DecayPhasor", "get_phasor", "get_mean_lifetime", "get_mean_micro_time_image"]
140+
},
141+
{
142+
"name": "Fluorescence decay and fitting",
143+
"source_pages": ["workflows.rst", "fit-guide.rst"],
144+
"html_pages": ["workflows.html", "fit-guide.html", "modules/decay.html"],
145+
"examples": [
146+
"examples/fluorescence_decay/plot_fit23.py",
147+
"examples/fluorescence_decay/plot_fit23_usage_2.py",
148+
"examples/fluorescence_decay/plot_fit24.py",
149+
"examples/fluorescence_decay/plot_fit25.py",
150+
"examples/fluorescence_decay/plot_fit26.py",
151+
"examples/fluorescence_decay/plot_fit_helpers.py",
152+
"examples/fluorescence_decay/plot_convolution_routines.py",
153+
"examples/flim/plot_mle_lifetime.py"
154+
],
155+
"symbols": [
156+
"Fit2x",
157+
"Fit23",
158+
"Fit24",
159+
"Fit25",
160+
"Fit26",
161+
"fit23",
162+
"fit24",
163+
"fit25",
164+
"fit26",
165+
"DecayFit23",
166+
"DecayFit24",
167+
"DecayFit25",
168+
"DecayFit26",
169+
"DecayFitData",
170+
"DecayConvolution",
171+
"DecayPhasor"
172+
]
173+
}
174+
]
175+
}

‎doc/burst-analysis.rst‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
.. _burst_analysis_guide:
2+
3+
Burst Analysis
4+
==============
5+
6+
Burst analysis groups photons into short time intervals where a molecule passes
7+
through the observation volume. In tttrlib, burst workflows start from ``TTTR``
8+
photon streams and return selections, ranges, and burst-level parameters that
9+
can be used for FRET, PDA, decay histograms, or filtering.
10+
11+
Core Objects
12+
------------
13+
14+
``BurstFilter``
15+
Runs burst search and filtering. It supports parameterized burst detection,
16+
filtering by burst size, duration, background, and dynamic parameter changes.
17+
18+
``BurstFeatureExtractor``
19+
Computes burst-level features that can be used for filtering, summaries, or
20+
downstream plots.
21+
22+
``TTTRRange`` and ``TTTRSelection``
23+
Store the photon index ranges that define bursts and derived selections.
24+
25+
Simple Path
26+
-----------
27+
28+
Use the simple path when you want one burst list from one photon stream:
29+
30+
.. code-block:: python
31+
32+
tttr = tttrlib.TTTR("single_molecule.spc", "SPC-130")
33+
bursts = tttr.get_ranges_by_time_window(
34+
minimum_window_length=0.0005,
35+
minimum_number_of_photons_in_time_window=30,
36+
macro_time_calibration=tttr.header.macro_time_resolution,
37+
)
38+
39+
Then compute burst sizes, durations, and channel counts from the returned ranges.
40+
41+
Advanced Path
42+
-------------
43+
44+
Use ``BurstFilter`` when burst selection is an iterative part of the analysis:
45+
46+
* search with an initial count-rate threshold,
47+
* merge short gaps,
48+
* filter on photon count, duration, or background,
49+
* relax thresholds and reapply filters,
50+
* export burst parameters to JSON for reproducibility.
51+
52+
The advanced examples show how to combine burst search with ALEX/PIE channel
53+
definitions, microtime gates, FRET observables, and serialized parameter sets.
54+
55+
Outputs and Checks
56+
------------------
57+
58+
Every burst example should report:
59+
60+
* number of bursts,
61+
* total photons assigned to bursts,
62+
* accepted/rejected counts after each filter,
63+
* burst size and duration distributions,
64+
* channel definitions and microtime gates,
65+
* enough parameters to reproduce the selection.
66+
67+
Troubleshooting
68+
---------------
69+
70+
No bursts
71+
Check macro-time calibration and lower the photon threshold. A threshold in
72+
raw macro-time units is a common mistake.
73+
74+
Too many bursts
75+
Increase the minimum photon count, shorten the maximum gap, or apply
76+
background filtering.
77+
78+
Unexpected FRET populations
79+
Verify donor/acceptor routing channels and PIE/ALEX gates before computing
80+
burst observables.
81+
82+
Examples
83+
--------
84+
85+
* :doc:`auto_examples/single_molecule/plot_01_burst_analysis`
86+
* :doc:`auto_examples/single_molecule/plot_burst_analysis_json`
87+
* :doc:`auto_examples/single_molecule/plot_burst_analysis_with_filter`
88+
* :doc:`auto_examples/single_molecule/plot_burstfilter_dynamic_enhanced`
89+
* :doc:`auto_examples/single_molecule/plot_fret_burst_analysis`
90+
* :doc:`auto_examples/single_molecule/plot_complete_burst_analysis_pipeline`
91+

0 commit comments

Comments
 (0)