https://github.com/gosling-lang/streamlit-gosling
Gosling custom component for Streamlit
https://github.com/gosling-lang/streamlit-gosling
python streamlit-component visualization
Last synced: 5 months ago
JSON representation
Gosling custom component for Streamlit
- Host: GitHub
- URL: https://github.com/gosling-lang/streamlit-gosling
- Owner: gosling-lang
- License: mit
- Created: 2022-06-16T19:06:19.000Z (about 4 years ago)
- Default Branch: master
- Last Pushed: 2024-06-07T01:45:02.000Z (about 2 years ago)
- Last Synced: 2024-06-07T23:52:03.911Z (about 2 years ago)
- Topics: python, streamlit-component, visualization
- Language: Python
- Homepage:
- Size: 5.78 MB
- Stars: 8
- Watchers: 3
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
Awesome Lists containing this project
README
# Streamlit - Gosling
A Streamlit component to display [Genomic Visualization using Gosling](http://gosling-lang.org).
An online demo is host at [Streamlit Clound](https://wangqianwen0418-streamlit-gosling-demo-st-gos-demo-zo60pz.streamlitapp.com/).
Checkout the [code of the demo](https://github.com/wangqianwen0418/streamlit-gosling-demo/blob/main/st_gos_demo.py)
## Install
```shell script
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`
```python
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`
```python
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
)
```
- [docs of gosling grammar](http://gosling-lang.org/docs)
- [docs of gosling python package](https://gosling-lang.github.io/gos)
- [docs of streamlit](https://docs.streamlit.io/)
## 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
```python
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
```shell script
cd streamlit_gosling/frontend
npm install
```
- Python side
```shell script
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
```shell script
cd frontend
npm run start
```
- Python side
```shell script
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`