.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/03-event_rate_over_time.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_auto_examples_03-event_rate_over_time.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_examples_03-event_rate_over_time.py:


Event rate and landing kinetics
===============================

This example demonstrates how to evaluate single-molecule binding kinetics over time:

1. Download an example movie and apply contrast-to-mass calibration.
2. Run detection and PSF fitting with :func:`massphoto.fit`.
3. Filter events by fit quality using ``DataFrame.query()``.
4. Plot molecular mass vs. acquisition frame.
5. Compute and plot the event landing rate over time.

.. GENERATED FROM PYTHON SOURCE LINES 13-15

.. code-block:: Python
   :dedent: 1










.. GENERATED FROM PYTHON SOURCE LINES 17-19

Imports and Setup
-----------------

.. GENERATED FROM PYTHON SOURCE LINES 19-38

.. code-block:: Python


    import matplotlib.pyplot as plt
    import numpy as np
    from zenodozipdownloader import ZenodoZipDownloader

    import massphoto as mp

    # Download example movie from Zenodo
    files = ZenodoZipDownloader(
        doi="10.5281/zenodo.15800729",
        download_dir="example_data",
    ).download("Figure 2.zip/006_dynamin_6.mp")
    if not files:
        raise RuntimeError(
            "Failed to download example data. Please download it manually from https://zenodo.org/record/15800729 "
            "or set path_movie to your own movie."
        )
    path_movie = files[0]








.. GENERATED FROM PYTHON SOURCE LINES 39-43

Process the Movie
-----------------

Configure mass calibration, disable progress bars for clean output in the docs, and run :func:`massphoto.fit`:

.. GENERATED FROM PYTHON SOURCE LINES 43-51

.. code-block:: Python


    mp.defaults.set("progress_bar", False)
    mp.defaults.set("mass_calibration", (-5.2, 3.1e4))

    movie, metadata = mp.read_movie(path_movie, convert_metadata=True)
    fitres = mp.fit(movie)









.. GENERATED FROM PYTHON SOURCE LINES 52-57

Mass vs. Frame (Landing Events over Time)
-----------------------------------------

A scatter plot of mass against frame reveals individual landing events as they occur.
Stable bands confirm constant calibration and mass populations across the acquisition:

.. GENERATED FROM PYTHON SOURCE LINES 57-67

.. code-block:: Python


    fig, ax = plt.subplots(figsize=(7, 3.5))
    ax.scatter(fitres["frame"], fitres["masses_kDa"], s=10, alpha=0.35)
    ax.set_xlabel("Frame number")
    ax.set_ylabel("Mass (kDa)")
    ax.set_ylim(-50, 700)
    ax.grid(True, linestyle="--", alpha=0.4)
    plt.tight_layout()
    plt.show()




.. image-sg:: /auto_examples/images/sphx_glr_03-event_rate_over_time_001.png
   :alt: 03 event rate over time
   :srcset: /auto_examples/images/sphx_glr_03-event_rate_over_time_001.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 68-72

Event Landing Rate over Time
----------------------------

To detect surface saturation or sample depletion, it can be useful to inspect the landing rate of events over time.

.. GENERATED FROM PYTHON SOURCE LINES 72-94

.. code-block:: Python


    window_size = 10  # frames
    min_frame = int(fitres["frame"].min())
    max_frame = int(fitres["frame"].max())
    bins = np.arange(min_frame - 0.5, max_frame + 1)
    counts, bin_edges = np.histogram(fitres["frame"], bins=bins)
    bin_centers = (bin_edges[:-1] + bin_edges[1:]) / 2
    counts_smooth = np.convolve(counts, np.ones(window_size) / window_size, mode="same")

    # The metadata contains the effective frame rate, which allows us to define a time axis and convert counts per frame to counts per second:
    time = bin_centers / metadata["framerate_effective"]
    counts_smooth *= metadata["framerate_effective"]

    fig, ax = plt.subplots(figsize=(7, 3.5))
    ax.plot(time, counts_smooth, label="Landing rate")
    ax.set_xlabel("Time (s)")
    ax.set_ylabel("Events / s")
    ax.set_ylim(bottom=0)
    ax.grid(True, linestyle="--", alpha=0.4)
    ax.legend(frameon=False)
    plt.tight_layout()
    plt.show()



.. image-sg:: /auto_examples/images/sphx_glr_03-event_rate_over_time_002.png
   :alt: 03 event rate over time
   :srcset: /auto_examples/images/sphx_glr_03-event_rate_over_time_002.png
   :class: sphx-glr-single-img






.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 17.110 seconds)


.. _sphx_glr_download_auto_examples_03-event_rate_over_time.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: 03-event_rate_over_time.ipynb <03-event_rate_over_time.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: 03-event_rate_over_time.py <03-event_rate_over_time.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: 03-event_rate_over_time.zip <03-event_rate_over_time.zip>`


.. only:: html

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

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