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.
- lumic-0.1.0rc1/LICENSE +21 -0
- lumic-0.1.0rc1/PKG-INFO +139 -0
- lumic-0.1.0rc1/README.md +99 -0
- lumic-0.1.0rc1/__init__.py +528 -0
- lumic-0.1.0rc1/_nnls.py +142 -0
- lumic-0.1.0rc1/evaluation/__init__.py +18 -0
- lumic-0.1.0rc1/evaluation/correlation.py +143 -0
- lumic-0.1.0rc1/evaluation/maps.py +166 -0
- lumic-0.1.0rc1/evaluation/metrics.py +319 -0
- lumic-0.1.0rc1/evaluation/residuals.py +248 -0
- lumic-0.1.0rc1/evaluation/sampling.py +202 -0
- lumic-0.1.0rc1/fpbase.py +84 -0
- lumic-0.1.0rc1/image.py +548 -0
- lumic-0.1.0rc1/io.py +948 -0
- lumic-0.1.0rc1/lumic.egg-info/PKG-INFO +139 -0
- lumic-0.1.0rc1/lumic.egg-info/SOURCES.txt +68 -0
- lumic-0.1.0rc1/lumic.egg-info/dependency_links.txt +1 -0
- lumic-0.1.0rc1/lumic.egg-info/requires.txt +30 -0
- lumic-0.1.0rc1/lumic.egg-info/top_level.txt +1 -0
- lumic-0.1.0rc1/pyproject.toml +57 -0
- lumic-0.1.0rc1/readers.py +86 -0
- lumic-0.1.0rc1/setup.cfg +4 -0
- lumic-0.1.0rc1/simulation/__init__.py +33 -0
- lumic-0.1.0rc1/simulation/detector.py +135 -0
- lumic-0.1.0rc1/simulation/fpbase_data/README.md +54 -0
- lumic-0.1.0rc1/simulation/fpbase_data/ebfp2_emission.csv +202 -0
- lumic-0.1.0rc1/simulation/fpbase_data/egfp_emission.csv +239 -0
- lumic-0.1.0rc1/simulation/fpbase_data/mcherry_emission.csv +252 -0
- lumic-0.1.0rc1/simulation/fpbase_data/mneptune_emission.csv +223 -0
- lumic-0.1.0rc1/simulation/mixing.py +39 -0
- lumic-0.1.0rc1/simulation/noise.py +29 -0
- lumic-0.1.0rc1/simulation/psf.py +76 -0
- lumic-0.1.0rc1/simulation/render.py +135 -0
- lumic-0.1.0rc1/simulation/result.py +45 -0
- lumic-0.1.0rc1/simulation/scene.py +162 -0
- lumic-0.1.0rc1/simulation/simulate.py +77 -0
- lumic-0.1.0rc1/simulation/spatial.py +105 -0
- lumic-0.1.0rc1/simulation/spectra.py +60 -0
- lumic-0.1.0rc1/uniqueness.py +411 -0
- 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.
|
lumic-0.1.0rc1/PKG-INFO
ADDED
|
@@ -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.
|
lumic-0.1.0rc1/README.md
ADDED
|
@@ -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.
|