# 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](https://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 | ✅ | ✅ | ✅ | ✅ | {% tabs %} {% tab title="Python" %} ```python from gofigr.jupyter import configure, FindByName configure( workspace=FindByName("Clinical Trial 42"), # ... ) ``` {% endtab %} {% tab title="R" %} ```r library(gofigR) gofigR::enable(workspace_name = "Clinical Trial 42") ``` {% endtab %} {% endtabs %} *** ## 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?** {% tabs %} {% tab title="Python (Jupyter)" %} Automatically when you load the GoFigr extension. The analysis is named after your notebook file: ```python %load_ext gofigr # Analysis "My_Notebook" is created (or reused) automatically ``` You can override the name: ```python from gofigr.jupyter import configure, FindByName configure(analysis=FindByName("Dose Response Analysis", create=True)) ``` {% endtab %} {% tab title="Python (Scripts)" %} Specified when you create a `Publisher`: ```python from gofigr.publisher import Publisher pub = Publisher(workspace="My Workspace", analysis="Batch Processing Results") ``` {% endtab %} {% tab title="R" %} Optionally specified when enabling GoFigr, or defaults to the document title: ```r library(gofigR) gofigR::enable(analysis_name = "Survival Analysis") ``` {% endtab %} {% endtabs %} *** ## 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?** {% tabs %} {% tab title="Python (Jupyter)" %} Automatically each time a plotting cell executes. GoFigr names figures based on the plot title or assigns a default name: ```python %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: ```python from gofigr.jupyter import publish, FindByName publish(fig=plt.gcf(), target=FindByName("Growth Curve", create=True)) ``` {% endtab %} {% tab title="Python (Scripts)" %} Created when you call `publish()`: ```python from gofigr.publisher import Publisher pub = Publisher(workspace="My Workspace", analysis="Analysis") plt.plot([1, 2, 3], [1, 4, 9]) pub.publish(plt.gcf()) ``` {% endtab %} {% tab title="R" %} Created when you call `publish()`: ```r library(ggplot2) p <- ggplot(mtcars, aes(x = wt, y = mpg)) + geom_point() + ggtitle("Weight vs MPG") publish(p, "Weight vs MPG") ``` {% endtab %} {% endtabs %} *** ## 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](#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:** {% tabs %} {% tab title="Python" %} Use GoFigr's tracked reading functions instead of pandas: ```python %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: ```python gf.sync.sync("data/patients.csv") ``` {% endtab %} {% tab title="R" %} Use `sync_workspace_asset()` to track data files: ```r library(gofigR) asset_rev <- sync_workspace_asset(gf, workspace_id, "data/patients.csv") ``` {% endtab %} {% endtabs %} ### 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](/features/story-mode.md). *** ## 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.gofigr.io/concepts/data-model.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.