> For the complete documentation index, see [llms.txt](https://docs.nuvolos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nuvolos.com/tutorials/tutorials-for-researchers/from-notebook-to-reproducible-result.md).
# From notebook to reproducible result
**What you will achieve.** \
By the end of this tutorial you will have run a complete analysis cycle (query → analyse → store), captured the working environment as a named snapshot, prepared a copy of it for an external reviewer, and exported the project as a portable Docker image you can hand to anyone, including someone outside your Nuvolos organisation.
**How long it takes.** \
About 60 minutes for the full cycle, depending on how much analysis you actually run. The export step itself can take a while in the background.
**What you need before you start.** \
You should have completed '[Your first research project](/tutorials/tutorials-for-researchers/your-first-research-project.md)' tutorial - that is, you have a research project on Nuvolos, you can navigate to it, and you have at least one application installed. You also need at least one dataset accessible from your project (either a Nuvolos table distributed to your instance, or a file you have already brought in).
{% stepper %}
{% step %}
### Step 1 - Run a complete analysis cycle
{% hint style="info" %}
The full reference, with both Matlab and RStudio code listed in parallel, lives in How-to › [Database research workflow](/how-to-guides/workflows-for-researchers/a-complete-database-research-workflow-matlab-and-rstudio.md).
{% endhint %}
A scientific workflow on Nuvolos breaks down into three steps that you'll do back-to-back, in the same application session:
* Query research-relevant data - pull what you need from a Nuvolos table or file.
* Analyse - transform, fit, summarise.
* Store - write the result back somewhere it will outlast your application session.
Open RStudio (or Matlab, or whichever language you prefer). The cycle in RStudio looks like this:
**Querying relevant data**
The example uses the Fama-French factor set available to demo users, joining a monthly stock series with the 5-factor table for one stock:
```sql
SELECT NAF.*, SM.MPRC, SM.MRET*100 AS SM_MRET_100, SM.MTCAP
FROM NORTH_AMERICA_5_FACTORS NAF
INNER JOIN TIME_SERIES_MONTHLY SM
ON SM.MCALDT = NAF.DATE
WHERE KYPERMNO = 14593
```
The code that executes the query, the above string is saved in `query_string`.
{% code overflow="wrap" %}
```sql
conn <- nuvolos::get_connection()
dataset_factor <- dbGetQuery(conn, query_string)
```
{% endcode %}
**Simple analysis**
Fit a linear regression on the data frame, write fitted values back into it:
{% code overflow="wrap" %}
```sql
dataset_factor$EXCESS_RETURN <- dataset_factor$SM_MRET_100 - dataset_factor$RF
mod <- lm(EXCESS_RETURN ~ (-1) + MKT_RF + SMB + HML + RMW + CMA, dataset_factor)
dataset_factor$FIT_FACTOR_5 <- mod$fitted.values
```
{% endcode %}
**Storing results**
Write the result back to the database as a new table:
{% code overflow="wrap" %}
```sql
DBI::dbWriteTable(conn, name="APPLE_5FACTOR_FIT", value=dataset_factor, batch_rows = 10000)
```
{% endcode %}
{% hint style="info" %}
**Same cycle, different language**
In Matlab the cycle looks identical: get\_connection() / select(con, query\_string) to query, fitlm() to fit, sqlwrite() to store.\
The pattern generalises to any Nuvolos-supported language: query, analyse, store.
{% endhint %}
{% hint style="success" %}
**Checkpoint**
You should now have a new table in your database - the result of the cycle, stored alongside the original data. This is the moment the analysis becomes a result rather than just a session.
{% endhint %}
{% endstep %}
{% step %}
### Step 2 - Capture the working environment as a named snapshot
A snapshot at this point is what makes the result *reproducible* - anyone restoring this snapshot will see the same files, the same installed packages, the same environment in which your result was produced. Without it, you have a result; with it, you have a result that someone else can reach by the same path.
From the left sidebar, hover the camera icon, click TAKE SNAPSHOT AND DESCRIBE, and give the snapshot a meaningful name. Convention from the Nuvolos team: snapshots that represent a stable, citable state of the data or analysis are often called "vintages", for example, "v1.0 - final analysis 2026-05". Add a description that captures what's specifically reproducible about this state (the query you ran, the regression spec, the package versions if you bothered to pin them).
{% endstep %}
{% step %}
### Step 3 - Prepare a copy for a reviewer
If you are publishing or peer-reviewing, a journal editor or external reviewer often needs to inspect or re-run your work. The clean way to do this on Nuvolos is to give them an exact copy of your environment - restricted to that copy, with no access to anything else in your organisation.
From the project containing your snapshot:
1. Create a new instance in the same space (Cogwheel → Project Users / Instances → + ADD NEW INSTANCE). Name it after the reviewer or the journal (e.g. "Reviewer copy - XYZ").
2. Distribute the snapshot from Step 2 to the new instance - go to your Master instance, stage the relevant files/tables/applications, open the distribute menu, and select the new instance as the target.
3. Invite the reviewer to the new instance as an Instance Editor. They can see and run everything in that one instance and nothing else in your organisation.
{% hint style="warning" %}
**Two limitations to know about**
**Anonymity:** This setup is not suitable for anonymous reviewers. As the space administrator, you create the instance and handle invitations directly, so you will always know the identity of users in your space.
**Role proliferation:** An Instance Editor can't invite further users. If a journal editor wants to bring in colleagues, they can't do so from this setup - you would have to invite each one yourself.
{% endhint %}
{% endstep %}
{% step %}
### Step 4 - Export the project for an external audience
If you need to hand the project to someone you can't invite to Nuvolos at all - a customer, a partner, an auditor, an external collaborator - exporting is the right tool. Application Export turns a Nuvolos application into a portable Docker image that can be deployed outside the platform.
You can export at two levels:
* The application only - share configuration and runtime setup, but not data, code, or files. Most common when working with third parties.
* The application together with its files - a complete (with caveats) snapshot of the project state, including file-based artifacts used by the application.
For the exact procedure, see [Application Export](/reference/applications/exporting-applications.md) in Reference. The procedure is documented end-to-end there; this tutorial focuses on the reproducibility flow rather than the export mechanics.
{% hint style="warning" %}
**Important caveats - read before relying on exports as a full handover**
**Licenses:** Nuvolos follows a bring-your-own-license (BYOL) model. To prevent accidental license leakage, license-based applications and license-related environment variables are NOT included in exports by default. If your use case requires a fully functional, licensed package, contact Nuvolos support to discuss options.
**Tabular data:** Data stored in Nuvolos Tables is not bundled with application exports. If your project depends on tabular data, export the relevant data to files (CSV, Parquet) and adapt your setup to work with file-based inputs where appropriate, taking licensing constraints into account.
**Container registry:** Application exports are pushed to Docker Hub by default. If you need to export to a different container registry, reach out to Nuvolos support.
{% endhint %}
{% hint style="success" %}
**You're done**
You have closed the loop from raw data to a result that another researcher - inside or outside Nuvolos - can reach by the same path. The combination of a named snapshot (for collaborators on Nuvolos), a reviewer instance (for journal editors), and an Application Export (for everyone else) covers the full range of "how do I share this so it's reproducible?".
{% endhint %}
{% endstep %}
{% endstepper %}
#### Where to go next
* To preserve and version multiple research vintages over time, see [How-to › Preserve and share results](/how-to-guides/workflows-for-researchers/when-you-are-done-exporting.md).
* To set up the data side properly - querying, importing, datasets - see [How-to › Set up a dataset](/how-to-guides/workflows-for-researchers/setting-up-a-dataset-on-nuvolos.md).
* If your analysis needs more compute, see [How-to › GPU computation](/how-to-guides/workflows-for-researchers/gpu-computation.md).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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.nuvolos.com/tutorials/tutorials-for-researchers/from-notebook-to-reproducible-result.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.