PYCORRFIT(1)

📦
version 1.3.1+nopack · 2 versions
, in ubuntu stonking

okay bestie, pull up a chair 💖 this is PYCORRFIT(1), the manual page for PyCorrFit, and we're gonna get through it together. It's a long one, so grab a snack 🍓

🌸 NAME 🌸

PyCorrFit — the PyCorrFit documentation ✨ [image]

Welcome to the docs for PyCorrFit (version 1.3.1+nopack), a data analysis software for fluorescence correlation spectroscopy, aka FCS. No cap, that's the whole vibe. 💅

🧬 ABOUT PYCORRFIT 🧬

So here's the tea, bestie: in current biomedical research, fluorescence correlation spectroscopy (FCS) is applied to characterize molecular dynamic processes in vitro and in living cells. 👑

But the commercial FCS setups? They only let you do data analysis that's locked to one specific instrument — either because of in-house file formats, or because there's just a finite number of correlation model functions implemented. It's giving restrictive. 🚫

PyCorrFit is a general-purpose FCS evaluation software that, amongst other formats, supports the established Zeiss ConfoCor3 ~.fcs file format. It comes with several built-in model functions, covering a wide range of applications in standard confocal FCS. Plus, it contains equations dealing with different excitation geometries like total internal reflection (TIR). Iconic behavior, honestly. 🔥

🖥️ Supported operating systems

  • Windows 7 and higher
  • Linux (Debian-based)
  • Any other operating system with a Python 3.6 installation (via pip)

📁 Supported filetypes

  • ALV correlators (~.ASC)
  • Correlator.com (Flex) correlators (~.SIN)
  • Zeiss ConfoCor3 (~.fcs)
  • PicoQuant (~.pt3) as implemented by Dominic Waithe (https://github.com/dwaithe/FCS_point_correlator)
  • PyCorrFit (~.csv)
  • PyCorrFit session (~.pcfs)

📈 Fitting

  • Pre-defined model functions (confocal FCS, TIR-FCS, triplet blinking, multiple components)
  • Import of user-defined model functions
  • Global fitting across multiple model functions or data sets
  • Least squares fit using Levenberg-Marquard, Simplex, and more
  • Weighted fitting with standard deviation

🛠️ Tools and Features

  • Averaging of curves
  • Background correction
  • Batch processing
  • Overlay tool to identify outliers
  • Fast simulation of model parameter behavior
  • Session management
  • High quality plot export using LaTeX (bitmap or vector graphics)

📝 How to cite

Müller, P., Schwille, P., and Weidemann, T. PyCorrFit - generic data evaluation for fluorescence correlation spectroscopy. Bioinformatics 30(17):2532-2533 (2014). doi:10.1093/bioinformatics/btu328 (http://dx.doi.org/10.1093/bioinformatics/btu328)

aesthetic visual appreciation moment ✨

  • [image] <_images/Screenshot_Desktop.png>
  • [image] <_images/Screenshot_Desktop_Mac.png>
  • [image] <_images/Screenshot_Desktop_Raspbian_Jessie.png>
  • [image] <_images/Screenshot_Desktop_Win.png>
  • [image] <_images/Screenshot_Graphics_output.png>
  • [image] <_images/Screenshot_Main.png>
  • [image] <_images/Screenshot_Select_curves.png>
  • [image] <_images/Screenshot_Trace_view.png>

🚀 GETTING STARTED 🚀

📦 Installation

  • Windows installers for PyCorrFit are available at the release page (https://github.com/FCS-analysis/PyCorrFit/releases). 🪟
  • On Debian-based systems, install via apt-get install pycorrfit.
  • If you have Python 3.6 installed, you may install PyCorrFit via pip install pycorrfit[GUI]. After the installation, type pycorrfit in a command shell to start PyCorrFit. 💫

📚 Documentation

The documentation is in the process of being transferred entirely to readthedocs.org. Currently, it is scattered across several places and it is most-likely outdated: 😭

🫶 CONTRIBUTE 🫶

💬 General remarks

PyCorrFit has no funding and a vanishingly small developer community. The maintainer's personal objective is to keep PyCorrFit operational on Linux and Windows, which is currently limited by the free time available. (real.) 😭

An active community is very important for an open source project such as PyCorrFit. You can help this community grow (and thus help improve PyCorrFit) in numerous ways:

  1. Tell your colleagues and peers about PyCorrFit. One of them might be able to contribute to the project. 🗣️
  2. If you need a new feature in PyCorrFit, publicly announce a bounty for its implementation. 💰
  3. If your research heavily relies on FCS, please consider diverting some of your resources to the development of PyCorrFit.
  4. You don't have to be a Python programmer to contribute. If you are familiar with reStrucuredText or LaTeX, you might be able to help out with the online documentation.
  5. Please cite: Müller et al. Bioinformatics 30(17): 2532–2533, 2014, DOI:10.1093/bioinformatics/btu328 (https://dx.doi.org/10.1093/bioinformatics/btu328)
  6. Sponsor on GitHub (https://github.com/sponsors/paulmueller) or donate via Liberapay (https://liberapay.com/paulmueller). 🎀

If you are planning to contribute to PyCorrFit, please contact the maintainer via the PyCorrFit issue page on GitHub such that you may coordinate a pull request.

✍️ For documentation writers

To build this documentation, fork PyCorrFit, navigate to the docs (not doc) directory and run:

  • pip install -r requirements.txt followed by
  • sphinx-build . _build.

This will create the html documentation on your computer. Syntax warnings and errors will be displayed during the build (there should be none). After making your changes to your forked branch, create a pull request on GitHub.

If you only found a typo or wish to make text-only changes, you can also use the GitHub interface to edit the files (without testing the build step on your computer). 🙈

👩‍💻 For developers

🐍 Running from source

It is recommended to work with virtual environments (https://docs.python.org/3/tutorial/venv.html).

🪟 Windows

The easiest way to run PyCorrFit from source on Windows is Anaconda (http://continuum.io/downloads).

  • conda install matplotlib numpy pip scipy wxpython
  • pip install cython wheel simplejson sympy lmfit
  • pip install -e . # in the root directory of the repository

🐧 Ubuntu Linux

PyCorrFit requires wxPython >= 4.0.1 which is not available as a binary wheel on PyPI. However, the wxPython people have wheels specific to certain Ubuntu versions (https://www.wxpython.org/pages/downloads/):

🧪 Testing

PyCorrFit is tested using pytest. If you have the time, please write test methods for your code and put them in the tests directory. You may run all tests by issuing:

pip install -r tests/requirements
pytest tests

🎯 Pull request guidelines

Please fork PyCorrFit and create a pull request (PR) introducing your changes.

📜 CHANGELOG 📜

List of changes in-between PyCorrFit releases. 🗂️

🎀 version 1.3.1

  • maintenance release

🎀 version 1.3.0

🎀 version 1.2.1

🎀 version 1.2.0

  • enh: add support for PicoQuant cor file format
  • ref: code cleanup
  • setup: modernize build pipeline
  • tests: remove deprecated pytest-runner
  • setup: require Python 3.10

🎀 version 1.1.8

🎀 version 1.1.7

  • docs: add sponsor links to contribute section
  • docs: add gallery with all images in docs/gallery

🎀 version 1.1.6

  • fix: improve support for Confocor FCS file format (see discussion in #37)
  • ref: make pathlib.Path a standard in readfiles
  • code cleanup
  • drop support for Python<3.6

🎀 version 1.1.5

🎀 version 1.1.4

  • maintenance release

🎀 version 1.1.3

  • maintenance release

🎀 version 1.1.2

  • ci: Automated release to PyPI with appveyor and travis-ci
  • fix: support lmfit >= 0.9.11

🎀 version 1.1.1

🎀 version 1.1.0

🎀 version 1.0.1

  • Improved support for ALV ".ASC" file format (#169 https://github.com/FCS-analysis/PyCorrFit/issues/169)
  • NumPy 0.13 support for ".ptu" file reader
  • Code cleanup:
    • Fetch latest available version from GitHub releases
    • New dependency for "simplejson" Python package
    • Move appveyor recipe to separate folder

🎀 version 1.0.0

  • New confocal fitting models T+T+2D and T+T+3D

okay and that's where this part wraps up — but bestie, there is SO much more coming 💅

🎀 version 0.9.9

🌸 version 0.9.8

💫 version 0.9.7

  • Second triplet time is now larger than first triplet time by default
  • Removed a hack that causes a run through all pages e.g. when an average is created
  • Bugfixes:
    • Opening sessions with user-defined models
    • Saving sessions with comments containing non-ASCII characters
    • Windows build: graphical plot export was misconfigured (added matplotlibrc patch in .spec file)

🦋 version 0.9.6

  • Bugfixes:
    • Fixed minor wx sizer problems for the tools
    • Fixed 'AttributeError' in page.py if no weights are present
  • New confocal fitting models (#111 — https://github.com/FCS-analysis/PyCorrFit/issues/111):
    • 3D+3D, 2D+2D, 3D+2D; no triplet
    • T+T+2D+2D, T+T+3D+2D; double triplet
    • T+3D+3D+3D, T+3D+3D+2D (#40, #59)
  • Under the hood:
    • Separation of core and GUI modules
    • Include tests in distributions for PyPI
    • Improve automated testing on Windows and Mac OS
    • More constraint options for fitting

💅 version 0.9.5

⭐ version 0.9.4

🔥 version 0.9.3

  • Fitting: migrated to lmfit
    • This introduces a new dependency for building PyCorrFit. (e.g. in Debian, the package "python-lmfit" is required)
    • Improved fitting behavior at parameter boundaries
    • Removed "Polak-Ribiere" fitting algorithm
    • Added "Sequential Linear Squares Programming" algorithm
  • Heuristic fit (#109 — https://github.com/FCS-analysis/PyCorrFit/issues/109):
    • Detect parameters that are stuck during fitting
    • Fit each curve five times or less and check whether the fit converges.
    • If two diffusion time parameter exist in a model, always make sure that one parameter is the larger one. This feature can currently not be disabled (#110 — https://github.com/FCS-analysis/PyCorrFit/issues/110).
  • Allow infinity ("inf" and "-inf") parameters for models and boundaries.
  • New model: confocal T+T+3D+3D
  • Bugfixes:

🌈 version 0.9.2

  • Bugfixes:
  • Update .pt3 reader to version 8399ff7401
  • Import traces of .pt3 files (experimental, #118)
⚠️ Warning: Absolute values for intensity might be wrong

🫶 version 0.9.1

👑 version 0.9.0

🍓 version 0.8.9

💜 version 0.8.8

  • Improved support for "ALV-7004" files
  • If you install the GUI with pip, you now need to include the 'GUI' requirement: 'pip install pycorrfit[GUI]'. The GUI depends on matplotlib and wxPython which is not required for scripting with the pycorrfit module.
  • Bugfix: missing version string on SuSe linux (#101 — https://github.com/FCS-analysis/PyCorrFit/issues/101)
  • Under the hood:
    • Python entry point script replaces "bin/" script
    • Windows build system hosted by appveyor.com
    • MacOS X build system hosted by travis-ci.org
    • New builds use wxPython3 (#85 — https://github.com/FCS-analysis/PyCorrFit/issues/85)
    • Unicode support without 'reload(sys)'
    • Error messages are more verbose

🌟 version 0.8.7

🧁 version 0.8.6

🎀 version 0.8.5

  • Fixed bug that made it impossible to load data (#88 — https://github.com/FCS-analysis/PyCorrFit/issues/88)
  • Exceptions are now handled by wxPython
  • Under the hood:
    • Pythonic repository structure
    • Relative imports
    • Windows build machine is now Windows 7
    • Removed strict dependency on matplotlib

✨ version 0.8.4

  • Support for PicoQuant data file format — Many thanks to Dominic Waithe (@dwaithe)
  • Improved compatibility with Zeiss .fcs file format
  • PyCorrFit is now dependent on Cython
  • The module 'openfile' is now available from within Python
  • Installer for Windows

💖 version 0.8.3

🌈 version 0.8.2 🌈

  • The documentation has been thoroughly reworked, bestie, like a full glow-up 💖
  • The user is now warned if he does not have a TeX distribution installed 🔔
  • Improvements:
  • Bugfix: TeX did not work on Ubuntu due to missing imports 😭

💖 version 0.8.1 💖

🦋 version 0.8.0 🦋

🌸 version 0.7.9 🌸

  • Support for Mac OSx 🍎
  • Enhancements:
    • Export file format (.csv) layout improved
    • Model function info text in UTF-8
    • Improved waring message when opening sessions from future versions 👀
    • New feature lets user set the range for the fitting parameters
  • Bugfixes:
    • Cleaned minor tracebacks and exceptions created by the frontend
    • Mac version now works as expected, but .app bundling failed 💀
    • Latex plotting features now support more characters such as "[]{}^" ✨

🎀 version 0.7.8 🎀

  • Enhancements:
    • Averages can now be calculated from user-selected pages
    • Pages selected in the Overlay tool are now automatically set for computation of average and for global fitting
    • Source pages are now displayed in average title
    • Graph normalization with particle numbers is now possible
  • Bugfixes:
    • Errors during fitting with weights equal to zero
    • Overlay tool displayed last curve after all pages have been removed 🙈
    • Global fit did not work with weights
  • Session saving now uses 20 digits accuracy 🔢
  • CSV export is now using tab-delimited data for easier Excel-import 📊
  • Added version checking for session management ✅

💜 version 0.7.7 💜

  • Fixed: Tools windows could not be closed (or moved on MS Windows) 🪟
  • Fixed: .csv export failed in some cases where no weights were used
  • Enhancement: The user is now asked before a page is closed 🫶
  • Enhancement: Tool "Page Info" and in exported .csv files, variables and values are now separated by a tab stop instead of a "="
  • Fixed: Opening a session with an empty page failed in some cases
  • Fixed: Tool "Statistics" missed to output the column "filename/title" if that key value is empty — replaced empty strings with "NoName" 👑
  • Enhancement: Tool "Overlay" now asks the user to check kept curves instead of showing the curves to be removed
  • Enhancement: Tool "Overlay" now has a "Cancel" button 🛑

🌟 version 0.7.6 🌟

  • Improved handling
  • Improved tool "Statistics" (#21 — https://github.com/FCS-analysis/PyCorrFit/issues/21) 📊
    • Fixed the case where "useless" data was produced — instead we write "NaN" data, removed warning message accordingly
    • Row-wise ordering according to page numbers (#22 — https://github.com/FCS-analysis/PyCorrFit/issues/22)
    • Column-wise ordering is now more intuitive (Fitted parameters with errors first)
    • Some columns are now checked by default
    • PyCorrFit remembers checked parameters for a page (not saved in session)
  • Improved tool "Overlay" (#23 — https://github.com/FCS-analysis/PyCorrFit/issues/23) 📈
    • New feature: Overlay shows run number of each file (upon import), the run (or index) of an experimental file is unique to PyCorrFit
    • Upon import, filenames and runs are displayed
    • In a session, the filename/title is displayed
  • Web address of PyCorrFit changed from "fcstools.dyndns.org/pycorrfit" to "pycorrfit.craban.de" 🔗 — the glow-up fr fr
  • Minor bugfixes: Batch control, Global fitting, import dialog 🔧

💫 version 0.7.5 💫

  • Added model functions to documentation. 📚
  • Weights from fitting are now exported in .csv files.
  • Rework of info panel for fitting 💅
  • Cleared unintuitive behavior of session saving: The fitting parameters were read from the frontend. This could have led to saving false fit meta data. 😭
  • During fitting, units are now displayed as "human readable" (#17 — https://github.com/FCS-analysis/PyCorrFit/issues/17).
  • Slider simulation now also uses human readable units (#17 — https://github.com/FCS-analysis/PyCorrFit/issues/17).
  • Secured support for Ubuntu 12.10 and 13.04 🐧
  • Fixed: new line (n) characters for LaTeX plotting on Windows 🪟

🍓 version 0.7.4 🍓

  • New tool: Colorful curve selection 🌈
  • Import data: Curve selection possible
  • Average: Crop average according to current page.
  • Fixed: Page now displays Chi-squared of global fit.
  • Fixed: Chi-squared and parameters of global fitting are now stored in sessions. 💾

⭐ version 0.7.3 ⭐

  • Issue closed. External weights from averages saved in session (#11 — https://github.com/FCS-analysis/PyCorrFit/issues/11).
  • Solved minor bugs 🐛
  • Added estimation of errors of fit (Issue #12/#14)
  • Fixed: Some .fcs files containing averages were not imported. 😩

🔥 version 0.7.2 🔥

  • Bugfix: Issue #10; we now have a goodness of the fit, if weighted fitting is performed
  • Bugfix: Weights for fitting not properly calculated (sqrt(std)).
  • Bugfix: Batch control IndexError with Info window opened 💀
  • Tool Statistics: Sort values according to page numbers
  • Tool global: Added weighted fitting
  • Residuals: According to weighted fitting, weighted residuals are plotted
  • Average: Variances from averaging can be used for weighted fitting

🧚 version 0.7.1 🧚

  • Feature: Added Python shell 🐍
  • Bugfix: Saving image was not performed using WXAgg
  • Bugfix: Notebook pages were drag'n'dropable
  • Update function now works in its own thread 🧵
  • Code cleanup: documentation of model functions
  • Added program icon 🎨

👑 version 0.7.0 👑

🌱 version 0.6.9 🌱

  • Initital GitHub commit 🐣 — the origin story, no cap
  • Index
  • Module Index
  • Search Page

👑 Author 👑

Paul Müller

2014, Paul Müller

And that's a wrap on the whole page, bestie 💖 the footer says May 15, 2026 and PYCORRFIT(1) — that's the source date and the manual page name, so you know exactly which version of this lil masterpiece you're reading 🫶✨

📦 where this page comes from