#22 further improvements on documentation

docs/build/html/_sources/index.rst.txt

@@ -8,11 +8,11 @@ What is SSAM-lite?
 
 SSAM-lite is a lightweight, browser-based implementation of the `SSAM framework <https://www.nature.com/articles/s41467-021-23807-4>`__.
 It provides the functionality of SSAMs most popular and widely used features in a graphical user interface
-with a few functions added for convenience and ease of use.
-
-
-TODO what does SSAM do
+with a few functions added for convenience and ease of use. It neiteher requires specialised computational experts 
+nor hardware to handle and process data and thus can be run on a modest laptop.
 
+The SSAM framework allows for cell segmentation-free identification of cell-types by integrating prior knowledge of 
+cell type-specific gene signatures with data from a variety of spatial in situ transcriptomics techniques.
 
 Citations
 =================
@@ -60,6 +60,5 @@ SOFTWARE.
 
    quickstart
    installation
-   tutorial
    usage
    solo_vs_server

docs/build/html/_sources/installation.rst.txt

@@ -14,7 +14,7 @@ Supported Browsers
 ==================
 
 TODO
-We should add some stuff about requirments etc
+We should add some stuff about requirements etc
 
 
 SSAM-lite-solo
@@ -27,6 +27,7 @@ The installation of SSAM-lite-solo could not be easier. You either clone the
 
    git clone https://github.com/sebastiantiesmeyer/ssamLite
 
+
 or download it as zip-file from GitHub and then extract it.
 
 That is literally all, you are ready to go.
@@ -45,6 +46,7 @@ To install SSAM-lite-server you first need to clone the
 
     git clone https://github.com/sebastiantiesmeyer/ssamLiteDev
 
+
 How to handle signatures ????
 Download singatures: https://www.dropbox.com/s/8qxkgg16zelg6ya/new_sheet.tar.xz?dl=0
 Place signatures in data/genetics/ ???
@@ -56,23 +58,30 @@ Next we create a ``conda`` environment (TODO we should provide a yaml?) and acti
     conda create -n flask
     conda activate flask
 
+
 .. note::
 
     You can set the environment name to your preferences.
 
+
 Now we need to install some dependencies. TODO should we provide versions of the packages?
 
 .. code-block:: bash
 
     conda install flask numpy pandas
 
+
 And start the server.
+
+.. code-block:: bash
+
     cd /ssamLiteDev/scripts/flask
     export FLASK_APP=run.py
     export FLASK_ENV=development
     flask run
 
-Open browser at 127.0.0.1:5000
+
+Type in the address bar of your browser: 127.0.0.1:5000
 
 This definitely needs to be explained.
 However, somebody with a little bit expertise should do this,

docs/build/html/_sources/usage.rst.txt

@@ -12,15 +12,15 @@ read :ref:`supported-browsers`. Connecting to SSAM-lite depends on whether you w
 SSAM-lite-solo
 --------------
 
-SSAM-lite-solo runs locally on your computer. It is executed by your Browser
-and to open it you onyl need to navigate to the unzipped SSAM-lite directory
-and double-click the *index.html* to open it in your default Web Browser.
+SSAM-lite-solo runs locally on your computer. It is executed by your browser
+and to open it you only need to navigate to the unzipped SSAM-lite directory
+and double-click the *index.html* and it will start in your default web browser.
 
 SSAM-lite-server
 ----------------
 
-To connect to SSAM-lite-server, you will need to to open your favourite Web Browser (not IE)
-and enter the correct IP address and port in the form {ip}:{port} (e.g. 127.0.0.1:5000).
+To connect to SSAM-lite-server, you will need to to open your favourite web browser (not IE)
+and type the correct IP address and port in the form {ip}:{port} (e.g. 127.0.0.1:5000) into the address bar.
 However, the IP and port depends on your local setup. Talk to your responsible SSAM-lite coordinator.
 
 Navigation
@@ -36,76 +36,80 @@ by uploading your data.
 Data
 ===========
 
-The Data will be uploaded in the **Data Center** section of the tool. By clicking the "Coordinates" 
+The data will be uploaded in the **Data Center** section of the tool. By clicking the "Coordinates" 
 or "Signatures" button and selecting the correct files.
 To be able to use SSAM-lite you need to prepare your data in csv format.
 Two input files are required and must be structured as follows:
 
 mRNA Coordinates
-    This file needs to be of the form Gene, x-coordinate, y-coordinate.
+    This file needs to be of the form gene, x-coordinate, y-coordinate.
     The name of the headers are irrelevant, however their order needs to be kept.
     Negative coordinates are possible and the units do not matter. However, their magnitude 
     might have an influence on proper parameter values later on.
 
     +----------+-----------+-----------+
-    | Gene     |   x       |   y       |
+    | gene,    |   x,      |   y       |
     +----------+-----------+-----------+
-    | Gene A   |   0.5     |   1.3     |
+    | gene A,  |   0.5,    |   1.3     |
     +----------+-----------+-----------+
-    | Gene A   |   1.1     |   2.1     |
+    | gene A,  |   1.1,    |   2.1     |
     +----------+-----------+-----------+
-    | Gene B   |   0.4     |   0.5     |
+    | gene B,  |   0.4,    |   0.5     |
     +----------+-----------+-----------+
 
 Gene Signatures
-    This file should be a matrix of Cell types by Genes. 
-    The first column and row contains the names of Cell types and Genes, respectively. All the other cell values
+    This file should be a matrix of cell types by genes. 
+    The first column and row contains the names of cell types and genes, respectively. All the other cell values
     are gene scores ... TODO  how to define this ...
     This will later be used to assign each pixel to a cell type (or leave them unclassified)
-    based on the Kernel Density Estimation.
+    based on the kernel density estimation.
 
     +--------------+----------+-----------+-----------+
-    |              | Gene A   | Gene B    | Gene C    |
+    |       ,      | gene A,  | gene B,   | gene C    |
     +--------------+----------+-----------+-----------+
-    | Celltype A   |    0.5   |   -0.5    |   1.3     |
+    | cell type A, |    0.5,  |   -0.5,   |   1.3     |
     +--------------+----------+-----------+-----------+
-    | Celltype B   |    -0.2  |   1.1     |   2.1     |
+    | cell type B, |    -0.2, |   1.1,    |   2.1     |
     +--------------+----------+-----------+-----------+
-    | Celltype C   |    0.3   |   0.4     |   0.5     |
+    | cell type C, |    0.3,  |   0.4,    |   0.5     |
     +--------------+----------+-----------+-----------+
 
 
 .. note::
-    The name of the genes sre not relevant as there is no database used in the background.
+    The name of the genes need not be correct as there is no database used in the background.
     But remember that the gene names from the coordinates and the signatures need to be the same
-    (or at least the two sets of names must be at least partially overlapping).
+    (or more specifically the two sets of names must be partially overlapping).
 
 Once both files are loaded you can proceed with setting the parameters for your analysis.
 
 Parameters
 ===========
 
-For a deep understanding of the SSAM framework we would refer the user to the
+For a more detailed explanation of the SSAM framework we would refer the user to the
 `SSAM publication <https://www.nature.com/articles/s41467-021-23807-4>`__,
 however we will briefly describe the purpose and effect of the parameters
 that can be set by the user to obtain optimal results.
 
 Vector field width
     The vector field width defines the horizontal pixel count of the output images.
-    This is necessary as the KDE will be projected onto discrete locations (the pixels).
+    This is necessary as the kernel density estimation (KDE) will be projected onto 
+    discrete locations (the pixels).
 
     A higher value will result in higher resolution but also in increased processing time and memory
     as well as size of the output images.
 
 KDE kernel bandwidth (sigma)
-    The kernel bandwidth TODO definition?
+    SSAM-lite uses a Gaussian kernel and the kernel bandwidth defines the "range" of 
+    integration of data points (mRNA spots) for the KDE.
 
     A higher value will result in an increased smoothing of the mRNA density estimation.
 
 Cell assignment threshold
     This threshold is used to decide whether a pixel in the KDE projection belongs to
-    a cell or not. It is visualised in the parameter preview to help find an 
-    optimal value.
+    a cell or not. 
+
+    As help to pick an optimal value you can check the KDE estimate (middle plot in the parameter preview)
+    to find the intensity that should serve as cutoff point.
 
 
 Each of the parameters can be set in their respective field and applied by hitting Enter.
@@ -129,7 +133,7 @@ Once it finished, the KDE estimates will be displayed in a plot (see example bel
 This step is the computationally most expensive and might tak a few minutes.
 
 .. note::
-    If you are using SSAM-lite-solo your Browser might warn you that it is being slowed down by the current site.
+    If you are using SSAM-lite-solo your browser might warn you that it is being slowed down by the current site.
     This is normal due to the heavy computation running in the background and can be ignored.
 
 .. image:: ../res/imgs/KDE.png
@@ -144,7 +148,7 @@ The inferred cell types will be displayed in a new plot.
   :width: 800
   :alt: Cell types inferred from KDE using the provided gene signatures
 
-If you are not content with the results you can go back to the parameters section
+If you are not satisfied with the results you can go back to the parameters section
 and refine those before rerunning the analysis.
 
 
@@ -153,4 +157,4 @@ Save results
 
 All plots are produced with `Plotly <https://plotly.com/>`__ and can be downloaded
 by hovering over the plot which triggers a legend to appear in the upper right corner,
-now click the Camera icon which lets you download the current plot as png file.
+now click the camera icon which lets you download the current plot as png file.

docs/build/html/genindex.html

@@ -38,7 +38,6 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="quickstart.html">quickstart / tldr</a></li>
 <li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
-<li class="toctree-l1"><a class="reference internal" href="tutorial.html">Tutorial</a></li>
 <li class="toctree-l1"><a class="reference internal" href="usage.html">Usage</a></li>
 <li class="toctree-l1"><a class="reference internal" href="solo_vs_server.html">Solo or Server?</a></li>
 </ul>

docs/build/html/index.html

@@ -40,7 +40,6 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="quickstart.html">quickstart / tldr</a></li>
 <li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
-<li class="toctree-l1"><a class="reference internal" href="tutorial.html">Tutorial</a></li>
 <li class="toctree-l1"><a class="reference internal" href="usage.html">Usage</a></li>
 <li class="toctree-l1"><a class="reference internal" href="solo_vs_server.html">Solo or Server?</a></li>
 </ul>
@@ -73,8 +72,10 @@
 <h1>What is SSAM-lite?<a class="headerlink" href="#what-is-ssam-lite" title="Permalink to this headline"></a></h1>
 <p>SSAM-lite is a lightweight, browser-based implementation of the <a class="reference external" href="https://www.nature.com/articles/s41467-021-23807-4">SSAM framework</a>.
 It provides the functionality of SSAMs most popular and widely used features in a graphical user interface
-with a few functions added for convenience and ease of use.</p>
-<p>TODO what does SSAM do</p>
+with a few functions added for convenience and ease of use. It neiteher requires specialised computational experts
+nor hardware to handle and process data and thus can be run on a modest laptop.</p>
+<p>The SSAM framework allows for cell segmentation-free identification of cell-types by integrating prior knowledge of
+cell type-specific gene signatures with data from a variety of spatial in situ transcriptomics techniques.</p>
 <section id="citations">
 <h2>Citations<a class="headerlink" href="#citations" title="Permalink to this headline"></a></h2>
 <p>TODO please correct me!</p>
@@ -118,7 +119,6 @@ <h2>License<a class="headerlink" href="#license" title="Permalink to this headli
 <li class="toctree-l2"><a class="reference internal" href="installation.html#ssam-lite-server">SSAM-lite-server</a></li>
 </ul>
 </li>
-<li class="toctree-l1"><a class="reference internal" href="tutorial.html">Tutorial</a></li>
 <li class="toctree-l1"><a class="reference internal" href="usage.html">Usage</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="usage.html#open-ssam-lite">Open SSAM-lite</a></li>
 <li class="toctree-l2"><a class="reference internal" href="usage.html#navigation">Navigation</a></li>

docs/build/html/installation.html

@@ -18,7 +18,7 @@
     <script src="_static/js/theme.js"></script>
     <link rel="index" title="Index" href="genindex.html" />
     <link rel="search" title="Search" href="search.html" />
-    <link rel="next" title="Tutorial" href="tutorial.html" />
+    <link rel="next" title="Usage" href="usage.html" />
     <link rel="prev" title="quickstart / tldr" href="quickstart.html" /> 
 </head>
 
@@ -46,7 +46,6 @@
 <li class="toctree-l2"><a class="reference internal" href="#ssam-lite-server">SSAM-lite-server</a></li>
 </ul>
 </li>
-<li class="toctree-l1"><a class="reference internal" href="tutorial.html">Tutorial</a></li>
 <li class="toctree-l1"><a class="reference internal" href="usage.html">Usage</a></li>
 <li class="toctree-l1"><a class="reference internal" href="solo_vs_server.html">Solo or Server?</a></li>
 </ul>
@@ -84,7 +83,7 @@ <h1>Installation<a class="headerlink" href="#installation" title="Permalink to t
 <section id="supported-browsers">
 <span id="id1"></span><h2>Supported Browsers<a class="headerlink" href="#supported-browsers" title="Permalink to this headline"></a></h2>
 <p>TODO
-We should add some stuff about requirments etc</p>
+We should add some stuff about requirements etc</p>
 </section>
 <section id="ssam-lite-solo">
 <h2>SSAM-lite-solo<a class="headerlink" href="#ssam-lite-solo" title="Permalink to this headline"></a></h2>
@@ -120,14 +119,14 @@ <h2>SSAM-lite-server<a class="headerlink" href="#ssam-lite-server" title="Permal
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>conda install flask numpy pandas
 </pre></div>
 </div>
-<dl class="simple">
-<dt>And start the server.</dt><dd><p>cd /ssamLiteDev/scripts/flask
-export FLASK_APP=run.py
-export FLASK_ENV=development
-flask run</p>
-</dd>
-</dl>
-<p>Open browser at 127.0.0.1:5000</p>
+<p>And start the server.</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span> /ssamLiteDev/scripts/flask
+<span class="nb">export</span> <span class="nv">FLASK_APP</span><span class="o">=</span>run.py
+<span class="nb">export</span> <span class="nv">FLASK_ENV</span><span class="o">=</span>development
+flask run
+</pre></div>
+</div>
+<p>Type in the address bar of your browser: 127.0.0.1:5000</p>
 <p>This definitely needs to be explained.
 However, somebody with a little bit expertise should do this,
 most of it will be config dependent and people installing this will most likely know what they are doing!</p>
@@ -139,7 +138,7 @@ <h2>SSAM-lite-server<a class="headerlink" href="#ssam-lite-server" title="Permal
           </div>
           <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
         <a href="quickstart.html" class="btn btn-neutral float-left" title="quickstart / tldr" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
-        <a href="tutorial.html" class="btn btn-neutral float-right" title="Tutorial" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
+        <a href="usage.html" class="btn btn-neutral float-right" title="Usage" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
     </div>
 
   <hr/>

docs/build/html/objects.inv

@@ -2,6 +2,5 @@
 # Project: SSAM-lite
 # Version: 
 # The remainder of this file is compressed using zlib.
-xڅ�1o� �w~R�Ҫk���:D��V#b��z�9Ǒ6��l�Hݎ���=Dg7�#=�5���e7��=A��Q,1�m
-��^�t^6��V�c��q�@�á�}�~Q�͝>�E�Ff�hةY����.��:}
-����˚���"�$	o5�}�0k�h��ӝ
��Ζ�0�۟�>{W�a%��J�xKR7�N�M��tG$�F�c��n>%5��:1�#9��Yˋߧ�>���]��H��W��4
+xڅ�1O�0�w���`5������R�1Vn|J,�\�]
+���u�ش����=�n��,�ٛz�O���C/GoiTk�R�BE�7��i^��;�M���8jj՗����do��z12�%;y���?��,}�S�_�k?c� e�U�d�z�6(Fھ>��L4�ߙ�'MA3��?L��'�g����CU��$u��T��MO�HA��C����է��3�&��)o_�|�=��"��r

docs/build/html/search.html

@@ -41,7 +41,6 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="quickstart.html">quickstart / tldr</a></li>
 <li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
-<li class="toctree-l1"><a class="reference internal" href="tutorial.html">Tutorial</a></li>
 <li class="toctree-l1"><a class="reference internal" href="usage.html">Usage</a></li>
 <li class="toctree-l1"><a class="reference internal" href="solo_vs_server.html">Solo or Server?</a></li>
 </ul>