Data Model

GoFigr organizes your work into a hierarchy that mirrors how data science and scientific computing projects are naturally structured: teams own projects, projects contain analyses, and analyses contain figures.

At a Glance

Organization
  └── Workspace
        ├── Analysis
        │     └── Figure
        │           └── Figure Revision  (images, code, metadata)
        ├── Asset
        │     └── Asset Revision  (data files)
        └── Story  (AI-generated presentations)

Object	What it represents	Created by
Organization	A team, lab, or company	GoFigr admin (Pro feature)
Workspace	A project or area of work	Web UI or client
Analysis	A notebook, script, or document	Client (auto) or Web UI
Figure	A named visualization that evolves over time	Client (auto) or Web UI
Figure Revision	A single snapshot of a figure—image, code, and metadata	Client (auto)
Asset	A tracked data file (CSV, Excel, Parquet, Jupyter notebook, etc.)	Client
Asset Revision	A specific version of an asset, identified by content hash	Client (auto)
Story	An AI-generated presentation or report built from figures	Web UI

---

Organizations (GoFigr Pro)

An organization represents a team, lab, department, or company. Organizations own workspaces and control who has access to them.

Key points:

• Every workspace belongs to exactly one organization.
• Organization members are assigned roles that determine what they can do across the organization’s workspaces.
• You can belong to multiple organizations
• Organization admins can set custom branding (e.g. company logo)

Membership roles (from most to least privileged):

Role	Can manage org settings	Can create workspaces	Can view all workspaces
Admin	✅	✅	✅
Workspace Admin	—	✅	✅
Workspace Creator	—	✅	Own only
Workspace Viewer	—	—	Assigned only

Organizations are managed through the GoFigr web UI at app.gofigr.io.

---

Workspaces

A workspace is your primary unit of organization in GoFigr. Think of it as a project folder—everything related to a particular project, study, or area of work lives in one workspace.

Key points:

• A workspace contains analyses, assets, and stories.
• Each workspace has its own set of members with independent access controls.
• When you run gfconfig, you select a default workspace that the Python and R clients use automatically.
• You can switch workspaces at any time in the web UI or override the default in your client code.

What belongs in a workspace:

A good rule of thumb is one workspace per project. For example, a clinical trial might have its own workspace, as would a machine learning experiment or a course you’re teaching. Related notebooks, figures, data files, and presentations all live together.

Workspace members have one of these roles:

Role	View content	Create analyses & figures	Manage members	Full control
Viewer	✅	—	—	—
Creator	✅	✅	—	—
Admin	✅	✅	✅	—
Owner	✅	✅	✅	✅

Python

from gofigr.jupyter import configure, FindByName

configure(
    workspace=FindByName("Clinical Trial 42"),
    # ...
)

R

library(gofigR)
gofigR::enable(workspace_name = "Clinical Trial 42")

---

Analyses

An analysis groups related figures together. It typically corresponds to a single notebook, script, or document.

Key points:

• Analyses live inside a workspace.
• In Jupyter, an analysis is created automatically using the notebook’s filename (e.g., exploration.ipynb becomes an analysis called “exploration”).
• In R, the analysis name defaults to the R Markdown document title or can be set manually.
• You can also create analyses manually in the web UI—for example, when importing figures from PowerPoint or Word documents.
• Analyses can be shared independently via link sharing, even if the rest of the workspace is private.

When are analyses created?

Python (Jupyter)

Automatically when you load the GoFigr extension. The analysis is named after your notebook file:

%load_ext gofigr
# Analysis "My_Notebook" is created (or reused) automatically

You can override the name:

from gofigr.jupyter import configure, FindByName

configure(analysis=FindByName("Dose Response Analysis", create=True))

Python (Scripts)

Specified when you create a Publisher:

from gofigr.publisher import Publisher

pub = Publisher(workspace="My Workspace", analysis="Batch Processing Results")

R

Optionally specified when enabling GoFigr, or defaults to the document title:

library(gofigR)
gofigR::enable(analysis_name = "Survival Analysis")

---

Figures

A figure represents a named visualization that can evolve over time. Each time you re-run a cell or script that produces the same plot, GoFigr creates a new revision under the same figure, building a complete version history.

Key points:

• Figures live inside an analysis.
• A figure has a name (e.g., “Survival Curve” or “PCA Scatter Plot”) and accumulates revisions over time.
• In the web UI, you browse figures and can drill into individual revisions or compare versions.
• Figures can be shared via link sharing or with specific users, independent of the parent analysis or workspace.
• Figures can also be imported from Git repositories, PowerPoint files, or Word documents through the web UI.

When are figures created?

Python (Jupyter)

Automatically each time a plotting cell executes. GoFigr names figures based on the plot title or assigns a default name:

%load_ext gofigr

import matplotlib.pyplot as plt

plt.plot([1, 2, 3], [1, 4, 9])
plt.title("Growth Curve")
# Figure "Growth Curve" is created (or a new revision is added if it already exists)

You can also publish manually with an explicit name:

from gofigr.jupyter import publish, FindByName

publish(fig=plt.gcf(), target=FindByName("Growth Curve", create=True))

Python (Scripts)

Created when you call publish():

from gofigr.publisher import Publisher

pub = Publisher(workspace="My Workspace", analysis="Analysis")

plt.plot([1, 2, 3], [1, 4, 9])
pub.publish(plt.gcf())

R

Created when you call publish():

library(ggplot2)

p <- ggplot(mtcars, aes(x = wt, y = mpg)) +
  geom_point() +
  ggtitle("Weight vs MPG")

publish(p, "Weight vs MPG")

---

Figure Revisions

A figure revision is a single snapshot of a figure at a point in time. It is the core unit of reproducibility in GoFigr—each revision captures everything needed to understand and recreate a visualization.

What a revision contains:

Component	Description
Image	The rendered figure in one or more formats (PNG, SVG, HTML for interactive plots)
Source code	The code cell or script that produced the figure
Metadata	Execution environment, library versions, timestamps, custom key-value pairs
Data	Inline data tables (DataFrames) embedded with the revision
Linked assets	References to tracked data files (see Assets below)

Key points:

• Revisions are immutable—once created, they don’t change. This guarantees reproducibility.
• Each revision has a unique ID and QR code, which appear below the figure in your notebook. Scanning the QR code or clicking the link takes you directly to that revision in the web UI.
• You can compare revisions side-by-side in the web UI to see how a figure evolved.
• Revisions inherit sharing permissions from their parent figure but can also be shared independently.

When are revisions created?

A new revision is created every time a figure is published. In Jupyter with auto-publish enabled, this means every time you execute a cell that produces a plot. In R, it happens every time you call publish(). Each run of your notebook or script adds a new revision, creating a full history.

---

Assets

An asset is a tracked data file in your workspace. While figures capture visualizations, assets capture the data that feeds into them—CSV files, Excel spreadsheets, Parquet datasets, and more.

Key points:

• Assets live at the workspace level (not inside an analysis), because the same dataset is often used across multiple analyses.
• Like figures, assets have revisions. Each time the file content changes, a new asset revision is created.
• Asset revisions are identified by a content hash: if the file hasn’t changed, no new revision is created. This is efficient and ensures you always know exactly which version of the data was used.
• When a figure is created from tracked data, the figure revision is automatically linked to the corresponding asset revision. This means you can always trace back from a figure to the exact data that produced it.

How assets get tracked:

Python

Use GoFigr’s tracked reading functions instead of pandas:

%load_ext gofigr

# Instead of pd.read_csv():
df = gf.read_csv("data/patients.csv")

# Now any figure created from df is automatically linked to this data version
plt.scatter(df['age'], df['biomarker'])
plt.title("Age vs Biomarker")

GoFigr supports read_csv, read_excel, read_json, read_parquet, read_feather, and read_pickle—all with the same API as their pandas equivalents.

You can also sync files manually:

gf.sync.sync("data/patients.csv")

R

Use sync_workspace_asset() to track data files:

library(gofigR)

asset_rev <- sync_workspace_asset(gf, workspace_id, "data/patients.csv")

Figures vs. Assets

	Figures	Assets
What they store	Visualizations (plots, charts, images)	Data files (CSV, Excel, Parquet, etc.)
Where they live	Inside an analysis	At the workspace level
Revisions contain	Images, code, metadata, data frames	File content
Created by	Publishing a plot	Tracking/syncing a data file
Relationship	A figure revision can link to asset revisions	An asset revision can be linked to many figure revisions

The link between figures and assets is what makes GoFigr’s traceability work: you can start from any figure and trace back through the code, the data, and the environment to fully understand how it was created.

---

Stories

A story is an AI-generated presentation or report built from a collection of figures. Stories bring your figures together into a narrative, with AI-generated titles, descriptions, and transitions.

Key points:

• Stories are created from the web UI by selecting figures within an analysis.
• The AI analyzes not just the images but also the source code, metadata, and data context to generate accurate technical descriptions.
• Stories can be exported as PowerPoint or Word documents.
• Like other objects, stories can be shared via link or with specific users.

To learn more, see AI Story Mode.

---

Sharing & Permissions

GoFigr provides two ways to share content:

Link sharing — Generate a public link for any analysis, figure, or asset. Anyone with the link can view the content without needing a GoFigr account.

User sharing — Share with specific GoFigr users, granting them access through their account.

Sharing can be configured at any level of the hierarchy. For example, you can share a single figure revision without exposing the rest of the analysis or workspace.

---

How It All Fits Together

Here’s a typical workflow showing how the data model comes to life:

1. You create a workspace for your project (e.g., “Lung Cancer Biomarkers”) through the web UI or during gfconfig setup.

2. You open a Jupyter notebook and load GoFigr. An analysis is automatically created from the notebook name.

3. You load data using gf.read_csv() (note gf, not pd) or similar. GoFigr creates an asset in your workspace and tracks the file version.

4. You create plots. Each plot becomes a figure, and each execution creates a new figure revision containing the image, code, and a link to the data asset.

5. You iterate. As you refine your analysis and re-run cells, new revisions accumulate under each figure, giving you a complete history.

6. You share results. In the web UI, you create a story from your figures. The AI generates a polished presentation that you export to PowerPoint and share with your team.

7. A colleague has a question about one of your figures. They scan the QR code below the figure, which takes them directly to the figure revision in GoFigr—complete with source code, data lineage, and execution context.