Visualizations

Generate shareable viewer links for workspace files and render publication-quality bioinformatics charts as PNG/SVG. Requires the files scope.

POST/v1/visualizations/viewer-urlfiles scope

Generate a shareable view.smarts.bio link for a workspace file. The URL is valid for 1 hour and opens the appropriate interactive viewer based on file format. Supports VCF, BAM/SAM, FASTA/FASTQ, PDB/mmCIF, and CSV/TSV.

Body field	Type	Description
file_path *	string	File path relative to workspace root (e.g. `/variants/annotated.vcf`).
workspace_id *	string	Workspace the file belongs to.
format	string	Override auto-detection: `vcf`, `bam`, `fasta`, `pdb`, `csv`.
expires_in	integer	URL validity in seconds (default 3600, max 86400).

from smartsbio import SmartsBio

client = SmartsBio(api_key="sk_live_...")
ws_id = client.workspaces.list()[0].id

# Upload and immediately get a viewer link
upload = client.files.upload("annotated.vcf", workspace_id=ws_id, path="variants/")

result = client.visualizations.viewer_url(
    file_path=upload["key"],
    workspace_id=ws_id,
)
print(f"Open in browser: {result['viewer_url']}")
print(f"Format detected: {result['format']}")
print(f"Expires in     : {result['expires_in']}s")

Format auto-detection by file extension

.vcf .bcf → variant viewer

.bam .sam .cram → alignment viewer

.fa .fasta .fastq .fq → sequence viewer

.pdb .cif .mmcif → structure viewer

.csv .tsv .txt → table viewer

POST/v1/visualizations/renderfiles scope

Submit an async render job that generates a plot from a workspace data file. Returns a job_id immediately. Poll GET /v1/visualizations/:job_id for status, or use the SDK's.wait_render() helper.

Body field	Type	Description
type *	string	Plot type — see table below.
file_path *	string	Path to the input file, relative to workspace root (e.g. `/results/data.csv`).
workspace_id *	string	Workspace for input/output.
options	object	Plot-type-specific options (see below).
output_format	string	`png` (default) or `svg`.
output_path	string	Destination folder in workspace (default `plots/`).

from smartsbio import SmartsBio

client = SmartsBio(api_key="sk_live_...")
ws_id = client.workspaces.list()[0].id

# Submit render job
job = client.visualizations.render(
    type="volcano_plot",
    file_path="/results/deseq2_results.csv",
    workspace_id=ws_id,
    options={
        "log2fc_col": "log2FoldChange",
        "pvalue_col": "padj",
        "gene_col": "gene_id",
        "threshold_fc": 1.0,
        "threshold_pvalue": 0.05,
        "title": "Treated vs Control",
    },
    output_format="png",
)
print(f"Render job {job['job_id']} queued")

# Wait until done
job = client.visualizations.wait_render(job["job_id"], workspace_id=ws_id)

# Download the plot
plot_path = client.files.download(job["output_path"], workspace_id=ws_id, dest="./plots/")
print(f"Plot saved to {plot_path}")
print(f"Viewer URL   : {job['preview_url']}")

Plot types

type	Input	Key options
volcano_plot	DESeq2/edgeR CSV	`log2fc_col`, `pvalue_col`, `gene_col`, `threshold_fc`, `threshold_pvalue`, `title`
manhattan_plot	GWAS summary stats CSV	`chr_col`, `pos_col`, `pvalue_col`, `snp_col`, `significance_line`
pca_plot	Count matrix CSV	`color_by`, `label_samples`, `components` (default [1,2])
heatmap	Count matrix CSV	`top_n`, `cluster_rows`, `cluster_cols`, `colormap`
coverage_track	BAM / bigWig	`region` (chr:start-end), `gene`, `height`
structure_3d	PDB / mmCIF	`color_by` (chain\|plddt\|bfactor), `highlight_residues`, `style` (cartoon\|surface\|stick)
pathway_map	Gene list / enrichment CSV	`pathway_id`, `highlight_genes`, `color_by_fc`

GET/v1/visualizations/:job_idfiles scope

Get the status of a render job. When completed, the response includes output_path (the saved PNG/SVG file path) andpreview_url (a short-lived viewer link).

job = client.visualizations.get_render("render_xyz789", workspace_id=ws_id)
print(f"Status     : {job['status']}")
if job["status"] == "completed":
    print(f"Output path: {job['output_path']}")
    print(f"Preview    : {job['preview_url']}")

End-to-end example: DEG analysis → volcano plot

Upload a count matrix, run differential expression, render a volcano plot, and share the result — all in one script.

from smartsbio import SmartsBio

client = SmartsBio(api_key="sk_live_...")
ws_id = client.workspaces.list()[0].id

# 1. Upload count matrix
counts = client.files.upload("counts.csv", workspace_id=ws_id, path="input/")

# 2. Run DEG analysis (async pipeline)
deg_pipeline = client.pipelines.create(
    tool_id="deseq2_analysis",
    workspace_id=ws_id,
    input={"file_path": counts["key"], "condition_col": "condition",
           "reference_level": "control", "treatment_level": "treated",
           "output_path": "results/"},
)
deg_pipeline = client.pipelines.wait(deg_pipeline["id"], workspace_id=ws_id,
    on_progress=lambda p: print(f"  DEG: {p['status']} {p['progress_pct']}%"))
results_key = deg_pipeline["output_paths"][0]
print(f"DEG results: {results_key}")

# 3. Render volcano plot (async)
render_job = client.visualizations.render(
    type="volcano_plot",
    file_path=results_key,
    workspace_id=ws_id,
    options={"log2fc_col": "log2FoldChange", "pvalue_col": "padj",
             "gene_col": "gene_id", "threshold_fc": 1.0, "threshold_pvalue": 0.05,
             "title": "Treated vs Control"},
    output_format="png",
)
render_job = client.visualizations.wait_render(render_job["job_id"], workspace_id=ws_id)

# 4. Download plot + get shareable link
plot_path = client.files.download(render_job["output_path"], workspace_id=ws_id, dest="./")
print(f"Plot saved   : {plot_path}")
print(f"Share link   : {render_job['preview_url']}")