:orphan:

Examples
========

These runnable examples demonstrate the core workflows of massphoto, organised from fundamental single-molecule analysis to diagnostics and pipeline customisation:

* **Core analysis (1-3)**: Contrast-to-mass calibration, mass distribution fitting, and event landing rate over time.
* **Diagnostics & quality control (4-6)**: Stage drift compensation, noise floor evaluation with averaging windows, and movie properties over time.
* **Pipeline & extensibility (7-9)**: Step-by-step walk-through, custom candidate detection, and reproducible analysis records with replay.

.. admonition:: Benchmark Datasets & Best Practice Protocol

   The sample data used across these examples originates from the benchmark mass photometry
   recordings archived on `Zenodo (10.5281/zenodo.15800729) <https://doi.org/10.5281/zenodo.15800729>`_,
   accompanying Kratochvíl et al., *Nat. Protoc.* (2025), `doi:10.1038/s41596-025-01255-4 <https://doi.org/10.1038/s41596-025-01255-4>`_.

   When running these examples for the first time, required data files (~1 GB total) are downloaded automatically
   from Zenodo and cached locally. An active internet connection is required on the first run;
   if a download times out due to network issues, re-running the command will retry files that were not fully downloaded.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This tutorial demonstrates how to estimate a contrast-to-mass calibration from a calibration movie:">

.. only:: html

  .. image:: /auto_examples/images/thumb/sphx_glr_01-mass_calibration_thumb.png
    :alt:

  :doc:`/auto_examples/01-mass_calibration`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Mass calibration</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to compute and fit mass distributions from a movie once a contrast-to-mass calibration is available:">

.. only:: html

  .. image:: /auto_examples/images/thumb/sphx_glr_02-mass_distribution_thumb.png
    :alt:

  :doc:`/auto_examples/02-mass_distribution`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Mass distribution</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to evaluate single-molecule binding kinetics over time:">

.. only:: html

  .. image:: /auto_examples/images/thumb/sphx_glr_03-event_rate_over_time_thumb.png
    :alt:

  :doc:`/auto_examples/03-event_rate_over_time`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Event rate and landing kinetics</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to correct for sample drift in a movie using the massphoto.correct_drift function.">

.. only:: html

  .. image:: /auto_examples/images/thumb/sphx_glr_04-drift_correction_thumb.png
    :alt:

  :doc:`/auto_examples/04-drift_correction`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Drift correction</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The shot noise curve is a practical tool for characterising the noise floor of a mass photometry measurement. It shows how the standard deviation of the ratiometric signal decreases as a function of the averaging window n_{avg}.">

.. only:: html

  .. image:: /auto_examples/images/thumb/sphx_glr_05-shot_noise_curve_thumb.png
    :alt:

  :doc:`/auto_examples/05-shot_noise_curve`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Shot noise curve</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to extract and inspect frame-level movie properties over time during movie processing:">

.. only:: html

  .. image:: /auto_examples/images/thumb/sphx_glr_06-movie_metrics_thumb.png
    :alt:

  :doc:`/auto_examples/06-movie_metrics`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Movie properties over time</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This tutorial walks through each stage of the mass photometry analysis pipeline individually, using the lower-level API instead of the high-level massphoto.fit. Exposing the intermediate results at every step makes it easier to inspect, tune, and debug the analysis.">

.. only:: html

  .. image:: /auto_examples/images/thumb/sphx_glr_07-step_by_step_pipeline_thumb.png
    :alt:

  :doc:`/auto_examples/07-step_by_step_pipeline`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Step-by-step pipeline</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to implement a custom detection function and use it with massphoto.fit:">

.. only:: html

  .. image:: /auto_examples/images/thumb/sphx_glr_08-custom_detection_thumb.png
    :alt:

  :doc:`/auto_examples/08-custom_detection`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Custom detection function</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Every call to massphoto.fit, massphoto.detect, and massphoto.process automatically attaches an analysis record to the returned DataFrame. This tutorial shows how to:">

.. only:: html

  .. image:: /auto_examples/images/thumb/sphx_glr_09-analysis_record_thumb.png
    :alt:

  :doc:`/auto_examples/09-analysis_record`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Analysis record and replay</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:

   /auto_examples/01-mass_calibration
   /auto_examples/02-mass_distribution
   /auto_examples/03-event_rate_over_time
   /auto_examples/04-drift_correction
   /auto_examples/05-shot_noise_curve
   /auto_examples/06-movie_metrics
   /auto_examples/07-step_by_step_pipeline
   /auto_examples/08-custom_detection
   /auto_examples/09-analysis_record



.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_