Merge branch 'plot-violin' into develop

doc/contribute/how_to.rst

@@ -27,4 +27,24 @@ A recommended workflow for contributing to ``FlowCal`` is as follows:
 5. Set up your virtual environment, if desired.
 6. Install ``FlowCal`` in developer mode, using ``python setup.py develop``.
 7. Write/test code, commit. Repeat until feature is fully implemented.
-8. Push and submit a merge request towards ``develop``.
+8. Push and submit a merge request towards ``develop``.
+
+Version Policy
+--------------
+The version number in ``FlowCal`` is organized as follows: ``MAJOR.MINOR.PATCH``. The following are guidelines on how to manage version numbers:
+
+* The patch version number should only be increased after fixing a bug or an incompatibility issue, if the public API was not modified at all.
+
+* The minor version number should be increased after a relatively minor API modification. For example:
+
+   * After fixing a bug, when a minor API modification was required to do so.
+   * After making a small adjustment to a function signature, such as adding a new argument or changing the data type of an existing one.
+   * After adding one or more relatively minor new features (e.g. a new plotting function).
+
+* The major version number should be increased after a fundamental modification to the API and/or the package, or the introduction of a major feature. For example:
+
+   * After completely reorganizing the FCSData object or the functions in the package
+   * After introducing a new Excel UI with a completely reorganized input file format.
+   * After introducing a Graphical User Interface.
+
+In general, new patch versions should not break a user's code, whereas minor versions should not require more than minor adjustments. Major versions could either require significant changes in the user's code or a complete change in the way they think about ``FlowCal``'s API.

doc/excel_ui/input_format.rst

@@ -12,7 +12,7 @@ Instruments sheet
 
 This sheet must be filled with basic information about the flow cytometer used to acquire the samples. Each row represents an instrument. Typically, the user would only need to specify one instrument. However, ``FlowCal`` allows the simultaneous processing of samples taken with different instruments. The figure below shows an example of an **Instruments** sheet.
 
-.. image:: https://www.dropbox.com/s/jgmgbgc2rbwagle/input_instruments.png?raw=1
+.. image:: /_static/img/excel_ui/input_instruments.png
 
 For each row, the following columns must be filled.
 
@@ -28,7 +28,7 @@ Beads sheet
 
 This sheet contains details about calibration microbeads and how to process them. Each row represents a different sample of beads. The figure below shows an example of an **Beads** sheet.
 
-.. image:: https://www.dropbox.com/s/e4snspj3w8yiqpl/input_beads.png?raw=1
+.. image:: /_static/img/excel_ui/input_beads.png
 
 For each row, the following columns must be filled:
 
@@ -46,7 +46,7 @@ Samples sheet
 
 In this sheet, the user specifies cell samples and tells ``FlowCal`` how to process them. Each row contains the information used in the analysis of one FCS file. One file can be analyzed several times with different options (e.g. gating fractions or fluorescence units) by adding more rows that reference the same file. The figure below shows an example of a **Samples** sheet.
 
-.. image:: https://www.dropbox.com/s/6c5b9lme2eg7iwx/input_samples.png?raw=1
+.. image:: /_static/img/excel_ui/input_samples.png
 
 For each row, the following columns must be filled:
 
@@ -61,6 +61,6 @@ For each row, the following columns must be filled:
     c. **MEF**: MEF units.
 6. **Gate Fraction** (F): Fraction of samples to keep when performing :doc:`density gating</fundamentals/density_gate>`.
 
-Additional columns, such as **Strain**, **Plasmid**, and **IPTG (mM)** (columns G, H, and I), can be added in any place for the user’s records, and will be copied unmodified to the output Excel file by ``FlowCal``.
+Additional columns, such as **Strain**, **Plasmid**, and **DAPG (uM)** (columns G, H, and I), can be added in any place for the user’s records, and will be copied unmodified to the output Excel file by ``FlowCal``.
 
-.. warning:: If MEF units are requested for a fluorescence channel of a sample, an FCS file with calibration beads data should be specified in the **Beads ID** column. Both beads and samples should have been acquired at the same settings for the specified fluorescence channel, otherwise ``FlowCal`` will throw an error.
+.. warning:: If MEF units are requested for a fluorescence channel of a sample, an FCS file with calibration beads data should be specified in the **Beads ID** column. Both beads and samples should have been acquired at the same settings for the specified fluorescence channel, otherwise ``FlowCal`` will throw an error.

doc/excel_ui/outputs.rst

@@ -12,29 +12,29 @@ Plots
 
     a. ``density_hist_<ID>.png``: A forward/side scatter 2D density diagram of the calibration particle sample, and a histogram for each relevant fluorescence channel.
 
-    .. image:: https://www.dropbox.com/s/qbnudtz1cfej7wg/output_beads_density.png?raw=1
+    .. image:: /_static/img/excel_ui/output_beads_density.png
 
     b. ``clustering_<ID>.png``: A plot of the sub-populations identified during the clustering step, where the different sub-populations are shown in different colors. Depending on the number of channels used for clustering, this plot is a histogram (when using only one channel), a 2D scatter plot (when using two channels), or a 3D scatter plot with three 2D projections (when using three channels or more).
 
-    .. image:: https://www.dropbox.com/s/omvr8t6qatuo64v/output_beads_clustering.png?raw=1
+    .. image:: /_static/img/excel_ui/output_beads_clustering.png
 
     .. note:: It is normally easy to distinguish the different bead populations in this plot, and the different colors should correspond to this expectation. If the populations have been identified incorrectly, changing the number of channels used for clustering or the density gate fraction can improve the results. These two parameters can be changed in the **Beads** sheet of the input Excel file.
 
     c. ``populations_<channel>_<ID>.png``: A histogram showing the identified microbead sub-populations in different colors, for each fluorescence channel in which a MEF standard curve is to be calculated. In addition, a vertical line is shown representing the median of each population, which is later used to calculate the standard curve. Sub-populations that were not used to generate the standard curve are shown in gray.
 
-    .. image:: https://www.dropbox.com/s/j8ac6reg6uxbbz5/output_beads_populations.png?raw=1
+    .. image:: /_static/img/excel_ui/output_beads_populations.png
 
     .. note:: All populations should be unimodal. Bimodal populations indicate incorrect clustering. This can be fixed by changing the number of channels used for clustering or the density gate fraction in the **Beads** sheet of the input Excel file.
 
     d. ``std_crv_<channel>_<ID>.png``: A plot of the fitted standard curve, for each channel in which MEF values were specified.
 
-    .. image:: https://www.dropbox.com/s/e1mp3woslx32rev/output_beads_sc.png?raw=1
+    .. image:: /_static/img/excel_ui/output_beads_sc.png
 
     .. note:: All the blue dots should line almost perfectly on the green line, otherwise the estimation of the standard curve might not be good. If this is not the case, you should make sure that clustering is being performed correctly by looking at the previous plots. If one dot differs significantly from the curve despite perfect clustering, you might want to manually remove it. This can be done by replacing its MEF value with the word "None" in the **Beads** sheet of the input Excel file.
 
 2. The folder ``plot_samples`` contains plots of the experimental cell samples. Each experimental sample of name “ID” as specified in the Excel input sheet results in a file named ``<ID>.png``. This image contains a forward/side scatter 2D density diagram with the gated region indicated, and a histogram for each user-specified fluorescence channel.
 
-.. image:: https://www.dropbox.com/s/mlkc6t22bzxz9k0/output_sample.png?raw=1
+.. image:: /_static/img/excel_ui/output_sample.png
 
 .. _excel-ui-outputs-excel:
 
@@ -47,16 +47,16 @@ In both sheets, the number of events after gating and the acquisition time are r
 
 Statistics per beads file, per fluorescence channel include: the channel gain, the amplifier type, the equation of the beads fluorescence model used, and the values of the fitted parameters.
 
-.. image:: https://www.dropbox.com/s/grgops0e5pt03ci/output_spreadsheet_beads.png?raw=1
+.. image:: /_static/img/excel_ui/output_spreadsheet_beads.png
 
 Statistics per cell sample, per fluorescence channel include: channel gain, mean, geometric mean, median, mode, arithmetic and geometric standard deviation, arithmetic and geometric coefficient of variation (CV), interquartile range (IQR), and robust coefficient of variation (RCV). Note that if an error has been found, the **Analysis Notes** field will be populated, and statistics and plots will not be reported.
 
-.. image:: https://www.dropbox.com/s/kjxpln97s42low8/output_spreadsheet_samples.png?raw=1
+.. image:: /_static/img/excel_ui/output_spreadsheet_samples.png
 
 In addition, a **Histograms** tab is generated, with bin/counts pairs for each sample and relevant fluorescence channel in the specified units.
 
-.. image:: https://www.dropbox.com/s/t4xq6rbm6jpri9d/output_spreadsheet_histograms.png?raw=1
+.. image:: /_static/img/excel_ui/output_spreadsheet_histograms.png
 
 One last tab named **About Analysis** is added with information about the corresponding input Excel file, the date and time of the run, and the FlowCal version used.
 
-.. image:: https://www.dropbox.com/s/hyi7k97cofqiibl/output_spreadsheet_about.png?raw=1
+.. image:: /_static/img/excel_ui/output_spreadsheet_about.png

doc/fundamentals/calibration.rst

@@ -28,7 +28,7 @@ To perform MEF calibration, the following steps are typically followed:
 
 Calibration beads must be measured in every experiment, using the same acquisition settings as when measuring cell samples. The figure below shows typical flow cytometry data from calibration beads.
 
-.. image:: https://www.dropbox.com/s/z4atwyiba8wy3b1/fundamentals_calibration_1.png?raw=1
+.. image:: /_static/img/fundamentals/fundamentals_calibration_1.png
 
 The top subfigure shows data from the forward/side scatter channels, whereas the bottom one shows one of the fluorescence channels. Note how several populations with different fluorescence values are evident in the bottom plot.
 
@@ -37,27 +37,27 @@ The top subfigure shows data from the forward/side scatter channels, whereas the
 
 Notice, in the figure above, that two different populations are present in the forward/side scatter plot. The faint population on the right/upper portion of the plot corresponds to bead aggregates. These are obviously undesired, as we are only interested in single bead fluorescence. This sort of situation is normally dealt with by "gating", which involves manually drawing a region of interest and retaining the events that fall inside. ``FlowCal`` performs :doc:`density gating<density_gate>`, an automated procedure to eliminate aggregates and other events that are clearly different from the main population of interest. The figure below shows a black contour surrounding the region identified by density gating in the forward/side scatter plot, showing that density gating can distinguish single beads from aggregates. Notice also how small peaks in the fluorescence plot disappear after density-gating, which is consistent with the eliminated population being composed of agglomerations of multiple beads.
 
-.. image:: https://www.dropbox.com/s/95ph8z8ajdn5wta/fundamentals_calibration_2.png?raw=1
+.. image:: /_static/img/fundamentals/fundamentals_calibration_2.png
 
 3. Identification of Bead Subpopulations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In order to calculate the average fluorescence of each subpopulation, the individual events corresponding to each must first be identified. The figure below shows one of the plots produced by ``FlowCal`` after an automated clustering algorithm has properly identified each subpopulation. Note how this can be achieved using information from several fluorescence channels at the same time.
 
-.. image:: https://www.dropbox.com/s/x0gnbrhzp51ljum/fundamentals_calibration_3.png?raw=1
+.. image:: /_static/img/fundamentals/fundamentals_calibration_3.png
 
 Next, the average fluorescence of each subpopulation is calculated. Some subpopulations, however, can have fluorescence values that are outside the limit of detection of the instrument, and therefore their events will show saturated fluorescence values. These subpopulations should not be considered further in the analysis. ``FlowCal`` discards these automatically.
 
 The figure below shows the individual subpopulations with a vertical line representing their median fluorescence. In addition, subpopulations that were automatically discarded are shown colored in gray.
 
-.. image:: https://www.dropbox.com/s/r9n8s96fmj7runm/fundamentals_calibration_4.png?raw=1
+.. image:: /_static/img/fundamentals/fundamentals_calibration_4.png
 
 4. Calculation of a Standard Curve
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Having the fluorescence of the individual populations, as measured by the flow cytometer, and the MEF values provided by the manufacturer, a standard curve can be calculated to transform fluorescence of any event to MEF. The figure below shows an example of such a standard curve. ``FlowCal`` uses the concept of a "bead fluorescence model", which is directly fitted to bead data but not immediately applicable to cells. However, some small mathematical manipulations turn this bead fluorescence model into a standard curve that is readily applicable to cells.
 
-.. image:: https://www.dropbox.com/s/9c6ibfo0vxa9j1a/fundamentals_calibration_5.png?raw=1
+.. image:: /_static/img/fundamentals/fundamentals_calibration_5.png
 
 5. Conversion of Cell Fluorescence to MEF
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/fundamentals/density_gate.rst

@@ -8,7 +8,7 @@ Density gating looks at two channels of flow cytometry data, and discards events
 
 In the figure below, a sample was acquired with an intentionally low side-scatter threshold to allow a significant number of events corresponding to non-biological debris. Density gating was then applied to retain 50% of the events in the densest region. Because cells have a more uniform size than the observed debris, density gating retains mostly cells, which is reflected in the fact that FL1 fluorescence is bimodal before gating, but not after.
 
-.. image:: https://www.dropbox.com/s/rz2cvv0vug4ws7g/fundamentals_density_1.png?raw=1
+.. image:: /_static/img/fundamentals/fundamentals_density_1.png
 
 .. note:: The sample shown above was intentionally acquired with a low threshold value in ``SSC`` to show the capabilities of density gating. Normally, a lot of the debris can be eliminated by simply selecting a higher ``SSC`` threshold. However, density gating is still an excellent method to clean the data and eliminate all the debris that a simple threshold cannot filter. In our experience, this can still be a significant fraction of the total event count, especially if the cell culture has low density.
 

doc/getting_started/install_anaconda.rst

@@ -3,11 +3,11 @@ Installing FlowCal with Anaconda
 
 To install Anaconda and ``FlowCal``, do the following:
 
-1. Navigate to https://www.anaconda.com/distribution/#download-section. Make sure that your operating system is selected (Windows, macOS, Linux). Click on the "Download" button below the "Python 3.7 version" message. This will download the installer.
+1. Navigate to `this <https://www.anaconda.com/products/individual>`_ page and scroll down to the "Anaconda Installers" section. Click on the "Graphical Installer" link below the name of your operating system (Windows, MacOS, or Linux). This will download the installer.
 
-.. note:: **Windows**: If your computer is a 32-bit PC, click on the message "32-Bit Graphical Installer" instead of the "Download" button. If you don't know whether yours is a 32 or 64 computer but you have purchased it in the last five years, it is probably a 64-bit computer and you can ignore this message.
+.. note:: **Windows**: If your computer is a 32-bit PC, click on the message "32-Bit Graphical Installer" instead of the "Download" button. If you don't know whether yours is a 32 or 64-bit computer but you have purchased it in the last five years, it is probably a 64-bit computer and you can ignore this message.
 
-.. note:: Python 2.7 is also supported. However, we recommend downloading the Python 3.7 version of Anaconda.
+.. note:: Python 2.7 is also supported. However, we recommend downloading the Python 3.8 version of Anaconda.
 
 2. Double click the installer (.exe in Windows, .pkg in OS X) and follow the instructions on screen.
 
@@ -17,7 +17,7 @@ To install Anaconda and ``FlowCal``, do the following:
 
 4. Inside the unzipped folder, double click on ``Install FlowCal (Windows).bat`` or ``Install FlowCal (macOS)`` if you are using Windows or OS X, respectively. This will open a terminal window and install ``FlowCal``. The installation procedure may take a few minutes. When installation is finished, the terminal will show the message “Press Enter to finish...”. If the installation was successful, your terminal should look like the figure below. Press Enter to close the terminal window.
 
-.. image:: https://www.dropbox.com/s/9ygziuk8r2r93kw/installation_completed.png?raw=1
+.. image:: /_static/img/getting_started/installation_completed.png
 
 .. note:: **Windows**: If the following message appears after double clicking ``Install FlowCal (Windows)``: “Windows protected your PC – Windows SmartScreen prevented an unrecognized app from starting...”, click on the “More info” link under the text, and then click on the “Run anyway” button. This will remove the security restriction from the program and allow it to run properly.
 

doc/getting_started/install_python.rst

@@ -1,7 +1,7 @@
 Installing FlowCal in an Existing Python Evironment
 =======================================================
 
-Python (2.7, 3.6, or 3.7) is required, along with ``pip`` and ``setuptools``. The easiest way is to install ``FlowCal`` is to use ``pip``::
+Python (2.7, 3.6, 3.7, or 3.8) is required, along with ``pip`` and ``setuptools``. The easiest way is to install ``FlowCal`` is to use ``pip``::
 
 	pip install FlowCal