lumic 0.1.0rc1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. lumic-0.1.0rc1/LICENSE +21 -0
  2. lumic-0.1.0rc1/PKG-INFO +139 -0
  3. lumic-0.1.0rc1/README.md +99 -0
  4. lumic-0.1.0rc1/__init__.py +528 -0
  5. lumic-0.1.0rc1/_nnls.py +142 -0
  6. lumic-0.1.0rc1/evaluation/__init__.py +18 -0
  7. lumic-0.1.0rc1/evaluation/correlation.py +143 -0
  8. lumic-0.1.0rc1/evaluation/maps.py +166 -0
  9. lumic-0.1.0rc1/evaluation/metrics.py +319 -0
  10. lumic-0.1.0rc1/evaluation/residuals.py +248 -0
  11. lumic-0.1.0rc1/evaluation/sampling.py +202 -0
  12. lumic-0.1.0rc1/fpbase.py +84 -0
  13. lumic-0.1.0rc1/image.py +548 -0
  14. lumic-0.1.0rc1/io.py +948 -0
  15. lumic-0.1.0rc1/lumic.egg-info/PKG-INFO +139 -0
  16. lumic-0.1.0rc1/lumic.egg-info/SOURCES.txt +68 -0
  17. lumic-0.1.0rc1/lumic.egg-info/dependency_links.txt +1 -0
  18. lumic-0.1.0rc1/lumic.egg-info/requires.txt +30 -0
  19. lumic-0.1.0rc1/lumic.egg-info/top_level.txt +1 -0
  20. lumic-0.1.0rc1/pyproject.toml +57 -0
  21. lumic-0.1.0rc1/readers.py +86 -0
  22. lumic-0.1.0rc1/setup.cfg +4 -0
  23. lumic-0.1.0rc1/simulation/__init__.py +33 -0
  24. lumic-0.1.0rc1/simulation/detector.py +135 -0
  25. lumic-0.1.0rc1/simulation/fpbase_data/README.md +54 -0
  26. lumic-0.1.0rc1/simulation/fpbase_data/ebfp2_emission.csv +202 -0
  27. lumic-0.1.0rc1/simulation/fpbase_data/egfp_emission.csv +239 -0
  28. lumic-0.1.0rc1/simulation/fpbase_data/mcherry_emission.csv +252 -0
  29. lumic-0.1.0rc1/simulation/fpbase_data/mneptune_emission.csv +223 -0
  30. lumic-0.1.0rc1/simulation/mixing.py +39 -0
  31. lumic-0.1.0rc1/simulation/noise.py +29 -0
  32. lumic-0.1.0rc1/simulation/psf.py +76 -0
  33. lumic-0.1.0rc1/simulation/render.py +135 -0
  34. lumic-0.1.0rc1/simulation/result.py +45 -0
  35. lumic-0.1.0rc1/simulation/scene.py +162 -0
  36. lumic-0.1.0rc1/simulation/simulate.py +77 -0
  37. lumic-0.1.0rc1/simulation/spatial.py +105 -0
  38. lumic-0.1.0rc1/simulation/spectra.py +60 -0
  39. lumic-0.1.0rc1/uniqueness.py +411 -0
  40. lumic-0.1.0rc1/utils.py +261 -0
lumic-0.1.0rc1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2022 Rafael Camacho
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,139 @@
1
+ Metadata-Version: 2.4
2
+ Name: lumic
3
+ Version: 0.1.0rc1
4
+ Summary: Spectral unmixing tools for fluorescence microscopy
5
+ Author: Lumic contributors
6
+ License-Expression: MIT
7
+ Project-URL: Repository, https://github.com/CCI-GU-Sweden/spectral-unmixing-microscopy
8
+ Classifier: Development Status :: 3 - Alpha
9
+ Classifier: Programming Language :: Python :: 3.12
10
+ Classifier: Topic :: Scientific/Engineering :: Image Processing
11
+ Requires-Python: <3.13,>=3.12
12
+ Description-Content-Type: text/markdown
13
+ License-File: LICENSE
14
+ Requires-Dist: numpy>=2.1
15
+ Requires-Dist: scipy>=1.14
16
+ Requires-Dist: scikit-learn>=1.6
17
+ Requires-Dist: scikit-image>=0.25
18
+ Requires-Dist: tqdm>=4.66
19
+ Requires-Dist: lxml>=4.9.2
20
+ Requires-Dist: pylibCZIrw>=6.1.0
21
+ Requires-Dist: ome-types<0.7,>=0.6.3
22
+ Requires-Dist: tifffile<2027,>=2026.9.20
23
+ Requires-Dist: imagecodecs>=2026.8.16
24
+ Provides-Extra: visualization
25
+ Requires-Dist: matplotlib>=3.9; extra == "visualization"
26
+ Provides-Extra: fpbase
27
+ Requires-Dist: fpbase==0.1.3; extra == "fpbase"
28
+ Provides-Extra: examples
29
+ Requires-Dist: matplotlib>=3.9; extra == "examples"
30
+ Requires-Dist: jupyterlab; extra == "examples"
31
+ Requires-Dist: ipykernel; extra == "examples"
32
+ Requires-Dist: pandas; extra == "examples"
33
+ Requires-Dist: multiprocess; extra == "examples"
34
+ Requires-Dist: threadpoolctl; extra == "examples"
35
+ Provides-Extra: test
36
+ Requires-Dist: pytest; extra == "test"
37
+ Provides-Extra: all
38
+ Requires-Dist: lumic[examples,fpbase,test,visualization]; extra == "all"
39
+ Dynamic: license-file
40
+
41
+ # Lumic backend
42
+
43
+ Lumic is a Python toolkit for spectral unmixing in fluorescence microscopy.
44
+ It reads CZI and OME-TIFF, fits component contributions from known reference
45
+ spectra or refines spectra with MCR-ALS, and exports quantitative results.
46
+ The backend runs without a graphical interface.
47
+
48
+ ## Install
49
+
50
+ Use Python 3.12. From the repository root, install with:
51
+
52
+ ```sh
53
+ python -m pip install ./Python/lumic
54
+ ```
55
+
56
+ The default install includes the bundled FPbase emission spectra. Optional
57
+ extras enable Matplotlib previews (`visualization`), online spectrum retrieval
58
+ (`fpbase`), notebook and plotting tools (`examples`), or pytest (`test`).
59
+ Install all four with `python -m pip install './Python/lumic[all]'`.
60
+
61
+ ## Unmix a simulated pixel offline
62
+
63
+ Sample two bundled spectra through the example 32-channel detector, then
64
+ estimate how much of each component was mixed into the pixel. The fit uses
65
+ known references, so it works without microscopy files or internet access.
66
+
67
+ ```python
68
+ import numpy as np
69
+
70
+ from lumic import positive_least_squares
71
+ from lumic.simulation import SpectralDetector, load_offline_emission_spectrum
72
+
73
+ detector = SpectralDetector.from_profile("980_32ch")
74
+ references = np.array([
75
+ detector.sample(*load_offline_emission_spectrum(name))
76
+ for name in ("EGFP", "mCherry")
77
+ ])
78
+ references /= references.sum(axis=1, keepdims=True)
79
+
80
+ # One pixel with contributions of 70 and 30 in total detected counts.
81
+ mixed_pixel = np.array([[70.0, 30.0]]) @ references
82
+ estimated = positive_least_squares(mixed_pixel, references, solver="auto")
83
+ print(np.round(estimated[0], 6)) # [70. 30.]
84
+ ```
85
+
86
+ ## Explore the examples
87
+
88
+ The examples live in the repository’s
89
+ [`Python/examples/`](https://github.com/CCI-GU-Sweden/spectral-unmixing-microscopy/tree/main/Python/examples)
90
+ directory. From the repository root, install the examples extra, switch to
91
+ `Python/`, and run the full workflow:
92
+
93
+ ```sh
94
+ python -m pip install './Python/lumic[examples]'
95
+ cd Python
96
+ python -m examples.spectral_image_workflow
97
+ ```
98
+
99
+ This walkthrough creates a three-protein mixture with shot noise, estimates
100
+ the component maps using known spectra, and plots the residual. It exports the
101
+ measurement, fitted reconstruction and abundance maps as OME-TIFF, then
102
+ reconstructs the fitted signal from the reloaded maps and their saved spectra.
103
+ See the [comparison figure](https://github.com/CCI-GU-Sweden/spectral-unmixing-microscopy/blob/main/Python/data/visual-check-spectral-image-workflow.png)
104
+ for the expected output.
105
+
106
+ | What you want to try | Command from `Python/` |
107
+ | --- | --- |
108
+ | Inspect a CZI or OME-TIFF header before loading pixels. Set `LOAD_PIXELS = True` in the script to read the selected plane. | `python -m examples.load_spectral_image` |
109
+ | Render a spectral Z stack in RGB and select one Z plane. | `python -m examples.render_spectral_rgb` |
110
+ | Simulate overlapping fluorescent structures and compare the recovered spectra and maps with the known inputs. | `python -m examples.visualize_overlapping_circles` |
111
+ | See how lower photon counts affect the relative noise in a spectral mixture. | `python -m examples.visualize_poisson_noise_levels` |
112
+ | Inspect spectral distinctness in an image and in the projected spectral space. | `python -m examples.visualize_spectral_uniqueness` |
113
+
114
+ These examples use bundled spectra or sample images and run offline once the
115
+ environment is installed. The separate `examples.simulate_fpbase_mixtures`
116
+ script fetches live spectra and needs internet access and the `fpbase` extra.
117
+
118
+ ## Go deeper with the backend guides
119
+
120
+ - **Work with microscope images.** Inspect CZI or OME-TIFF metadata before
121
+ loading pixels, select a time point or Z plane, and keep track of the image
122
+ axes as you unfold and refold the data. Save abundance maps as OME-TIFF with
123
+ the exact fitted spectra so you can reconstruct the fitted signal later.
124
+ [Image I/O guide](https://github.com/CCI-GU-Sweden/spectral-unmixing-microscopy/blob/main/Python/lumic/IO_README.md)
125
+ - **Build a controlled simulation.** Sample reference spectra through a
126
+ detector model, set the component contributions, and render spatial
127
+ shapes with optical blur and noise. Keep the original spectra and
128
+ abundance maps as ground truth for comparing fits.
129
+ [Simulation guide](https://github.com/CCI-GU-Sweden/spectral-unmixing-microscopy/blob/main/Python/lumic/simulation/README.md)
130
+ - **Evaluate a fit.** Align components before comparing spectra and
131
+ abundance maps across runs. When ground truth is unavailable, use signed
132
+ residual PCA and spatial or spectral correlations to look for patterns
133
+ the fit leaves unexplained.
134
+ [Evaluation guide](https://github.com/CCI-GU-Sweden/spectral-unmixing-microscopy/blob/main/Python/lumic/evaluation/README.md)
135
+
136
+ ## License and data attribution
137
+
138
+ Lumic is distributed under the MIT license. The bundled spectra carry their
139
+ FPbase source and attribution notice alongside the CSV files.
@@ -0,0 +1,99 @@
1
+ # Lumic backend
2
+
3
+ Lumic is a Python toolkit for spectral unmixing in fluorescence microscopy.
4
+ It reads CZI and OME-TIFF, fits component contributions from known reference
5
+ spectra or refines spectra with MCR-ALS, and exports quantitative results.
6
+ The backend runs without a graphical interface.
7
+
8
+ ## Install
9
+
10
+ Use Python 3.12. From the repository root, install with:
11
+
12
+ ```sh
13
+ python -m pip install ./Python/lumic
14
+ ```
15
+
16
+ The default install includes the bundled FPbase emission spectra. Optional
17
+ extras enable Matplotlib previews (`visualization`), online spectrum retrieval
18
+ (`fpbase`), notebook and plotting tools (`examples`), or pytest (`test`).
19
+ Install all four with `python -m pip install './Python/lumic[all]'`.
20
+
21
+ ## Unmix a simulated pixel offline
22
+
23
+ Sample two bundled spectra through the example 32-channel detector, then
24
+ estimate how much of each component was mixed into the pixel. The fit uses
25
+ known references, so it works without microscopy files or internet access.
26
+
27
+ ```python
28
+ import numpy as np
29
+
30
+ from lumic import positive_least_squares
31
+ from lumic.simulation import SpectralDetector, load_offline_emission_spectrum
32
+
33
+ detector = SpectralDetector.from_profile("980_32ch")
34
+ references = np.array([
35
+ detector.sample(*load_offline_emission_spectrum(name))
36
+ for name in ("EGFP", "mCherry")
37
+ ])
38
+ references /= references.sum(axis=1, keepdims=True)
39
+
40
+ # One pixel with contributions of 70 and 30 in total detected counts.
41
+ mixed_pixel = np.array([[70.0, 30.0]]) @ references
42
+ estimated = positive_least_squares(mixed_pixel, references, solver="auto")
43
+ print(np.round(estimated[0], 6)) # [70. 30.]
44
+ ```
45
+
46
+ ## Explore the examples
47
+
48
+ The examples live in the repository’s
49
+ [`Python/examples/`](https://github.com/CCI-GU-Sweden/spectral-unmixing-microscopy/tree/main/Python/examples)
50
+ directory. From the repository root, install the examples extra, switch to
51
+ `Python/`, and run the full workflow:
52
+
53
+ ```sh
54
+ python -m pip install './Python/lumic[examples]'
55
+ cd Python
56
+ python -m examples.spectral_image_workflow
57
+ ```
58
+
59
+ This walkthrough creates a three-protein mixture with shot noise, estimates
60
+ the component maps using known spectra, and plots the residual. It exports the
61
+ measurement, fitted reconstruction and abundance maps as OME-TIFF, then
62
+ reconstructs the fitted signal from the reloaded maps and their saved spectra.
63
+ See the [comparison figure](https://github.com/CCI-GU-Sweden/spectral-unmixing-microscopy/blob/main/Python/data/visual-check-spectral-image-workflow.png)
64
+ for the expected output.
65
+
66
+ | What you want to try | Command from `Python/` |
67
+ | --- | --- |
68
+ | Inspect a CZI or OME-TIFF header before loading pixels. Set `LOAD_PIXELS = True` in the script to read the selected plane. | `python -m examples.load_spectral_image` |
69
+ | Render a spectral Z stack in RGB and select one Z plane. | `python -m examples.render_spectral_rgb` |
70
+ | Simulate overlapping fluorescent structures and compare the recovered spectra and maps with the known inputs. | `python -m examples.visualize_overlapping_circles` |
71
+ | See how lower photon counts affect the relative noise in a spectral mixture. | `python -m examples.visualize_poisson_noise_levels` |
72
+ | Inspect spectral distinctness in an image and in the projected spectral space. | `python -m examples.visualize_spectral_uniqueness` |
73
+
74
+ These examples use bundled spectra or sample images and run offline once the
75
+ environment is installed. The separate `examples.simulate_fpbase_mixtures`
76
+ script fetches live spectra and needs internet access and the `fpbase` extra.
77
+
78
+ ## Go deeper with the backend guides
79
+
80
+ - **Work with microscope images.** Inspect CZI or OME-TIFF metadata before
81
+ loading pixels, select a time point or Z plane, and keep track of the image
82
+ axes as you unfold and refold the data. Save abundance maps as OME-TIFF with
83
+ the exact fitted spectra so you can reconstruct the fitted signal later.
84
+ [Image I/O guide](https://github.com/CCI-GU-Sweden/spectral-unmixing-microscopy/blob/main/Python/lumic/IO_README.md)
85
+ - **Build a controlled simulation.** Sample reference spectra through a
86
+ detector model, set the component contributions, and render spatial
87
+ shapes with optical blur and noise. Keep the original spectra and
88
+ abundance maps as ground truth for comparing fits.
89
+ [Simulation guide](https://github.com/CCI-GU-Sweden/spectral-unmixing-microscopy/blob/main/Python/lumic/simulation/README.md)
90
+ - **Evaluate a fit.** Align components before comparing spectra and
91
+ abundance maps across runs. When ground truth is unavailable, use signed
92
+ residual PCA and spatial or spectral correlations to look for patterns
93
+ the fit leaves unexplained.
94
+ [Evaluation guide](https://github.com/CCI-GU-Sweden/spectral-unmixing-microscopy/blob/main/Python/lumic/evaluation/README.md)
95
+
96
+ ## License and data attribution
97
+
98
+ Lumic is distributed under the MIT license. The bundled spectra carry their
99
+ FPbase source and attribution notice alongside the CSV files.