docs: add basic LMM analysis example (#55)

.gitignore

@@ -107,3 +107,4 @@ _version_save.py
 docs/*.bib.bak
 .idea
 build-recipes/ShapeOut2Launcher.spec
+.Rhistory

docs/scrots/make_scrots_qg_lme4.py

@@ -0,0 +1,53 @@
+"""Screenshots for quick guide R-lme4"""
+import pathlib
+import sys
+
+from PyQt5 import QtCore
+from PyQt5.QtWidgets import QApplication
+from shapeout2.gui.main import ShapeOut2
+from shapeout2.gui import compute
+
+test_data = pathlib.Path(__file__).parent / ".." / ".." / "tests" / "data"
+
+
+app = QApplication(sys.argv)
+
+QtCore.QLocale.setDefault(QtCore.QLocale(QtCore.QLocale.C))
+
+mw = ShapeOut2()
+mw.settings.setValue("check for updates", 0)
+mw.settings.setValue("advanced/check pyqtgraph version", 0)
+
+# build up a session
+mw.on_action_open(test_data / "version_2_5_0_dcor_lme4.so2")
+
+# create dialog manually
+dlg = compute.ComputeSignificance(mw, pipeline=mw.pipeline)
+
+# set the variables
+# treatment rep 1
+dlg.datasets[0].comboBox_group.setCurrentIndex(1)
+# treatment rep 2
+dlg.datasets[1].comboBox_group.setCurrentIndex(1)
+dlg.datasets[0].spinBox_repeat.setValue(2)
+# control rep 1
+pass
+# control rep 2
+dlg.datasets[3].spinBox_repeat.setValue(2)
+# control rep 3
+dlg.datasets[4].spinBox_repeat.setValue(3)
+
+# set the feature
+feat_id = dlg.comboBox_feat.findData("deform")
+dlg.comboBox_feat.setCurrentIndex(feat_id)
+
+dlg.show()
+QApplication.processEvents()
+dlg.grab().save("_qg_lme4_init.png")
+
+dlgr = dlg.on_lme4(ret_dlg=True)
+dlgr.show()
+QApplication.processEvents()
+dlgr.grab().save("_qg_lme4_results.png")
+
+mw.close()

docs/sec_qg_batch_stats.rst

@@ -1,8 +1,8 @@
 .. _sec_qg_batch_stats:
 
-==================
-Compute statistics
-==================
+=======================
+Export statistical data
+=======================
 
 The :ref:`Quick View window <sec_quick_view>` quantifies the statistics for
 the features shown there. If you need access to statistics for more features of

docs/sec_qg_lme4.rst

@@ -0,0 +1,81 @@
+.. _sec_qg_lme4:
+
+=============================================
+Statistical significance testing (R and lme4)
+=============================================
+Since version 2.5.0, Shape-Out 2 allows you to quantify the statistical
+significance (p-value) when comparing two measurement groups. The analysis
+uses linear mixed effects models (LMM) as described in :cite:`Herbig2018`
+and yields results identical to those obtained with Shape-Out 1.
+
+The LMM analysis is performed using the lme4 R package
+and is based on the :ref:`implementation in dclab <dclab:sec_av_lme4>`
+(please read for more information on the options available) which uses
+`rpy2 <https://github.com/rpy2/rpy2/>`_ to connect to R.
+Here, we make use of the dataset :cite:`FigshareLMM` to illustrate this
+functionality.
+
+
+Basic linear mixed models
+-------------------------
+We would like to quantify the difference between human skeletal stem cells
+(SSC) and the human osteosarcoma cell line MG-63 (which is often used as a
+model system for SSCs) using a likelihood ratio test based on LMM.
+
+Please load :download:`this session <../tests/data/version_2_5_0_dcor_lme4.so2>`
+into Shape-Out (via *File | Open Session*). The experimental data are accessed
+from DCOR, so you will need a working internet connection. The session contains
+five datasets:
+
+- SSC_16uls_rep1_20150611.rtdc  (SSC repetition 1)
+- SSC_16uls_rep2_20150611.rtdc  (SSC repetition 2)
+- MG63_pure_16uls_rep1_20150421.rtdc  (MG-63 repetition 1)
+- MG63_pure_16uls_rep2_20150422.rtdc  (MG-63 repetition 2)
+- MG63_pure_16uls_rep3_20150422.rtdc  (MG-63 repetition 3)
+
+In this example, we treat SSC as our "treatment" and MG-63 as our "control".
+These are just group names that remind us that we are comparing one type of
+sample against another type.
+
+Note that the settings for Young's modulus computation have already been
+defined and that the datasets are already filtered with these box filters:
+
+- Porosity (*area_ratio*): 0 to 1.05
+- Area [µm²] (*area_um*): 120 to 550
+- Deformation (*deform*): 0 to 0.1
+
+To perform an LMM analysis, go to *Compute | Statistical significance* and
+set the groups (SSC: treatment; MG63: control) and repetitions (enumeration
+by date-time).
+
+.. image:: scrots/qg_lme4_init.png
+    :target: _images/qg_lme4_init.png
+
+Make sure that the feature "Deformation" is selected and hit *Run R-lme4*. The
+results of the LMM analysis are shown in a new dialog.
+
+.. image:: scrots/qg_lme4_results.png
+    :target: _images/qg_lme4_results.png
+
+The most important numbers are extracted from the report and are shown at
+the top:
+
+- **Fixed effect intercept:**
+  The mean of the parameter chosen for all controls.
+
+- **Fixed effect treatment:**
+  The effect size of the parameter chosen between the mean
+  of all controls and the mean of all treatments.
+
+- **Anova p-value:**
+  The p-value of the ANOVA test.
+
+In the report, you will also find the **Full coefficient table**, which
+shows the effect size of the parameter chosen between control and treatment
+for every single experiment.
+
+We are interested in the p-value, which is 0.01256 for
+Deformation. We repeat the analysis with Area (0.0002183) and Young's
+modulus (0.0002777). The p-values indicate that MG-63 (mean elastic
+modulus 1.26 kPa) cells are softer than SSCs (mean elastic modulus 1.54 kPa)
+:cite:`Herbig2018`.

docs/sec_quick_guides.rst

@@ -10,4 +10,5 @@ Quick Guides
    sec_qg_filtering
    sec_qg_dcor
    sec_qg_youngs_modulus
+   sec_qg_lme4
    sec_qg_batch_stats

docs/shapeout.bib

@@ -130,6 +130,15 @@ @Article{NawUrb2019
   publisher    = {Springer Nature},
 }
 
+@Misc{FigshareLMM,
+  author    = {Xavier, Miguel and Rosendahl, Philipp and Müller, Paul and Herbig, Maik and Guck, Jochen},
+  title     = {Real-time deformability cytometry data of primary human skeletal stem cells and the human osteosarcoma cell line MG-63},
+  month     = {Feb},
+  year      = {2020},
+  doi       = {10.6084/m9.figshare.11662773.v2},
+  publisher = {figshare},
+}
+
 @Misc{NawUrb2019data,
   author    = {Nawaz, Ahmad Ahsan and Urbanska, Marta and Herbig, Maik and Nötzel, Martin and Kräter, Martin and Rosendahl, Philipp and Herold, Christoph and Töpfner, Nicole and Kubankova, Marketa and Goswami, Ruchi and et al.},
   title     = {Sorting real-time fluorescence and deformability cytometry (soRT-FDC) - manuscript data},

shapeout2/gui/compute/comp_lme4_results.py

@@ -29,11 +29,11 @@ def __init__(self, parent, rlme4_results, *args, **kwargs):
         else:
             self.label_yes.hide()
             self.label_no.show()
-        self.lineEdit_pvalue.setText("{:f}".format(res["anova p-value"]))
+        self.lineEdit_pvalue.setText("{:.7g}".format(res["anova p-value"]))
         self.lineEdit_intercept.setText(
-            "{:f}".format(res["fixed effects intercept"]))
+            "{:.7g}".format(res["fixed effects intercept"]))
         self.lineEdit_treatment.setText(
-            "{:f}".format(res["fixed effects treatment"]))
+            "{:.7g}".format(res["fixed effects treatment"]))
 
         # summary text
         summary = []

shapeout2/gui/compute/comp_lme4_results.ui

@@ -91,13 +91,19 @@
        <layout class="QGridLayout" name="gridLayout_2">
         <item row="3" column="0">
          <widget class="QLabel" name="label_3">
+          <property name="toolTip">
+           <string>The effect size of the parameter chosen between the mean of all controls and the mean of all treatments</string>
+          </property>
           <property name="text">
            <string>Fixed effect treatment</string>
           </property>
          </widget>
         </item>
         <item row="2" column="1">
          <widget class="QLineEdit" name="lineEdit_intercept">
+          <property name="toolTip">
+           <string>The mean of the parameter chosen for all controls</string>
+          </property>
           <property name="text">
            <string>nan</string>
           </property>
@@ -108,6 +114,9 @@
         </item>
         <item row="3" column="1">
          <widget class="QLineEdit" name="lineEdit_treatment">
+          <property name="toolTip">
+           <string>The effect size of the parameter chosen between the mean of all controls and the mean of all treatments</string>
+          </property>
           <property name="text">
            <string>nan</string>
           </property>
@@ -118,13 +127,19 @@
         </item>
         <item row="1" column="0">
          <widget class="QLabel" name="label_2">
+          <property name="toolTip">
+           <string>The p-value of the ANOVA test</string>
+          </property>
           <property name="text">
            <string>Anova p-value</string>
           </property>
          </widget>
         </item>
         <item row="2" column="0">
          <widget class="QLabel" name="label_4">
+          <property name="toolTip">
+           <string>The mean of the parameter chosen for all controls</string>
+          </property>
           <property name="text">
            <string>Fixed effect intercept</string>
           </property>
@@ -180,6 +195,9 @@ font-weight:600}</string>
         </item>
         <item row="1" column="1">
          <widget class="QLineEdit" name="lineEdit_pvalue">
+          <property name="toolTip">
+           <string>The p-value of the ANOVA test</string>
+          </property>
           <property name="text">
            <string>nan</string>
           </property>