Skip to content

Commit

Permalink
#22 , first draft of quickstart, usage and installation ready
Browse files Browse the repository at this point in the history
  • Loading branch information
niklasmueboe committed Sep 17, 2021
1 parent 3bf2cf6 commit ac16958
Showing 22 changed files with 231 additions and 77 deletions.
Binary file modified docs/build/html/.doctrees/environment.pickle
Binary file not shown.
Binary file modified docs/build/html/.doctrees/index.doctree
Binary file not shown.
Binary file modified docs/build/html/.doctrees/quickstart.doctree
Binary file not shown.
Binary file modified docs/build/html/.doctrees/tutorial.doctree
Binary file not shown.
Binary file modified docs/build/html/.doctrees/usage.doctree
Binary file not shown.
Binary file added docs/build/html/_images/ParameterPreview.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
32 changes: 28 additions & 4 deletions docs/build/html/_sources/index.rst.txt
Original file line number Diff line number Diff line change
@@ -6,11 +6,13 @@
What is SSAM-lite?
##################

- WEBAPp
- runs only in Browser
- SSAM paper etc
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


Citations
=================
@@ -26,7 +28,29 @@ Sebastian Tiesmeyer, Shashwat Sahay, Niklas Mueller-Boetticher, Roland Eils, Seb
License
=================

TODO enter license here
TODO do we stick to the MIT license

MIT License

Copyright (c) 2021 sebastiantiesmeyer

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



9 changes: 5 additions & 4 deletions docs/build/html/_sources/quickstart.rst.txt
Original file line number Diff line number Diff line change
@@ -26,14 +26,15 @@ Download the test data from ..... TODO
My first analysis
=================

Open the *index.html* from the directory you just unzipped.
Open the *index.html* from the unzipped SSAM-lite directory by double-clicking.

Click on **Get going!**

Click on "coordinates" and select the *coordinates.csv* from the sample data.
Do the same for the "signatures" (obviously use the *signature.csv* this time, *duh!*)
Click on "Coordinates" and select the *coordinates.csv* from the sample data.
Do the same for the "Signatures" (obviously use the *signature.csv* this time, *duh!*)

Time is flying by so we skip the "Parameters" section heading straight for "Analysis" and click on "Run Kernel Density Estimation".
Time is flying by so we skip the "Parameters" section, leaving them at their default values,
heading straight for "Analysis" and click on "Run Kernel Density Estimation".
Time for a short break now, this step might take 2 mins.

When the KDE has been estimated scroll further down and hit "Infer Cell Types". Done!
5 changes: 3 additions & 2 deletions docs/build/html/_sources/tutorial.rst.txt
Original file line number Diff line number Diff line change
@@ -3,7 +3,8 @@ Tutorial
########


TODO do we need a tutorial? there is not a lot of room between the quickstart and the usage anyway?


refernce tutorial in app
After installation of SSAM-lite, this tutorial will help you get to
know the basic workflow of

58 changes: 45 additions & 13 deletions docs/build/html/_sources/usage.rst.txt
Original file line number Diff line number Diff line change
@@ -19,25 +19,36 @@ and double-click the *index.html* to open it in your default Web Browser.
SSAM-lite-server
----------------

To connet to SSAM-lite-server, you will need to to open your favourite Web Browser (not IE)
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).
However, the IP and port depends on your local setup. Talk to your SSAM-lite coordinator.
However, the IP and port depends on your local setup. Talk to your responsible SSAM-lite coordinator.

Navigation
===========

Navigation is straight-forward. You can either scroll up and down to switch between the different steps
or you can use the navigation bar in the top of the window to directly jump to any section.

Furthermore, the "Get going!" button will bring you to the data center to start the analysis
by uploading your data.


Data
===========

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:
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.
The name of the headers are irrelevant, however their order needs to be kept.
Negative coordinates are possible.
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 |
+----------+-----------+-----------+
@@ -69,6 +80,7 @@ Gene Signatures
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).

Once both files are loaded you can proceed with setting the parameters for your analysis.

Parameters
===========
@@ -79,37 +91,57 @@ 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
asdhas
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).

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)
dsälifhsdfälgh
The kernel bandwidth TODO definition?

A higher value will result in an increased smoothing of the mRNA density estimation.

Cell assignment threshold
sdlfh
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.


Each of the parameters can be set in their respective field and applied by hitting Enter.
For a more intuitive parameter selection you can open a preview by clicking "Use preview generator for parameter search".
This will display the results of a subset of your data with the currently set parameters and lets you
interactively explore and tune your parameter set.

.. image:: ../res/imgs/ParameterPreview.png
:width: 800
:alt: Screenshot of the Parameter preview section

Once you are happy with your choice you can proceed with the actual analysis.


Analysis
========

To run the analysis, you start by clicking "Run Kernel Density Estimation" below
"Step 1: Kernel Density Estimation" and wait until processing is finished.
After it finished, the KDE estimates will be displayed in a plot (see example below).
Once it finished, the KDE estimates will be displayed in a plot (see example below).
This step is the computationally most expensive and might tak a few minutes.

.. note::
Your Browser might warn you that the current site is slowing it down.
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
:width: 600
:width: 800
:alt: KDE estimation given the previously set parameters

Next, given the KDE estimates you can start inferring cell types.
Scroll down to "Step 2: Cell Assignments" and click on "Infer Cell Types".
The inferred cell types will be displayed in a new plot.

.. image:: ../res/imgs/inferredCelltypes.png
:width: 600
: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
29 changes: 23 additions & 6 deletions docs/build/html/index.html
Original file line number Diff line number Diff line change
@@ -71,11 +71,10 @@

<section id="what-is-ssam-lite">
<h1>What is SSAM-lite?<a class="headerlink" href="#what-is-ssam-lite" title="Permalink to this headline"></a></h1>
<ul class="simple">
<li><p>WEBAPp</p></li>
<li><p>runs only in Browser</p></li>
<li><p>SSAM paper etc</p></li>
</ul>
<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>
<section id="citations">
<h2>Citations<a class="headerlink" href="#citations" title="Permalink to this headline"></a></h2>
<p>TODO please correct me!</p>
@@ -86,7 +85,24 @@ <h2>Citations<a class="headerlink" href="#citations" title="Permalink to this he
</section>
<section id="license">
<h2>License<a class="headerlink" href="#license" title="Permalink to this headline"></a></h2>
<p>TODO enter license here</p>
<p>TODO do we stick to the MIT license</p>
<p>MIT License</p>
<p>Copyright (c) 2021 sebastiantiesmeyer</p>
<p>Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the “Software”), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:</p>
<p>The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.</p>
<p>THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.</p>
<div class="toctree-wrapper compound">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul>
@@ -105,6 +121,7 @@ <h2>License<a class="headerlink" href="#license" title="Permalink to this headli
<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>
<li class="toctree-l2"><a class="reference internal" href="usage.html#data">Data</a></li>
<li class="toctree-l2"><a class="reference internal" href="usage.html#parameters">Parameters</a></li>
<li class="toctree-l2"><a class="reference internal" href="usage.html#analysis">Analysis</a></li>
9 changes: 5 additions & 4 deletions docs/build/html/quickstart.html
Original file line number Diff line number Diff line change
@@ -94,11 +94,12 @@ <h2>Test data<a class="headerlink" href="#test-data" title="Permalink to this he
</section>
<section id="my-first-analysis">
<h2>My first analysis<a class="headerlink" href="#my-first-analysis" title="Permalink to this headline"></a></h2>
<p>Open the <em>index.html</em> from the directory you just unzipped.</p>
<p>Open the <em>index.html</em> from the unzipped SSAM-lite directory by double-clicking.</p>
<p>Click on <strong>Get going!</strong></p>
<p>Click on “coordinates” and select the <em>coordinates.csv</em> from the sample data.
Do the same for the “signatures” (obviously use the <em>signature.csv</em> this time, <em>duh!</em>)</p>
<p>Time is flying by so we skip the “Parameters” section heading straight for “Analysis” and click on “Run Kernel Density Estimation”.
<p>Click on “Coordinates” and select the <em>coordinates.csv</em> from the sample data.
Do the same for the “Signatures” (obviously use the <em>signature.csv</em> this time, <em>duh!</em>)</p>
<p>Time is flying by so we skip the “Parameters” section, leaving them at their default values,
heading straight for “Analysis” and click on “Run Kernel Density Estimation”.
Time for a short break now, this step might take 2 mins.</p>
<p>When the KDE has been estimated scroll further down and hit “Infer Cell Types”. Done!</p>
<p>That’s how easy SSAM-lite is!</p>
Loading

0 comments on commit ac16958

Please sign in to comment.