massphoto: from movies to masses ================================================= **massphoto** is an open-source Python package for analysing mass photometry movies, from detecting single-protein events to measuring contrasts and calibrated mass distributions. * **For mass photometry users:** Analyse your measurements directly in Python, keeping your entire workflow transparent, shareable, and fully under your control. * **Simple yet flexible:** Turn raw movies into calibrated mass distributions with a single command, or customise parameters like integration time and PSF shape. * **Open and reproducible:** Automate batch processing across large datasets and output single-molecule events as standard pandas DataFrames to integrate into your analysis pipelines. .. container:: mp-home-actions .. button-ref:: usage :color: primary Get started .. button-ref:: installation :color: primary :outline: Install massphoto .. code-block:: bash :class: mp-home-pip-snippet pip install massphoto .. The four workflow panels below (raw.png, events.png, profile.svg, histogram.svg) are generated build outputs produced by _save_homepage_panels() in docs/source/_examples/02-mass_distribution.py from the public 006_dynamin_6.mp movie. Provenance metadata is stored in auto_examples/images/homepage/provenance.json. To update or regenerate them, edit the hidden block in example 02 and run an executing Sphinx build (without -D plot_gallery=0). .. grid:: 2 2 4 4 :gutter: 4 :class-container: mp-home-workflow .. grid-item:: :class: mp-home-step .. image:: auto_examples/images/homepage/raw.png :alt: Three grayscale frames from the same region of the measured movie. .. rubric:: 1. Raw movie Camera intensity over time .. grid-item:: :class: mp-home-step .. image:: auto_examples/images/homepage/events.png :alt: The same measured region after ratiometric processing, with the fitted event marked. .. rubric:: 2. Reveal events Ratiometric background subtraction & detection .. grid-item:: :class: mp-home-step .. image:: auto_examples/images/homepage/profile.svg :alt: Measured pixel profile through the marked event and its fitted PSF, including side lobes. .. rubric:: 3. Fit events Event positions and contrasts .. grid-item:: :class: mp-home-step .. image:: auto_examples/images/homepage/histogram.svg :alt: Calibrated mass histogram of the full measurement with a fitted distribution. :target: auto_examples/02-mass_distribution.html .. rubric:: 4. Mass distribution Calibrate, filter, and analyse Data from a real mass photometry measurement of dynamin (see the :ref:`detailed analysis tutorial `). The package reads raw mass photometry movies, performs ratiometric background subtraction, detects single-molecule events, fits their point spread functions (PSFs), and returns a table of fitted events with contrasts and calibrated masses. .. admonition:: Best Practice Protocol & Data For comprehensive experimental guidelines, sample preparation protocols, and calibration strategies, see: Kratochvíl et al., *Best practice mass photometry: a guide to optimal single-molecule mass measurement*, Nature Protocols **2025**, `(10.1038/s41596-025-01255-4) `_. The benchmark datasets used in this documentation are part of this study and are available on `Zenodo (10.5281/zenodo.15800729) `_. **massphoto** is designed for simplicity: a single command turns a movie into a calibrated event table, while every stage - drift correction, background subtraction, candidate detection, and PSF fitting - can be configured and customised. Results are returned as standard pandas DataFrames with complete metadata: .. code-block:: python import massphoto as mp df = mp.fit("./protein_measurement.mp") Each row of the returned DataFrame describes one fitted single-molecule event: .. raw:: html
frame x y contrasts masses_kDa
0 20 86.09 6.87 0.00343 101.2
1 20 165.06 72.34 0.00604 182.1
2 20 205.38 74.17 0.00648 195.8
3 20 124.95 80.87 0.00580 174.5
4 20 189.78 93.18 0.01202 367.4
To include mass columns, first set your :ref:`mass calibration ` in ``mp.defaults``. Without calibration, you can still inspect fitted contrasts. The :doc:`usage guide ` explains the processing stages, result columns, and choices that affect your analysis. The examples provide complete recipes. Explore the code examples ------------------------- Walk through runnable Python scripts and downloadable Jupyter notebooks covering typical mass photometry workflows (see the full :doc:`example gallery `): .. grid:: 1 1 3 3 :gutter: 3 .. grid-item-card:: Calibrate a measurement :link: sphx_glr_auto_examples_01-mass_calibration.py :link-type: ref .. raw:: html Code example showing how to turn known reference masses into a contrast-to-mass calibration and check the resulting mass scale. .. grid-item-card:: Analyse a sample :link: sphx_glr_auto_examples_02-mass_distribution.py :link-type: ref .. raw:: html Code example going from a raw movie to a calibrated mass distribution, including fit quality filtering, and peak fitting. .. grid-item-card:: Step-by-step pipeline :link: sphx_glr_auto_examples_07-step_by_step_pipeline.py :link-type: ref .. raw:: html Walk-through of each processing stage individually to inspect intermediate results and tune parameters for your measurement. Feedback & Community -------------------- Encountered a bug, working with an unsupported instrument or file format, or have a feature request? Please open an issue on the `GitHub Issue Tracker `_! .. toctree:: :hidden: :maxdepth: 2 :caption: Contents: installation usage auto_examples/index api/index contributing .. container:: mp-home-index-links :ref:`genindex` · :ref:`modindex` · :ref:`search`