docs: add differential feature analysis LMM (#55)

docs/scrots/make_scrots_qg_lme4.py

@@ -29,7 +29,7 @@
 dlg.datasets[0].comboBox_group.setCurrentIndex(1)
 # treatment rep 2
 dlg.datasets[1].comboBox_group.setCurrentIndex(1)
-dlg.datasets[0].spinBox_repeat.setValue(2)
+dlg.datasets[1].spinBox_repeat.setValue(2)
 # control rep 1
 pass
 # control rep 2

docs/scrots/make_scrots_qg_lme4_diff.py

@@ -0,0 +1,65 @@
+"""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_diff.so2")
+
+# create dialog manually
+dlg = compute.ComputeSignificance(mw, pipeline=mw.pipeline)
+
+# set the variables
+# 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[1].spinBox_repeat.setValue(2)
+# res treatment rep 1
+dlg.datasets[2].comboBox_group.setCurrentIndex(1)
+# res treatment rep 2
+dlg.datasets[3].comboBox_group.setCurrentIndex(1)
+dlg.datasets[3].spinBox_repeat.setValue(2)
+# control rep 1
+pass
+# control rep 2
+dlg.datasets[5].spinBox_repeat.setValue(2)
+# control rep 3
+dlg.datasets[6].spinBox_repeat.setValue(3)
+# res control rep 1
+pass
+# res control rep 2
+dlg.datasets[8].spinBox_repeat.setValue(2)
+# res control rep 3
+dlg.datasets[9].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_diff_init.png")
+
+dlgr = dlg.on_lme4(ret_dlg=True)
+dlgr.show()
+QApplication.processEvents()
+dlgr.grab().save("_qg_lme4_diff_results.png")
+
+mw.close()

docs/sec_qg_lme4.rst

@@ -33,6 +33,11 @@ five datasets:
 - MG63_pure_16uls_rep2_20150422.rtdc  (MG-63 repetition 2)
 - MG63_pure_16uls_rep3_20150422.rtdc  (MG-63 repetition 3)
 
+.. note:: The data sets are ordered according to run index. In an ideal case,
+    the run index would resemble the repetition of an experiment. Here,
+    however, the run index is only an internal lab book reference.
+
+
 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.
@@ -79,3 +84,31 @@ 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`.
+
+
+LMM analysis of differential deformation
+----------------------------------------
+To check whether the deformation we see is not just an inherent deformation
+(visible in the reservoir data), we would like to perform a differential feature
+analysis.
+
+Please load :download:`this session <../tests/data/version_2_5_0_dcor_lme4_diff.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
+ten datasets (reservoir measurements in addition to the measurements above).
+
+As in the example above, go to *Compute | Statistical significance* and
+set the groups and repetitions.
+
+.. image:: scrots/qg_lme4_diff_init.png
+    :target: _images/qg_lme4_diff_init.png
+
+The results of the LMM analysis for differential deformation are:
+
+.. image:: scrots/qg_lme4_diff_results.png
+    :target: _images/qg_lme4_diff_results.png
+
+The p-value for the differential deformation is magnitudes lower than the
+p-value for the (non-differential) deformation in the previous example.
+This indicates that there is a non-negligible initial deformation of the
+cells in the reservoir.

tests/test_gui_lme4.py

@@ -1,5 +1,6 @@
 """Test lme4 functionality"""
 import pathlib
+import socket
 
 from shapeout2.gui.main import ShapeOut2
 from shapeout2 import session
@@ -8,6 +9,13 @@
 
 
 data_path = pathlib.Path(__file__).parent / "data"
+with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+    try:
+        s.connect(("www.python.org", 80))
+        NET_AVAILABLE = True
+    except socket.gaierror:
+        # no internet
+        NET_AVAILABLE = False
 
 
 @pytest.fixture(autouse=True)
@@ -20,6 +28,7 @@ def run_around_tests():
     session.clear_session()
 
 
+@pytest.mark.skipif(not NET_AVAILABLE, reason="No network connection!")
 def test_lme4_with_dcor_session(qtbot):
     """
     Open a session with DCOR data and perform lme4 analysis from
@@ -38,7 +47,7 @@ def test_lme4_with_dcor_session(qtbot):
     dlg.datasets[0].comboBox_group.setCurrentIndex(1)
     # treatment rep 2
     dlg.datasets[1].comboBox_group.setCurrentIndex(1)
-    dlg.datasets[0].spinBox_repeat.setValue(2)
+    dlg.datasets[1].spinBox_repeat.setValue(2)
     # control rep 1
     pass
     # control rep 2
@@ -52,4 +61,57 @@ def test_lme4_with_dcor_session(qtbot):
 
     dlgr = dlg.on_lme4(ret_dlg=True)
 
-    assert dlgr.lineEdit_pvalue.text() == "0.012969"
+    assert dlgr.label_model.text() == "lmer"
+    assert dlgr.label_feature.text() == "Deformation"
+    assert dlgr.label_differential.text() == "No"
+    assert dlgr.lineEdit_pvalue.text() == "0.012558"
+
+
+@pytest.mark.skipif(not NET_AVAILABLE, reason="No network connection!")
+def test_lme4_with_dcor_session_differential(qtbot):
+    """
+    Perform differential deformation test
+    """
+    mw = ShapeOut2()
+    qtbot.addWidget(mw)
+    mw.on_action_open(data_path / "version_2_5_0_dcor_lme4_diff.so2")
+
+    # create dialog manually
+    dlg = 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[1].spinBox_repeat.setValue(2)
+    # res treatment rep 1
+    dlg.datasets[2].comboBox_group.setCurrentIndex(1)
+    # res treatment rep 2
+    dlg.datasets[3].comboBox_group.setCurrentIndex(1)
+    dlg.datasets[3].spinBox_repeat.setValue(2)
+    # control rep 1
+    pass
+    # control rep 2
+    dlg.datasets[5].spinBox_repeat.setValue(2)
+    # control rep 3
+    dlg.datasets[6].spinBox_repeat.setValue(3)
+    # res control rep 1
+    pass
+    # res control rep 2
+    dlg.datasets[8].spinBox_repeat.setValue(2)
+    # res control rep 3
+    dlg.datasets[9].spinBox_repeat.setValue(3)
+
+    # set the feature
+    feat_id = dlg.comboBox_feat.findData("deform")
+    dlg.comboBox_feat.setCurrentIndex(feat_id)
+
+    dlgr = dlg.on_lme4(ret_dlg=True)
+
+    assert dlgr.label_model.text() == "lmer"
+    assert dlgr.label_feature.text() == "Deformation"
+    assert dlgr.label_differential.text() == "Yes"
+    assert dlgr.lineEdit_pvalue.text() == "0.0000035055"
+    assert dlgr.lineEdit_intercept.text() == "0.020509"
+    assert dlgr.lineEdit_treatment.text() == "-0.0052991"