Skip to content

Latest commit

 

History

History
222 lines (168 loc) · 5.78 KB

readme.md

File metadata and controls

222 lines (168 loc) · 5.78 KB

Streamlit - Gosling

A Streamlit component to display Genomic Visualization using Gosling.

An online demo is host at Streamlit Clound.
Checkout the code of the demo

Install

pip install streamlit gosling streamlit-gosling 

Usage

This library provides 2 functions to display gosling visualization :

  • from_gos to display visualization from a gosling instances. Make sure you have gosling installed via pip install gosling.
  • from_json to display visualization from Golsing spec in the form Python dict.

using from_gos

import streamlit as st
import gosling as gos
import streamlit_gosling as st_gos

size = 500


# create visualization using gosling
@st.cache_data
def chart():
    data = gos.matrix("https://server.gosling-lang.org/api/v1/tileset_info/?d=leung2015-hg38")
    return gos.Track(data).mark_bar().encode(
        x=gos.X("xs:G", axis="bottom"),
        xe="xe:G",
        y=gos.Y("ys:G", axis="left"),
        ye="ye:G",
        color=gos.Color("value:Q", range="hot", legend=True),
    ).properties(width=size, height=size).view()

# wrap gosling visualization as a streamlit component
st_gos.from_gos(
    spec=chart(), 
    id='id', 
    height=size+ 100
)

using from_json

import streamlit_gosling as st_gos

spec = {
  "title": "Basic Marks: bar",
  "subtitle": "Tutorial Examples",
  "tracks": [
    {
      "layout": "linear",
      "width": 800,
      "height": 180,
      "data": {
        "url": "https://resgen.io/api/v1/tileset_info/?d=UvVPeLHuRDiYA3qwFlm7xQ",
        "type": "multivec",
        "row": "sample",
        "column": "position",
        "value": "peak",
        "categories": ["sample 1"],
        "binSize": 5
      },
      "mark": "bar",
      "x": {"field": "start", "type": "genomic", "axis": "bottom"},
      "xe": {"field": "end", "type": "genomic"},
      "y": {"field": "peak", "type": "quantitative", "axis": "right"},
      "size": {"value": 5}
    }
  ]
}

st_gos.from_gos(
    spec=spec, 
    id='gos_bar', 
    height= 200
)

API

streamlit-gosling API

from_gos(id: string,
    spec: a gosling visualization object,
    height: number,
    exportButton: boolean,
    eventType?: 'mouseOver' | 'click' | 'rangeSelect',
    api?
)
from_json(id: string,
    spec: a gosling JSON spec as python dicts
    height: number,
    exportButton: boolean,
    eventType?: 'mouseOver' | 'click' | 'rangeSelect',
    api?
)
  • id: string

  • spec: a visualization object created using Gosling or a gosling JSON spec as python dicts

  • height: number

  • exportButton: boolean, whether to include the export button in the gosling component

  • eventType: string, one of 'mouseOver', 'click', and 'rangeSelect'. If specified, the event data of the specified mouse event will be returned by the streamlit-gosling component.

  • api: Call an api function of the gosling visualization. Three types of api actions are currently supported.

    • { action: "zoomTo", viewId: string, position: string, padding?: number, duration?: number }
    • { action: "zoomToExtent", viewId: string, duration?: number}
    • { action: "zoomToGene", viewId: string, gene: string, padding?: number, duration?: number }

    example

    import streamlit as st
    from streamlit_gosling as st_gos
    
    # user select a chromosome using streamlit select box
    chr = st.select('zoom to a chromosome', [str(i) for i in range(1, 20)])
    
    # the visaulization will zoom to different chromosome based on users' selection above
    st_gos.from_gos(
        spec=/****/, 
        id='id', 
        height=350, 
        api={'action': 'zoomTo','viewId': 'track-1', 'position': f'chr{chr}'}
      )

Development

Make sure _RELEASE = False in streamlit_gosling/init.py

Install

  • JS side
cd streamlit_gosling/frontend
npm install
  • Python side
conda create -n streamlit-gosling python=3.9
conda activate streamlit-gosling
pip install -e .

Run

You need to run both the JS side and the Python side for development mode.

  • JS side
cd frontend
npm run start
  • Python side
streamlit run streamlit_gosling/__init__.py

Test Before Publish to PYPI

  1. set _RELEASE = True in init.py

  2. check the version number in setup.py

  3. run . publish-script.sh

  4. answer yes for uploading to test.pypi for testing. twine will prompt you for a username and password. For the username, use __token__. For the password, use API token.

  5. download and test pip install --index-url https://test.pypi.org/simple/ --no-deps streamlit-gosling