.. _Cell-ACDC: https://cell-acdc.readthedocs.io/en/latest/index.html
.. _GitHub: https://github.com/ElpadoCan/SpotMAX/issues
.. _BioImage Model Zoo: https://bioimage.io/#/
.. _mNeonGreen: https://www.fpbase.org/protein/mneongreen/
.. _seel-2023: https://www.nature.com/articles/s41594-023-01091-8
.. _ridge operator: https://scikit-image.org/docs/stable/auto_examples/edges/plot_ridge_filter.html

.. |load-folder| image:: ../images/folder-open.svg
    :width: 20

.. |compute| image:: ../images/compute.png
    :width: 20

.. |cog| image:: ../../../resources/icons/cog.svg
    :width: 20

.. |cog_play| image:: ../../../resources/icons/cog_play.svg
    :width: 20

.. |plus| image:: ../../../resources/icons/math/add.svg
    :width: 20

.. _mtdna-yeast:

Count single mitochondrial DNA nucleoids and quantify mitochondrial network volume
==================================================================================

Expected run time for this demo: few minutes.

In this tutorial we will count the number of mitochondrial DNA nucleoids and we 
will segment the mitochondrial network in 3D as a reference channel. 

For details about the method used to visualize these structures see 
`this publication <seel-2023>`_. 

.. admonition:: Goals

    * Detect and separate highly connected spots
    * Segment network-like structures as reference channel (mitochondrial network)
    * Filter valid spots based on reference channel signal

.. include:: _preliminary_segment_cells.rst

Dataset
-------

To follow this tutorial, download the dataset from 
`here <https://hmgubox2.helmholtz-muenchen.de/index.php/s/AttDZajALPme4nz>`_.

This dataset was published in `this publication <seel-2023>`_. 

After unzipping the downloaded file, you will see the following folder structure::
    
    Position_26
    └── Images
        ├── ASY15-1_0nM-26_s26_acdc_output.csv
        ├── ASY15-1_0nM-26_s26_last_tracked_i.txt
        ├── ASY15-1_0nM-26_s26_metadata.csv
        ├── ASY15-1_0nM-26_s26_mKate.tif
        ├── ASY15-1_0nM-26_s26_mNeon.tif
        ├── ASY15-1_0nM-26_s26_phase_contr.tif
        ├── ASY15-1_0nM-26_s26_segm.npz
        └── ASY15-1_0nM-26_s26_segmInfo.npz

Some of these files are generated by `Cell-ACDC`_ and they will not be discussed here. 

What we can see is that we have 3 ``.tif`` files corresponding to 3 channels 
whose filename end with ``mKate.tif``, ``mNeon.tif``, ``phase_contr.tif``. 

The ``phase_contr`` channel is the channel we used to segment the single cells with 
`Cell-ACDC`_. The resulting segmentation masks are saved in the file ending with 
``segm.npz``. 

The ``mNeon`` channel is the channel where we want to detect the spots. 

The ``mKate`` channel is the labelling of the mitochondrial network and we can 
use it in SpotMAX as the reference channel (more details below). 

.. figure:: ../images/tutorials_mtDNA_mito_yeast_figure.svg
    :align: center

    **A)** Phase contrast channel used for segmentation of the cells. 
    **B)** mNeon channel used to visualize the mitochondrial DNA nucleoids 
    (spots channel). Arrows indicate areas of connected spots. **C)** mKate 
    channel used to label the mitochondrial network (reference channel).

.. tip:: 

    SpotMAX can take advantage of mother-bud (or sister cells) relationships. To 
    annotate the relationship use the `Cell-ACDC`_ software. These annotations 
    are saved in the file ending with ``acdc_output.csv``. 

Loading the dataset
-------------------

Now that we have our dataset with the segmentation file of the cells, we can 
proceed with detecting the spots. 

.. important:: 

    In this tutorial we assume that you are already familiar with the analysis 
    parameters. If not, please read about them here: :ref:`params-desc`.

Click on the |load-folder| ``Load folder`` button on the top-right of the GUI. 
Select the ``Position_26`` folder you downloaded and load the ``mNeon`` channel. 

When the dataset is loaded, you will see on the :ref:`analysis-parameters-tab` 
on the left that some of the parameters have already been filled out. 

Now let's see how we can determine the optimal parameters for this dataset.

Setting up the parameters
-------------------------

The parameters are grouped into separate sections so we will go one by one.

File paths and channels
^^^^^^^^^^^^^^^^^^^^^^^

Since we want to segment the mitochondrial network as a reference channel from 
the ``mKate`` channel, we write 'mKate' in the :confval:`Reference channel end name` parameter. 

If we want to take advantage of the mother-bud (or sister cells) pairings we write 
'acdc_output.csv' in the :confval:`Table with lineage info end name` parameter. 

We can then decide on a :confval:`Run number` (in this case we leave it at 1), and, 
optionally, we can append a text at the end of the output files, for example we 
could write 'tutorial' at in the :confval:`Text to append at the end of the output files`. 

Finally, we select '.csv' for the :confval:`File extension of the output tables`. 

.. _metadata_mtdna_yeast_tutorial:

METADATA
^^^^^^^^

Since some of the metadata is already saved in the file ending with ``metadata.csv`` 
some of the entries were correctly loaded. 

We need to correct the :confval:`Spots reporter emmission wavelength (nm)` to 
509 since the fluorescence probe used to image the mitochondrial DNA is `mNeonGreen`_. 

Now we need to determine the optimal values for the 
:confval:`Spot minimum z-size (μm)` and :confval:`Resolution multiplier in y- and x- direction` 
parameters. These are **important** because if the resulting 
:confval:`Spot (z, y, x) minimum dimensions (radius)` is too low we will detect 
multiple peaks within the same spot. On the other hand, if it is too high, we 
risk to miss the smaller spots. For this tutorial we will use 
``Spot minimum z-size (μm) = 1.0`` and 
``Resolution multiplier in y- and x- direction = 2.0``. 

.. tip::

    The simplest way to determine these values is to use the tools available 
    in the ``Tune parameters tab``. See more instructions in this section 
    :ref:`tune-parameters-tab` and here :confval:`Spot minimum z-size (μm)`. 

Once you have inserted these values you should now see the following at the 
:confval:`Spot (z, y, x) minimum dimensions (radius)` parameter::

    Spot (z, y, x) minimum dimensions (radius)  (1.0, 0.4357, 0.4357) μm
                                                (2.8571, 6.479, 6.479) pxl

Pre-processing
^^^^^^^^^^^^^^

For the pre-processing activating or not the :confval:`Aggregate cells prior analysis` 
will not make any difference becasue we are working with a single mother-daughter 
pair. If we would be working with multiple cells and we already know that some 
of the cells in the image do not have spots activating this parameter might 
be very important (especially if we use ``Thresholding`` for the 
:confval:`Spots segmentation method`). 

We do not need to activate :confval:`Remove hot pixels` because this specific 
dataset does not have any very bright isolated single pixel. 

We leave the :confval:`Initial gaussian filter sigma` to 0.75 because we want to 
activate :confval:`Sharpen spots signal prior detection`. When sharpening is active, 
the gaussian filtered image is not used for detection but only for quantification. 
Using a small gaussian sigma is recommended to remove some of the background 
noise. With a higher sigma the smoothing would be to aggressive, especially 
because we are dealing with low signal-to-noise ratio.  

.. tip:: 
    You can visually inspect the result of every pre-processing filter 
    by pressing on the |compute| compute button beside each filter. 

Reference channel
^^^^^^^^^^^^^^^^^

In this tutorial, as well as detecting the spots, we also want to segment the 
mitochondrial network from the ``mKate`` signal as the reference channel. 
We will then use the resulting segmentation to remove those spots that are 
outside of the mitochondrial network (we are interested in detecting only the 
mitochondrial DNA that is inside the mitochondrial network). 

To this purpose we activate :confval:`Segment reference channel`.

Another important parameter we want to activate is :confval:`Use the ref. channel mask to determine background`. 
This is because we want to keep only those spots that are significantly brighter 
than the ``mKate`` signal in the same area. However, we cannot compare absolute 
intensities between ``mNeon`` and ``mKate`` because they are two different 
fluorophores. Therefore, we need to normalize the two signals before comparing 
them. To do so, SpotMAX will divide the mean of the signal within each spot 
(using the minimum spot size determined in the `metadata_mtdna_yeast_tutorial`_ 
section) by the background median. To determine the background, we want to take 
the median of the pixels that are outside of the spots, but inside of the 
mitochondrial network, hence we activate this parameter.

Next, we turn our attention onto the filters that are available to enhance 
the segmentation accuracy. Since we are dealing with network-like structures, 
a gaussian filter (smoothing) might not be enough. A better filter in this case 
is a `ridge operator`_. These operators take one or more values called ``sigmas`` 
used as scales of the filter. For this specific dataset, we write ``2, 3`` in the 
:confval:`Sigmas used to enhance network-like structures` parameter.   

.. tip:: 

    Selecting the right sigmas for the ridge operator might require some trial 
    and error. Some values that you can test are ``1``, ``2``, ``1, 2``, and 
    ``2, 3``. The more sigmas you use, the longer the computation time. 
    Test these values by both visually inspecting the result of the filter and 
    the result of the segmentation (using the |compute| compute buttons). 

For the :confval:`Ref. channel gaussian filter sigma` parameter instead, we leave 
this one at 0.75 to remove some background noise. 

Now we need to choose whether to use the 'Thresholding' or 'BioImage.IO model' 
for the :confval:`Ref. channel segmentation method`. Since we know that 
'Thresholding' works well in this case we will use that, but feel free to 
experiment with any of the models available at the `BioImage Model Zoo`_. 

Next, to choose the optimal :confval:`Ref. channel threshold function` we click 
on the |compute| button beside the :confval:`Ref. channel segmentation method` 
and we should be able to appreciate that ``thresholding_yen``, ``threshold_otsu``, 
and ``threshold_isodata`` all do a pretty good job at segmenting the mitochondrial 
network. We will proceed with ``thresholding_yen``. 

Finally, we can choose whether to :confval:`Save reference channel segmentation masks` 
and :confval:`Save pre-processed reference channel image`.

Spots channel
^^^^^^^^^^^^^

We are almost done, since this is the last section that we will setup. 

For the :confval:`Spots segmentation method` we know that 'SpotMAX AI' works 
well in this case, but feel free to experiment with 'Thresholding' (which is much faster 
than the neural networks) and with any of the models available at the `BioImage Model Zoo`_.

.. note:: 

    If this is the first time you are using the 'SpotMAX AI' method, SpotMAX will 
    need to install some libraries. Keep an eye on the terminal during this 
    time and check that installation is successful.

After selecting 'SpotMAX AI' you will need to configure the parameters of the 
model. To do so, click on the |cog| cog button beside the parameter. If you 
want more information about the parameters of the AI see this section 
:ref:`ai_params`. For this dataset, we know that the following parameters 
work well:

* **Model type**: 2D
* **Preprocess across experiment**: False
* **Preprocess across timepoints**: False
* **Gaussian filter sigma**: 0.0
* **Remove hot pixels**: False
* **Config yaml filepath**: SpotMAX_v2/spotmax/nnet/config.yaml
* **PhysicalSizeX**: 0.0672498 (same as in the `metadata_mtdna_yeast_tutorial`_)
* **Resolution multiplier yx**: 1.0 
  
Next, we can ignore :confval:`Spot detection threshold function` because we 
are using the 'SpotMAX AI' method.

Now, as we said at the beginning, we want to keep only those spots that are 
significantly higher than the reference channel in the same place. To do so, 
we can take advantage of a couple of features to filter valid spots. One 
way to compare the two signals is to perform a Welch's t-test and keep only 
those spots whose *p-value* of the test is below a certain threshold. Therefore 
at the :confval:`Features and thresholds for filtering true spots` we click on 
the ``Set features or view the selected ones`` button and we expand the 
:ref:`stat-test-vs-ref-ch` group. We then select the ``p-value (t-test)`` feature 
and we click ``Ok``. Next, we select a maximum bound for the *p-value* of 0.025. 
Since this would result in keeping those spots whose mean intensity is both 
significantly and lower then the reference channel, to keep only those that have 
higher mean intensity we click on the |plus| ``Add feature`` button and we 
add the ``t-statistic`` from the :ref:`stat-test-vs-ref-ch` group. Finally, 
we set a minimum bound on the **t-statistic** of 0, meaning that we will 
keep only those spots whose mean intensity is higher than the reference channel. 

Here is how the window to select the features should look like:

.. figure:: ../images/features_and_thresholds_window.png
    :align: center

    Window used to select features and thresholds for filtering true spots.

We now activate :confval:`Optimise detection for high spot density`, and we do 
not activate :confval:`Compute spots size (fit gaussian peak(s))`. 

Finally, we can choose whether to :confval:`Save spots segmentation masks` and 
:confval:`Save pre-processed spots image`. 

.. note:: 

    Since we do not activate :confval:`Compute spots size (fit gaussian peak(s))` 
    we do not need to worry about the paramters in the :ref:`spotfit-params` 
    section. Also, we can leave the :ref:`config-params` section deactivated 
    and we will get asked about it when we run the analysis

Running the analysis
--------------------

Ok, we are finally ready to run the analysis! 

To do so simply click on the |cog_play| ``Run analysis...`` button on the top 
right of the tab. 

SpotMAX will now allow use to save the parameters to an INI configuration file 
and we choose 'Yes'. This way we can load them back into the GUI any time we 
want by clicking on the |load-folder| ``Load parameters from previous analysis...`` 
button on the top-left of the tab. 

Next, SpotMAX will ask us whether we want to select the measurements to save and 
we say 'No, save all the measurements'. 

Then we choose a filename for the parameters file and the folder where to save 
them. We will get a dialogue confirming that parameters where saved with the 
path where they have been saved. We click 'Ok' and we get a reminder 
that the analysis will now run in the terminal and we should keep an eye on that. 

We click on 'Ok, run now!' and we move our attention to the terminal. In the 
terminal we will get asked some last questions about parameters that we did 
not selected and we simply confirm that we want to use the default ones. 

The analysis will now run and the output files will be saved in the 
same folder of the dataset in a new folder called ``SpotMAX_output``. For details 
about the output files see this section :ref:`output-files`. 


Closing remarks
---------------

At the end of the analysis you can go back to the GUI and visualize and 
inspect the results using the tools in the :ref:`inspect-results-tab`. 

That's it! I hope you found this tutorial useful and you can let us know 
if you found mistakes or any other feedback on our `GitHub`_ page or by 
sending us an email at :email:`elpado6872@gmail.com`.

Until next time! 

.. toctree:: 
    :hidden:

    _preliminary_segment_cells.rst
