FigureYa Help

How to Run FigureYa in Wisp Science

Update (2025): This page was originally a VS Code setup tutorial. We now recommend >Wisp Science — it has built-in R and Python kernels, no extension or path configuration needed, and works out of the box.

1. Install Wisp Science

  1. Download & Install:
    - Visit the >Wisp Science download page and choose your OS and processor.
    - macOS: signed & notarized .dmg; Windows: signed MSI; Linux: .deb / AppImage.

  2. Install R (if not already installed):
    - Wisp Science requires R to be installed on your system. Download it from >r-project.org.

  3. Add a Model:
    - Open Wisp Science → Settings → Models and add your model (supports OpenAI-compatible and Anthropic models).
    - You can also open the bundled demo project (no API key needed) to explore first.

2. Get FigureYa

Option A: Use natural language in Wisp Science (simplest)

Just tell the AI in Wisp Science's chat:

"Clone the FigureYa repository for me"

The AI will run git clone automatically — FigureYa will be in your project directory when it's done. If you only need one module:

"Download the FigureYa59volcanoV2 module for me"

Option B: Git Clone

Run in Wisp Science's terminal:

git clone https://github.com/ying-ge/FigureYa.git

Option C: Download ZIP

Go to the >FigureYa repository, click Code → Download ZIP, and extract to your project directory.

Option D: Fork and clone your own copy

See Why use Fork.

Option E: Download a single module from the gallery

If you only need one FigureYa module, there's no need to clone the entire repo:

  1. Open the >FigureYa Gallery and browse the thumbnails to find the module you need.
  2. Hover your mouse over a thumbnail — a download option for that module will appear. Click to download the individual module file.
  3. Place the downloaded file in your project directory and you're ready to go.

🇨🇳 Faster download for users in China: If GitHub is slow, use the mirror site >https://figureya.online/ — same steps, faster speeds.

3. Run FigureYa Modules

First: Run the example to confirm the module works

Before using your own data, run the example data once to confirm the output meets your expectations.

Open the FigureYa project in Wisp Science and tell the AI:

"Run the FigureYa59volcanoV2 module"

The AI will:
1. Read the module's .Rmd file
2. Execute it in the built-in R kernel
3. Output figures and results
4. Record the run history

💡 You can also render the entire file manually:
R rmarkdown::render("FigureYa59volcanoV2.Rmd")

Replace Example Data with Your Own Data (Most Common Need)

Every FigureYa module comes with example data. What you care about most is: how do I plug in my own data and get the same figure?

Step 1: Check what data the module needs

Tell the AI:

"What input data does FigureYa59volcanoV2 need? What format?"

The AI will read the .Rmd file and tell you:
- Input file format (e.g., CSV, TSV)
- Required columns (e.g., gene, logFC, PValue)
- Data types for each column (numeric, character)
- Whether annotation columns are needed (e.g., gene Symbol)

Step 2: Let the AI inspect your data

After placing your data file in the project directory, tell the AI:

"This is my differential expression result file DEG.csv. Check if it meets the requirements of FigureYa59volcanoV2"

The AI will:
1. Read your file and automatically profile the data (rows, columns, field names, data types, missing values)
2. Compare it against the module's input contract
3. If column names don't match, tell you which ones to rename
4. If data types are wrong, flag fields that need conversion

Step 3: Let the AI adapt the script

Tell the AI:

"Replace the example data with my DEG.csv and run FigureYa59volcanoV2"

The AI will:
1. Copy the module script to your working directory (or edit in place)
2. Change the data path from the example file to your file
3. Adjust column name mapping (e.g., module uses Gene, your file uses gene_name — AI maps them automatically)
4. Handle data type conversions (e.g., string P-values to numeric)
5. Run the adapted script and generate the figure
6. Compare the output with the example to confirm the result is reasonable

Step 4: Fine-tune the figure

Got the figure but want to tweak it? Keep talking to the AI:

"Change the P-value threshold to 0.01, make the labels bigger, use red-green colors"

The AI modifies and re-renders directly in the persistent R kernel — variables and intermediate results are preserved, no need to start over.

Tips for Replacing Data

Tip Description
Read the input contract first Ask the AI what format the module needs before preparing your data
Match column names Column names in the script must match your data — AI can auto-map them
Fix the file path Change the example data path to your file path, or place your file where the module expects it
Start small Test with a small subset first, then switch to the full dataset
Use the here package Use library(here) for relative paths, avoid hardcoding absolute paths
Check data types String-encoded numbers, factor levels, missing-value symbols (NA/blank/-) can all cause errors

⚠️ Common errors: Most failures are not code bugs — they're data format mismatches: column names don't align, data types are wrong, or file paths can't be found. Having the AI profile your data first prevents 90% of these issues.

4. Why Is This Easier Than VS Code?

What you had to do in VS Code In Wisp Science
Install R extension, Code Runner, Markdown plugins Built-in R kernel, no extensions needed
Configure R path (r.rterm.windows, etc.) Auto-detected, or one click in Settings
Manually set working directory with setwd() Project root is the working directory
AI can only chat, cannot touch files AI directly reads/writes files, runs code, makes figures
No way to undo after an error Undo a turn's file edits
Need separate Python env for mixed analysis Python and R kernels coexist, variables persist

5. Common Issues

  • R not detected?

  • Check the R interpreter path in Settings, or confirm with which R.

  • Missing R packages?

  • Just ask the AI: "install the R packages needed for this module."

  • Want to run on a remote server?

  • Register an SSH host in Settings → Compute to submit long-running tasks remotely.

Next Steps

Note: If you are still using VS Code, the original setup guide remains available as a reference.