diff --git a/docs/build/html/.doctrees/environment.pickle b/docs/build/html/.doctrees/environment.pickle index 837c2eb..0615eff 100644 Binary files a/docs/build/html/.doctrees/environment.pickle and b/docs/build/html/.doctrees/environment.pickle differ diff --git a/docs/build/html/.doctrees/index.doctree b/docs/build/html/.doctrees/index.doctree index e624b7c..6600a1f 100644 Binary files a/docs/build/html/.doctrees/index.doctree and b/docs/build/html/.doctrees/index.doctree differ diff --git a/docs/build/html/.doctrees/quickstart.doctree b/docs/build/html/.doctrees/quickstart.doctree index cc6efbe..d7f1209 100644 Binary files a/docs/build/html/.doctrees/quickstart.doctree and b/docs/build/html/.doctrees/quickstart.doctree differ diff --git a/docs/build/html/.doctrees/tutorial.doctree b/docs/build/html/.doctrees/tutorial.doctree index 832b3da..0ba24f6 100644 Binary files a/docs/build/html/.doctrees/tutorial.doctree and b/docs/build/html/.doctrees/tutorial.doctree differ diff --git a/docs/build/html/.doctrees/usage.doctree b/docs/build/html/.doctrees/usage.doctree index 77439d5..ae5fe15 100644 Binary files a/docs/build/html/.doctrees/usage.doctree and b/docs/build/html/.doctrees/usage.doctree differ diff --git a/docs/build/html/_images/ParameterPreview.png b/docs/build/html/_images/ParameterPreview.png new file mode 100644 index 0000000..3a8642c Binary files /dev/null and b/docs/build/html/_images/ParameterPreview.png differ diff --git a/docs/build/html/_sources/index.rst.txt b/docs/build/html/_sources/index.rst.txt index fc94866..06b4c04 100644 --- a/docs/build/html/_sources/index.rst.txt +++ b/docs/build/html/_sources/index.rst.txt @@ -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 `__. +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. diff --git a/docs/build/html/_sources/quickstart.rst.txt b/docs/build/html/_sources/quickstart.rst.txt index 411e463..876f199 100644 --- a/docs/build/html/_sources/quickstart.rst.txt +++ b/docs/build/html/_sources/quickstart.rst.txt @@ -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! diff --git a/docs/build/html/_sources/tutorial.rst.txt b/docs/build/html/_sources/tutorial.rst.txt index 08dff56..fa61da1 100644 --- a/docs/build/html/_sources/tutorial.rst.txt +++ b/docs/build/html/_sources/tutorial.rst.txt @@ -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 diff --git a/docs/build/html/_sources/usage.rst.txt b/docs/build/html/_sources/usage.rst.txt index adbc800..d9e2918 100644 --- a/docs/build/html/_sources/usage.rst.txt +++ b/docs/build/html/_sources/usage.rst.txt @@ -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,13 +91,33 @@ 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 @@ -93,15 +125,15 @@ 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. @@ -109,7 +141,7 @@ 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 diff --git a/docs/build/html/index.html b/docs/build/html/index.html index d5c23a2..34ff8ab 100644 --- a/docs/build/html/index.html +++ b/docs/build/html/index.html @@ -71,11 +71,10 @@

What is SSAM-lite?

- +

SSAM-lite is a lightweight, browser-based implementation of the SSAM framework. +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

TODO please correct me!

@@ -86,7 +85,24 @@

Citations

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.

Contents:

    @@ -105,6 +121,7 @@

    LicenseTutorial
  • Usage
    • Open SSAM-lite
    • +
    • Navigation
    • Data
    • Parameters
    • Analysis
    • diff --git a/docs/build/html/quickstart.html b/docs/build/html/quickstart.html index a3bb447..5694117 100644 --- a/docs/build/html/quickstart.html +++ b/docs/build/html/quickstart.html @@ -94,11 +94,12 @@

      Test data

      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!)

      -

      Time is flying by so we skip the “Parameters” section heading straight for “Analysis” and click on “Run Kernel Density Estimation”. +

      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, 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!

      That’s how easy SSAM-lite is!

      diff --git a/docs/build/html/searchindex.js b/docs/build/html/searchindex.js index 2a7c8d2..2f4b4c7 100644 --- a/docs/build/html/searchindex.js +++ b/docs/build/html/searchindex.js @@ -1 +1 @@ -Search.setIndex({docnames:["index","installation","quickstart","solo_vs_server","tutorial","usage"],envversion:{"sphinx.domains.c":2,"sphinx.domains.changeset":1,"sphinx.domains.citation":1,"sphinx.domains.cpp":4,"sphinx.domains.index":1,"sphinx.domains.javascript":2,"sphinx.domains.math":2,"sphinx.domains.python":3,"sphinx.domains.rst":2,"sphinx.domains.std":2,sphinx:56},filenames:["index.rst","installation.rst","quickstart.rst","solo_vs_server.rst","tutorial.rst","usage.rst"],objects:{},objnames:{},objtypes:{},terms:{"0":[1,5],"1":[1,5],"10":0,"1101":0,"127":[1,5],"2":[2,5],"2021":0,"3":5,"4":5,"5":5,"5000":[1,5],"8qxkgg16zelg6ya":1,"break":2,"default":5,"do":[1,2],"ds\u00e4lifhsdf\u00e4lgh":5,"export":1,"function":[],"new":5,"public":5,"short":2,"while":1,A:5,And:1,But:5,For:[2,5],IF:[],If:[1,5],It:5,That:[1,2],The:[1,5],There:[],To:[1,5],Will:1,_:[],_solo_or_serv:[],abl:5,about:1,activ:1,add:1,address:5,after:5,afterward:5,all:[1,5],almost:[1,5],an:[],analysi:0,app:4,appear:5,ar:[1,5],asdha:5,assign:5,b:5,back:5,background:5,bandwidth:5,base:[0,5],been:2,befor:5,below:5,best:1,biorxiv:0,bit:1,boettich:0,briefli:5,browser:[0,5],c:5,camera:5,can:[1,2,5],cd:1,cell:[2,5],celltyp:5,click:[2,5],clone:1,column:5,com:1,come:1,compat:5,comput:5,computation:5,conda:1,config:1,connect:5,connet:5,contain:5,content:5,coordin:[2,5],corner:5,correct:[0,5],could:1,creat:1,csv:[2,5],current:5,data:[0,1],databas:5,decid:1,deep:5,defin:5,definit:1,densiti:[2,5],depend:[1,5],describ:5,develop:1,differ:1,directori:[2,5],displai:5,dl:1,doe:[],doi:0,done:2,doubl:5,down:[2,5],download:[1,2,5],dropbox:1,due:5,duh:2,e:5,each:5,easi:2,easier:1,effect:5,eil:0,either:1,enter:[0,5],environ:1,estim:[2,5],etc:[0,1],exampl:5,execut:5,expect:[],expens:5,experti:[],expertis:1,explain:1,extract:[1,2],favourit:5,few:5,field:5,file:[1,5],finish:5,first:[0,1,5],fit:1,flask:1,flask_app:1,flask_env:1,flavor:1,fly:2,follow:1,form:5,format:5,framework:[0,5],from:[1,2,5],further:2,g:5,gene:5,genet:1,get:2,git:1,github:1,given:5,glanc:2,go:[1,2,5],guid:1,ha:2,handl:1,head:2,header:5,heavi:5,help:1,here:[0,2],hit:2,hover:5,how:[1,2,5],howev:[1,5],html:[2,5],http:1,icon:5,ident:[1,5],ie:5,ignor:5,implement:1,index:[2,5],infer:[2,5],input:5,instal:0,ip:5,irrelev:5,ishaqu:0,just:2,kde:[2,5],kept:5,kernel:[2,5],know:[1,2],label:[],later:5,least:5,leav:5,legend:5,let:5,light:0,like:1,link:[],list:5,lite:2,liter:1,littl:[1,2],local:5,lot:1,mackowiak:0,matrix:5,me:0,might:[2,5],min:2,minut:5,modul:[],most:[1,5],mrna:5,mst:[],mueller:0,must:5,my:0,n:1,name:[1,5],nave:0,navig:5,need:[1,5],neg:5,new_sheet:1,next:[1,5],nikla:0,normal:5,note:[],now:[1,2,5],numpi:1,obtain:5,obvious:2,onli:0,onyl:5,open:[0,1,2],optim:5,order:5,org:[],other:5,over:5,overlap:5,packag:1,page:[],panda:1,paper:0,paramet:[0,2],partial:5,peopl:1,pictur:[],pixel:5,place:1,pleas:0,plot:5,plotli:5,png:5,port:5,possibl:5,prefer:1,prepar:5,process:5,produc:5,provid:1,purpos:5,py:1,quick:2,quickstart:0,quit:1,read:5,readi:1,refer:5,refernc:4,refin:5,relev:5,rememb:5,repositori:1,requir:[1,5],rerun:5,resolv:0,respect:5,result:0,right:5,roland:0,row:5,run:[0,1,2,5],s:[1,2],sahai:0,same:[2,5],sampl:2,save:0,score:5,script:1,scroll:[2,5],sdlfh:5,search:[],sebastian:0,sebastiantiesmey:1,section:[2,5],see:5,select:2,server:0,set:[1,5],setup:5,shashwat:0,should:[1,5],sigma:5,signatur:[1,2,5],singatur:1,site:5,skip:2,slow:5,so:2,solo:[0,2],some:1,somebodi:1,spatial:0,sre:5,ssam:2,ssamlit:1,ssamlitedev:1,start:[1,5],step:[2,5],straight:2,stuff:1,support:[0,5],tak:5,take:2,talk:5,tar:1,test:0,thei:1,them:5,thi:[1,2,5],those:[2,5],threshold:5,tiesmey:0,time:2,tldr:0,todo:[0,1,2,5],transcriptom:0,trigger:5,tutori:0,two:[1,5],type:[2,5],unclassifi:5,understand:5,until:5,unzip:[2,5],upper:5,us:[2,5],usag:[0,1],user:5,valu:5,vector:5,veri:2,version:[1,5],wait:5,want:[2,5],warn:5,we:[1,2,5],web:[0,5],webapp:0,weight:0,what:[1,2],when:2,whether:5,which:[1,5],who:2,width:5,would:5,www:1,x:5,xz:1,y:5,yaml:1,you:[1,2,5],your:[1,5],zip:[1,2]},titles:["What is SSAM-lite?","Installation","quickstart / tldr","Solo or Server?","Tutorial","Usage"],titleterms:{analysi:[2,5],browser:1,citat:0,content:0,data:[2,5],document:[],first:2,how:[],indic:[],instal:[1,2],licens:0,lite:[0,1,5],my:2,open:5,paramet:5,quickstart:2,result:5,s:[],save:5,server:[1,3,5],solo:[1,3,5],ssam:[0,1,5],support:1,tabl:[],test:2,tldr:2,tutori:4,us:[],usag:5,welcom:[],what:0}}) \ No newline at end of file +Search.setIndex({docnames:["index","installation","quickstart","solo_vs_server","tutorial","usage"],envversion:{"sphinx.domains.c":2,"sphinx.domains.changeset":1,"sphinx.domains.citation":1,"sphinx.domains.cpp":4,"sphinx.domains.index":1,"sphinx.domains.javascript":2,"sphinx.domains.math":2,"sphinx.domains.python":3,"sphinx.domains.rst":2,"sphinx.domains.std":2,sphinx:56},filenames:["index.rst","installation.rst","quickstart.rst","solo_vs_server.rst","tutorial.rst","usage.rst"],objects:{},objnames:{},objtypes:{},terms:{"0":[1,5],"1":[1,5],"10":0,"1101":0,"127":[1,5],"2":[2,5],"2021":0,"3":5,"4":5,"5":5,"5000":[1,5],"8qxkgg16zelg6ya":1,"break":2,"default":[2,5],"do":[0,1,2,4,5],"ds\u00e4lifhsdf\u00e4lgh":[],"export":1,"function":0,"new":5,"public":5,"short":2,"switch":5,"while":1,A:[0,5],AND:0,AS:0,And:1,BE:0,BUT:0,But:5,By:5,FOR:0,For:[2,5],IF:[],IN:0,IS:0,If:[1,5],It:[0,5],NO:0,NOT:0,OF:0,OR:0,THE:0,TO:0,That:[1,2],The:[0,1,5],There:[],To:[1,5],WITH:0,Will:1,_:[],_solo_or_serv:[],abl:5,about:1,abov:0,action:0,activ:1,actual:5,ad:0,add:1,address:5,after:4,afterward:5,all:[0,1,5],almost:[1,5],also:5,an:[0,5],analysi:0,ani:[0,5],anywai:4,app:[],appear:5,appli:5,ar:[1,5],aris:0,asdha:[],assign:5,associ:0,author:0,b:5,back:5,background:5,bandwidth:5,bar:5,base:[0,5],basic:4,been:2,befor:5,being:5,belong:5,below:5,best:1,between:[4,5],biorxiv:0,bit:1,boettich:0,both:5,briefli:5,bring:5,browser:[0,5],button:5,c:[0,5],camera:5,can:[1,2,5],cd:1,cell:[2,5],celltyp:5,center:5,charg:0,choic:5,claim:0,click:[2,5],clone:1,column:5,com:1,come:1,compat:5,comput:5,computation:5,conda:1,condit:0,config:1,connect:[0,5],connet:[],contain:5,content:5,contract:0,conveni:0,coordin:[2,5],copi:0,copyright:0,corner:5,correct:[0,5],could:1,count:5,creat:1,csv:[2,5],current:5,damag:0,data:[0,1],databas:5,deal:0,decid:[1,5],deep:5,defin:5,definit:[1,5],densiti:[2,5],depend:[1,5],describ:5,develop:1,differ:[1,5],directli:5,directori:[2,5],discret:5,displai:5,distribut:0,dl:1,document:0,doe:0,doi:0,done:2,doubl:[2,5],down:[2,5],download:[1,2,5],dropbox:1,due:5,duh:2,e:5,each:5,eas:0,easi:2,easier:1,effect:5,eil:0,either:[1,5],enter:5,environ:1,estim:[2,5],etc:1,event:0,exampl:5,execut:5,expect:[],expens:5,experti:[],expertis:1,explain:1,explor:5,express:0,extract:[1,2],favourit:5,featur:0,few:[0,5],field:5,file:[0,1,5],find:5,finish:5,first:[0,1,5],fit:[0,1],flask:1,flask_app:1,flask_env:1,flavor:1,fly:2,follow:[0,1,5],form:5,format:5,forward:5,framework:[0,5],free:0,from:[0,1,2,5],furnish:0,further:2,furthermor:5,g:5,gene:5,gener:5,genet:1,get:[2,4,5],git:1,github:1,given:5,glanc:2,go:[1,2,5],grant:0,graphic:0,guid:1,ha:2,handl:1,happi:5,have:5,head:2,header:5,heavi:5,help:[1,4,5],here:2,herebi:0,higher:5,hit:[2,5],holder:0,horizont:5,hover:5,how:[1,2,5],howev:[1,5],html:[2,5],http:1,icon:5,ident:[1,5],ie:5,ignor:5,imag:5,implement:[0,1],impli:0,includ:0,increas:5,index:[2,5],infer:[2,5],influenc:5,input:5,instal:[0,4],interact:5,interfac:0,intuit:5,ip:5,irrelev:5,ishaqu:0,jump:5,just:2,kde:[2,5],kept:5,kernel:[2,5],kind:0,know:[1,2,4],label:[],later:5,least:5,leav:[2,5],legend:5,let:5,liabil:0,liabl:0,light:0,lightweight:0,like:1,limit:0,link:[],list:5,lite:[2,4],liter:1,littl:[1,2],load:5,local:5,locat:5,lot:[1,4],mackowiak:0,magnitud:5,matrix:5,matter:5,me:0,memori:5,merchant:0,merg:0,might:[2,5],min:2,minut:5,mit:0,modifi:0,modul:[],more:5,most:[0,1,5],mrna:5,mst:[],mueller:0,must:5,my:0,n:1,name:[1,5],nave:0,navig:0,necessari:5,need:[1,4,5],neg:5,new_sheet:1,next:[1,5],nikla:0,noninfring:0,normal:5,note:[],notic:0,now:[1,2,5],numpi:1,obtain:[0,5],obvious:2,onc:5,onli:[],onto:5,onyl:5,open:[0,1,2],optim:5,order:5,org:[],other:[0,5],otherwis:0,out:0,output:5,over:5,overlap:5,packag:1,page:[],panda:1,paper:[],paramet:[0,2],partial:5,particular:0,peopl:1,permiss:0,permit:0,person:0,pictur:[],pixel:5,place:1,pleas:0,plot:5,plotli:5,png:5,popular:0,port:5,portion:0,possibl:5,prefer:1,prepar:5,preview:5,proce:5,process:5,produc:5,project:5,proper:5,provid:[0,1],publish:0,purpos:[0,5],py:1,quick:2,quickstart:[0,4],quit:1,read:5,readi:1,refer:5,refernc:[],refin:5,relev:5,rememb:5,repositori:1,requir:[1,5],rerun:5,resolut:5,resolv:0,respect:5,respons:5,restrict:0,result:0,right:[0,5],roland:0,room:4,row:5,run:[1,2,5],s:[1,2],sahai:0,same:[2,5],sampl:2,save:0,score:5,script:1,scroll:[2,5],sdlfh:[],search:5,sebastian:0,sebastiantiesmey:[0,1],section:[2,5],see:5,select:[2,5],sell:0,server:0,set:[1,5],setup:5,shall:0,shashwat:0,should:[1,5],sigma:5,signatur:[1,2,5],singatur:1,site:5,size:5,skip:2,slow:5,smooth:5,so:[0,2],softwar:0,solo:[0,2],some:1,somebodi:1,spatial:0,sre:5,ssam:[2,4],ssamlit:1,ssamlitedev:1,start:[1,5],step:[2,5],stick:0,straight:[2,5],structur:5,stuff:1,subject:0,sublicens:0,subset:5,substanti:0,support:[0,5],tak:5,take:2,talk:5,tar:1,test:0,thei:1,them:[2,5],thi:[0,1,2,4,5],those:[2,5],threshold:5,tiesmey:0,time:[2,5],tldr:0,todo:[0,1,2,4,5],tool:5,top:5,tort:0,transcriptom:0,trigger:5,tune:5,tutori:0,two:[1,5],type:[2,5],unclassifi:5,understand:5,unit:5,until:5,unzip:[2,5],up:5,upload:5,upper:5,us:[0,2,5],usag:[0,1,4],user:[0,5],valu:[2,5],vector:5,veri:2,version:[1,5],visualis:5,wait:5,want:[2,5],warn:5,warranti:0,we:[0,1,2,4,5],web:[0,5],webapp:[],weight:0,well:5,what:[1,2],when:2,whether:[0,5],which:[1,5],who:2,whom:0,wide:0,width:5,window:5,without:0,workflow:4,would:5,www:1,x:5,xz:1,y:5,yaml:1,you:[1,4,5],your:[1,5],zip:[1,2]},titles:["What is SSAM-lite?","Installation","quickstart / tldr","Solo or Server?","Tutorial","Usage"],titleterms:{analysi:[2,5],browser:1,citat:0,content:0,data:[2,5],document:[],first:2,how:[],indic:[],instal:[1,2],licens:0,lite:[0,1,5],my:2,navig:5,open:5,paramet:5,quickstart:2,result:5,s:[],save:5,server:[1,3,5],solo:[1,3,5],ssam:[0,1,5],support:1,tabl:[],test:2,tldr:2,tutori:4,us:[],usag:5,welcom:[],what:0}}) \ No newline at end of file diff --git a/docs/build/html/tutorial.html b/docs/build/html/tutorial.html index 22ab000..ae725d7 100644 --- a/docs/build/html/tutorial.html +++ b/docs/build/html/tutorial.html @@ -72,7 +72,9 @@

      Tutorial

      -

      refernce tutorial in app

      +

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

      +

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

      diff --git a/docs/build/html/usage.html b/docs/build/html/usage.html index 14ded20..f1b1d8f 100644 --- a/docs/build/html/usage.html +++ b/docs/build/html/usage.html @@ -48,6 +48,7 @@
    • SSAM-lite-server
  • +
  • Navigation
  • Data
  • Parameters
  • Analysis
  • @@ -96,19 +97,29 @@

    SSAM-lite-solo

    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.

+

Data

-

To be able to use SSAM-lite you need to prepare your data in csv format.

-

Two input files are required:

+

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. 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.

@@ -178,6 +189,7 @@

Data 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

@@ -185,31 +197,43 @@

ParametersSSAM publication, 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

+
+
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).

+

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

+
KDE kernel bandwidth (sigma)

The kernel bandwidth TODO definition?

+

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

-
Cell assignment threshold

sdlfh

+
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.

+

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.

+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.

-KDE estimation given the previously set parameters +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.

-Cell types inferred from KDE using the provided gene signatures +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.

diff --git a/docs/res/imgs/KDE.png:Zone.Identifier b/docs/res/imgs/KDE.png:Zone.Identifier deleted file mode 100644 index 053d112..0000000 --- a/docs/res/imgs/KDE.png:Zone.Identifier +++ /dev/null @@ -1,3 +0,0 @@ -[ZoneTransfer] -ZoneId=3 -HostUrl=about:internet diff --git a/docs/res/imgs/ParameterPreview.png b/docs/res/imgs/ParameterPreview.png new file mode 100644 index 0000000..3a8642c Binary files /dev/null and b/docs/res/imgs/ParameterPreview.png differ diff --git a/docs/res/imgs/inferredCelltypes.png:Zone.Identifier b/docs/res/imgs/inferredCelltypes.png:Zone.Identifier deleted file mode 100644 index 053d112..0000000 --- a/docs/res/imgs/inferredCelltypes.png:Zone.Identifier +++ /dev/null @@ -1,3 +0,0 @@ -[ZoneTransfer] -ZoneId=3 -HostUrl=about:internet diff --git a/docs/source/index.rst b/docs/source/index.rst index fc94866..06b4c04 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -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 `__. +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. diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst index 411e463..876f199 100644 --- a/docs/source/quickstart.rst +++ b/docs/source/quickstart.rst @@ -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! diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst index 08dff56..fa61da1 100644 --- a/docs/source/tutorial.rst +++ b/docs/source/tutorial.rst @@ -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 diff --git a/docs/source/usage.rst b/docs/source/usage.rst index adbc800..d9e2918 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -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,13 +91,33 @@ 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 @@ -93,15 +125,15 @@ 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. @@ -109,7 +141,7 @@ 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