Merge pull request #19 from Fluorescence-Tools/development

Development

.appveyor.yml

@@ -11,7 +11,15 @@ environment:
 #  - ps: iex ((new-object net.webclient).DownloadString('https://raw.githubusercontent.com/appveyor/ci/master/scripts/enable-rdp.ps1'))
 
 install:
+  ##################################################
+  # Install packages for docs.
+  # i#4000: choco fails to download doxygen.portable so we install ourselves:
+  - appveyor DownloadFile http://doxygen.nl/files/doxygen-1.8.17.windows.x64.bin.zip
+  - 7z x doxygen-1.8.17.windows.x64.bin.zip -oc:\projects\install\doxygen > nul
+  - set PATH=c:\projects\install\doxygen;%PATH%
   - "SET PATH=%PYTHON%;%PYTHON%\\Scripts;%PATH%"
+  ##################################################
+  # Build conda package
   - conda config --set always_yes yes --set changeps1 no
   - conda update -q conda
   - conda create -n build python=3.7 git conda-build anaconda-client numpy conda-verify ripgrep

.travis.yml

@@ -8,6 +8,15 @@ matrix:
     - os: osx
       osx_image: xcode9.4
 
+# The Sphinx C++ docs are build with doxygen and breathe
+addons:
+  apt:
+    packages:
+      - doxygen
+  homebrew:
+    packages:
+      - doxygen
+
 env:
   # Build and test package on all supported python versions
   - BUILD_TARGET=3.7 MINICONDA_VERSION=latest
@@ -57,8 +66,7 @@ after_success:
       cd docs
       conda env create -f environment.yml
       conda activate docs_env
-      conda install doxygen -c conda-forge
-      # Use Sphinx to make the html docs the doxygen docs are build with breathe
+      # Build Sphinx docs
       make clean
       make html
       touch _build/html/.nojekyll

CMakeLists.txt

@@ -16,7 +16,7 @@ SET(CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake;${CMAKE_MODULE_PATH}")
 IF(CMAKE_BUILD_TYPE STREQUAL "Release")
     MESSAGE("Release build")
     ADD_DEFINITIONS("-DVERBOSE=0")
-ELSE(CMAKE_BUILD_TYPE STREQUAL "Release")
+ELSE(CMAKE_BUILD_TYPE STREQUAL "Debug")
     MESSAGE("Debug build")
     ADD_DEFINITIONS("-DVERBOSE=1")
 ENDIF(CMAKE_BUILD_TYPE STREQUAL "Release")

conda-recipe/meta.yaml

@@ -9,7 +9,7 @@ source:
 
 build:
     number: 0
-    string: np{{ CONDA_NPY }}py{{ CONDA_PY }}_{{ GIT_BUILD_STR }}
+    string: np{{ CONDA_NPY }}py{{ CONDA_PY }}_{{ data.get('GIT_BUILD_STR', "0")|lower }}
 
 requirements:
   host:

docs/conf.py

@@ -33,28 +33,31 @@
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
-# needs_sphinx = '1.0'
+needs_sphinx = '1.8.5'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.mathbase',
-    'matplotlib.sphinxext.only_directives',
+    # 'sphinx.ext.mathbase',
+    # 'matplotlib.sphinxext.only_directives',
     'matplotlib.sphinxext.plot_directive',
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
+    'sphinx.ext.autodoc',
     'sphinxcontrib.bibtex',
     'recommonmark',
-    'sphinx.ext.autosectionlabel'
+    'sphinx.ext.autosectionlabel',
+    'sphinx.ext.intersphinx'
 ]
 
 
 breathe_projects = {}
 # latex and breathe do not play very well together. Therefore
 # breathe is only used for the webpage.
 # compatible with readthedocs online builder and local builder
-if sys.argv[0].endswith('sphinx-build') and ('html' in sys.argv or sys.argv[-1] == '_build/html'):
+if sys.argv[0].endswith('sphinx-build') and \
+        ('html' in sys.argv or sys.argv[-1] == '_build/html'):
     subprocess.call('doxygen', shell=True)
     breathe_projects['tttrlib'] = './_build/xml'
     breathe_default_project = "tttrlib"
@@ -113,8 +116,9 @@
         html_theme_path = sphinx_rtd_theme.get_html_theme_path()
     html_theme = 'sphinx_rtd_theme'
 
+
 def setup(app):
-    app.add_stylesheet("fix_rtd.css")
+    app.add_css_file("fix_rtd.css")
 
 
 # Theme options are theme-specific and customize the look and feel of a theme

docs/correlation.rst

@@ -1,9 +1,8 @@
-Correlation
-===========
+Fluorescence correlation
+========================
 
 Creating correlators
 --------------------
-
 ``tttrlib`` offers a set of correlators via a unified interface for correlations
 of TTTR data. To correlate ``TTTR`` objects, first a TTTR dataset should be
 loaded. Next, a ``Correlator`` object needs to be created. There are different
@@ -107,7 +106,6 @@ via the ``correlation`` attribute of the correlator is accessed.
 
 Correlators options
 -------------------
-
 The default correlation algorithm follows a multi-tau correlation algorithm. Here,
 two parameters control the correlation range, i.e, the maximum correlation time
 and the number of correlation points: ``n_bins`` and ``n_casc``. In a multiple
@@ -136,22 +134,26 @@ is used.
 
 Examples
 --------
-
 Below are a few examples how the correlator con be used in conjuncture with
 tttrlib. The given examples can be used as templates to develop other correlation
 analysis procedures.
 
 Normal correlations
 +++++++++++++++++++
-
 As described previously there are several analogous possibilities to compute
 correlations. Two possibilities are shown in the example below.
 
 .. plot:: plots/correlation_normal.py
 
+Analysing such correlation functions informs on diffusion and fast kinetics. Such
+correlation functions can be analyzed by dedicated open tools for fluorescence
+such as `ChiSurf <https://github.com/fluorescence-tools/chisurf/>`_,
+`PyCorrFit <https://github.com/FCS-analysis/PyCorrFit>`_, and
+`PAM <https://github.com/fluorescence-tools/pam>`_ or generic curve analysis
+software.
+
 Count rate filer
 ++++++++++++++++
-
 Low count rate parts of a TTTR file can be discriminated. The example below
 displays the correlation analysis of a single molecule FRET experiment. Note,
 the background has a significant contribution to the unfiltered correlation
@@ -160,6 +162,9 @@ certain amount of photons are discriminated by the selection.
 
 .. plot:: plots/correlation_cr_filter.py
 
+Such a filter can be used to remove the background in a single-molecule experiment
+that decreased the correlation amplitude.
+
 
 Micro time gating
 +++++++++++++++++
@@ -174,12 +179,28 @@ Micro time gating
 
 Full correlation
 ++++++++++++++++
+When processes faster than the macro time clock are of interest, the micro time
+and the macro time can be combined into a united time axis. Using the combined
+time axis a so called full correlation can be performed using cw excitation.
 
 .. plot:: plots/correlation_gating.py
 
+Above is an example how a full correlation can be computed. Note, in the example
+the full correlation is computed for a sample that was measured in a pulsed
+excitation experiment. However, the same procedure can be applied to cw data.
+
+
+Slice and correlate
++++++++++++++++++++
+In some cases it can be advantages to slice the data into sub-sets and correlate
+the subsets individually in particular if the average intensity in the sample
+is not stable, e.g. when measuring in cells.
+
+.. plot:: plots/correlation_slice.py
 
-Filtering aggregates
-++++++++++++++++++++
+The By comparing the correlations of the subsets a filter can be defined that
+discriminates outlines. For details on how such a filter can be determined
+see :cite:`Ries2010`.
 
 
 Lifetime filters
@@ -188,7 +209,6 @@ Lifetime filters
 
 Estimating the noise of the correlation curves
 ++++++++++++++++++++++++++++++++++++++++++++++
-
 There are many approaches to calculate the noise in correlation functions
 (see: :cite:`Wohland2001`, :cite:`Qian1990`, :cite:`Starchev2001`). An
 analytical calculation of the noise is not possible because it involves diverging

docs/environment.yml

@@ -6,6 +6,8 @@ dependencies:
     - tttrlib
     # the versions are all pinned to reduce the memory load by conda
     # without that, the docs would not build on read the docs
+    - numba=0.48.0
+    - scipy=1.4.1
     - blas=1.0
     - bzip2=1.0.8
     - ca-certificates=2020.1.1
@@ -36,7 +38,6 @@ dependencies:
     - xz=5.2.4
     - zlib=1.2.11
     - pip:
-      - sphinx-bootstrap-theme==0.7.1
       - babel==2.8.0
       - chardet==3.0.4
       - commonmark==0.9.1
@@ -49,7 +50,8 @@ dependencies:
       - latexcodec==2.0.0
       - markupsafe==1.1.1
       # matplotlib=2.2.3 because matplotlib.sphinxext was removed in matplotlib 3.x.x
-      - matplotlib==2.2.3
+        #      - matplotlib==2.2.3
+      - matplotlib==3.1.3
       - numpy==1.18.1
       - numpydoc==0.9.2
       - oset==0.1.3
@@ -64,7 +66,8 @@ dependencies:
       - recommonmark==0.6.0
       - requests==2.23.0
       - snowballstemmer==2.0.0
-      - sphinx==1.8.5
+      - sphinx==2.4.4
+      - sphinx-bootstrap-theme==0.7.1
       - sphinx-rtd-theme==0.4.3
       - sphinxcontrib-bibtex==1.0.0
       - sphinxcontrib-websupport==1.2.1

docs/examples/tttr_correlation_cr_filter.py

@@ -13,12 +13,12 @@
 mt = data.get_macro_time()
 
 # This selects the indices of the first routing channel 0
-ch1_indeces = data.get_selection_by_channel(np.array([0]))
+ch1_indeces = data.get_selection_by_channel([0])
 t1 = mt[ch1_indeces]
 w1 = np.ones_like(t1, dtype=np.float)
 
 # This selects the indices of the routing channel 8
-ch2_indeces = data.get_selection_by_channel(np.array([8]))
+ch2_indeces = data.get_selection_by_channel([8])
 t2 = mt[ch2_indeces]
 w2 = np.ones_like(t1, dtype=np.float)
 

docs/examples/tttr_correlation_simple.py

@@ -9,12 +9,12 @@
 
 # make a cross-correlation between the two green channels (ch 0, ch 8)
 # This selects the indices of the first routing channel 0
-ch1_indeces = data.get_selection_by_channel(np.array([0]))
+ch1_indeces = data.get_selection_by_channel([0])
 t1 = mt[ch1_indeces]
 w1 = np.ones_like(t1, dtype=np.float)
 
 # This selects the indices of the routing channel 8
-ch2_indeces = data.get_selection_by_channel(np.array([8]))
+ch2_indeces = data.get_selection_by_channel([8])
 t2 = mt[ch2_indeces]
 w2 = np.ones_like(t1, dtype=np.float)
 

docs/examples/tttr_read.py

@@ -52,7 +52,7 @@
 # time(tttrlib)   = 690 ms               # 270 Mb file -> 391 MB/sec
 
 r = spc132
-ch0 = r.get_indeces_by_channels(np.array([0]))
+ch0 = r.get_indeces_by_channels([0])
 p.hist(r.micro_times[ch0], bins=np.linspace(1, 2000))
 
 ch1 = r.get_indeces_by_channels(np.array([2]))

docs/examples/tttr_selection.py

@@ -8,7 +8,7 @@
 data = tttrlib.TTTR('../../data/PQ/PTU/PQ_PTU_HH_T3.ptu', 'PTU')
 data.get_macro_time()
 
-ch1_indeces = data.get_selection_by_channel(np.array([0]))
+ch1_indeces = data.get_selection_by_channel([0])
 p2 = tttrlib.TTTR(data, ch1_indeces)
 ch0 = p2.get_macro_time()
 

docs/glossary.rst

@@ -17,9 +17,11 @@ Glossary
         Meaning the fluorescence lifetime of the corresponding donor fluorescence quantum yield, :math:`\Phi_{F}^{D0}`
         should be used.
 
-    CLSM confocal laser scanning microscopy
+    CLSM
+        confocal laser scanning microscopy
 
-    PDA Photon Distribution Analysis
+    PDA
+        Photon Distribution Analysis
 
     MFD (Multiparameter Fluorescence Detection)
         A MFD experiments is a time-resolved fluorescence experiment which probes the absorption and fluorescence,