started on #22, general structure of documentation and first paragraphs

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/build/html/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: f43c1aaa288727b6e9c2859e1885576f
+tags: 645f666f9bcd5a90fca523b33c5a78b7

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

@@ -0,0 +1,41 @@
+.. SSAM-lite documentation master file, created by
+   sphinx-quickstart on Thu Sep 16 13:38:45 2021.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+What is SSAM-lite?
+##################
+
+- WEBAPp
+- runs only in Browser
+- SSAM paper etc
+
+
+
+Citations
+=================
+
+TODO please correct me!
+
+Sebastian Tiesmeyer, Shashwat Sahay, Niklas Mueller-Boetticher, Roland Eils, Sebastian Mackowiak, Naveed Ishaque.
+2021.
+"`SSAM-lite: a light-weight web-based framework for analysis of spatially resolved transcriptomics data <https://biorxiv.org>`__"
+*bioRxiv*. doi: 10.1101/2021....
+
+
+License
+=================
+
+TODO enter license here
+
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   quickstart
+   installation
+   tutorial
+   usage
+   solo_vs_server

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

@@ -0,0 +1,79 @@
+############
+Installation
+############
+
+SSAM-lite comes in two flavors -- SSAM-lite-solo and SSAM-lite-server.
+While the usage is almost identical the installation differs quite a lot.
+If you need some help deciding which of the two fits your needs best and what the differences are follow the guide
+:ref:`solo-or-server`
+
+
+.. _supported-browsers:
+
+Supported Browsers
+==================
+
+TODO
+We should add some stuff about requirments etc
+
+
+SSAM-lite-solo
+==============
+
+The installation of SSAM-lite-solo could not be easier. You either clone the 
+`GitHub repository <https://github.com/sebastiantiesmeyer/ssamLite>`__
+
+.. code-block:: bash
+
+   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.
+
+
+
+SSAM-lite-server
+================
+
+Will this be implemented?
+
+To install SSAM-lite-server you first need to clone the
+`GitHub repository <https://github.com/sebastiantiesmeyer/ssamLiteDev>`__
+
+.. code-block:: bash
+
+    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/ ???
+
+Next we create a ``conda`` environment (TODO we should provide a yaml?) and activate it.
+
+.. code-block:: bash
+
+    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.
+    cd /ssamLiteDev/scripts/flask
+    export FLASK_APP=run.py
+    export FLASK_ENV=development
+    flask run
+
+Open browser at 127.0.0.1:5000
+
+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!

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

@@ -0,0 +1,41 @@
+#################
+quickstart / tldr
+#################
+
+
+For those of us
+
+- with very little time,
+- who know what `SSAM <https://www.nature.com/articles/s41467-021-23807-4>`__ is,
+- and just want to get a quick glance at what SSAM-lite can do ...
+
+
+Installation
+============
+
+Click `here <https://github.com/sebastiantiesmeyer/ssamLite/archive/refs/heads/main.zip>`__
+to download SSAM-lite-solo as zip, and extract it.
+
+
+Test data
+=========
+
+Download the test data from ..... TODO
+
+
+My first analysis
+=================
+
+Open the *index.html* from the directory you just unzipped.
+
+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!*)
+
+Time is flying by so we skip the "Parameters" section 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!
+
+That's how easy SSAM-lite is!

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

@@ -0,0 +1,6 @@
+ .. _solo-or-server:
+
+###############
+Solo or Server?
+###############
+

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

@@ -0,0 +1,9 @@
+########
+Tutorial
+########
+
+
+
+
+refernce tutorial in app
+

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

@@ -0,0 +1,124 @@
+####################
+Usage
+####################
+
+Open SSAM-lite
+==============
+
+SSAM-lite will be opened (and executed) in your Web Browser. For a list of compatible Browsers
+read :ref:`supported-browsers`. Connecting to SSAM-lite depends on whether you want to use the
+*solo* or *server* version. However, the usage afterwards will be (almost) identical.
+
+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-server
+----------------
+
+To connet 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.
+
+
+Data
+===========
+
+To be able to use SSAM-lite you need to prepare your data in csv format.
+
+Two input files are required:
+
+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.
+
+    +----------+-----------+-----------+
+    | Gene     | x         | y         |
+    +----------+-----------+-----------+
+    | Gene A   |   0.5     |   1.3     |
+    +----------+-----------+-----------+
+    | Gene A   |   1.1     |   2.1     |
+    +----------+-----------+-----------+
+    | 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
+    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.
+
+    +--------------+----------+-----------+-----------+
+    |              | Gene A   | Gene B    | Gene C    |
+    +--------------+----------+-----------+-----------+
+    | Celltype A   |    0.5   |   -0.5    |   1.3     |
+    +--------------+----------+-----------+-----------+
+    | Celltype B   |    -0.2  |   1.1     |   2.1     |
+    +--------------+----------+-----------+-----------+
+    | Celltype 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.
+    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).
+
+
+Parameters
+===========
+
+For a deep understanding 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
+    asdhas
+
+KDE kernel bandwidth (sigma)
+    dsälifhsdfälgh
+
+Cell assignment threshold
+    sdlfh
+
+
+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).
+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.
+    This is normal due to the heavy computation running in the background and can be ignored.
+
+.. image:: ../res/imgs/KDE.png
+  :width: 600
+  :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
+  :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
+and refine those before rerunning the analysis.
+
+
+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.