> For the complete documentation index, see [llms.txt](https://gaps.gitbook.io/gaps/jQBaAQpYuk4HtfLcsK7Y/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gaps.gitbook.io/gaps/jQBaAQpYuk4HtfLcsK7Y/m2.md).
# Module 2 - Preparation
[← Previous module](/gaps/jQBaAQpYuk4HtfLcsK7Y/m1.md) | [GAPS structure](/gaps/jQBaAQpYuk4HtfLcsK7Y/structure.md) | [Next module →](/gaps/jQBaAQpYuk4HtfLcsK7Y/m3.md)
***
## Module 2 - Preparation
Open Science requires effort beyond simply uploading files. Data, scripts, figures, and other materials often need organization, documentation, cleaning, and anonymization before they can be meaningfully shared. Careful planning from the start of the project is essential to streamline this process and maximize its efficacy.
## Learning objectives
By the end of this module, you will be able to:
* Adopt an artifact-oriented mindset throughout the research process.
* Organize project repositories with clear, consistent structures.
* Structure project environments and workflows to support future sharing and reproducibility.
* Distinguish raw, processed, and shareable data and handle each appropriately.
* Apply data curation and documentation practices.
* Apply anonymization strategies appropriate to quantitative and qualitative data.
* Align artifact contents with the associated publication.
* Prepare artifacts for sharing while balancing openness, accessibility, and ethical constraints.
## Prepare artifacts as part of the research process
> **Key principle:** Treat artifact preparation as an ongoing activity, not a final packaging step.
| Artifact-last workflow | Artifact-oriented workflow |
| ------------------------------------------------- | ----------------------------------------------------------- |
| Artifacts prepared only near submission | Artifacts developed continuously throughout the project |
| Data scattered across tools and folders | Structured and versioned data |
| Intermediate files overwritten or lost | Intermediate steps version-controlled |
| Key decisions undocumented | Decisions and results traceable |
| Manual, undocumented steps | Scripted and traceable processes |
| Collect data manually and store in spreadsheets | Use scripts to collect and store data in structured formats |
| Reconstruct workflow at the end | Maintain documentation throughout the process |
| Run analyses through manual steps | Automatically generate results, figures, and tables |
| High effort at submission time | Lower, incremental effort at submission time |
| Limited reproducibility, even by original authors | Reproducibility integrated into the workflow |
| Collaboration harder due to missing context | Shared workflows facilitate collaboration and onboarding |
In an artifact-oriented workflow, the final package is often already close to publication quality by the end of the project, requiring minimal additional preparation.
### Planning early
> **Tip:** Structure your project so that it can be directly shared as a replication package. Integrate all necessary components (data, code, documentation) consistently from the beginning.
Without an artifact-oriented approach, data may become disorganized or partially lost, important decisions may remain undocumented, and results may become difficult to reproduce, even by the original authors.
Early planning helps researchers:
* Improve repository organization from the start.
* Reduce rework at the end of the project.
* Improve traceability of decisions and results.
* Preserve version history and avoid losing intermediate outputs.
* Facilitate inspection, validation, extension, and comparison across studies.
* Anticipate ethical, legal, institutional, and consent-related constraints for data sharing.
Even when full sharing is not possible, plan appropriate documentation, metadata, anonymization strategies, and access conditions throughout the research process.
Support from co-authors also makes the process smoother.
### Choose file formats early
> **Tip:** Decide on file formats at the start of the project. Changing formats near the end may require time-consuming conversions or recreation of important files.
Prefer open, widely supported, and well-documented formats. Avoid proprietary or tool-specific formats whenever suitable alternatives exist.
| Content type | Recommended formats |
| ------------------- | -------------------------------------------- |
| Text documents | TXT, Markdown (MD), ODT, PDF/A, XML |
| Tabular data | CSV, TSV, JSON |
| Images | TIFF, PNG, JPG, SVG |
| Audio | WAV, FLAC, OPUS |
| Video | MPEG2, VP8, VP9, AV1, Motion JPEG 2000 (MJ2) |
| Compressed archives | ZIP, TAR.GZ |
Additional format guidelines:
* Prefer **machine-readable formats** for automated and reproducible workflows.
* When both human- and machine-readable representations are valuable, provide both.
* Example: CSV for automation and XLSX for manual inspection.
* **Avoid spreadsheet formats as the sole representation** of research data.
## Repository organization
> **Key principle:** The repository structure should capture the essence of the research process, making it clear how the study was conducted and how results were produced.
Discuss and align the repository structure with collaborators early in the project to reduce inconsistencies and facilitate artifact preparation later.
### Folder structure and directory organization
The folder structure should reflect the research workflow. Document the repository structure inside the artifact itself. It is especially important in large repositories with datasets, scripts, intermediate files, and generated outputs.
For detailed example and step-by-step instructions on how to describe this folder hierarchy to external users, see the [Structural Documentation section in Module 3](/gaps/jQBaAQpYuk4HtfLcsK7Y/m3.md#structural-documentation).
#### Separating raw and processed data
> **Rule:** Never manipulate original data files directly. Always generate derived files through scripts, stored in separate directories.
* Keep original data in a dedicated folder (e.g., `data-raw/`).
* Store cleaned/transformed data in a separate folder (e.g., `data-clean/`).
* Store cleaning scripts alongside the cleaned data to make the transformation reproducible.
Mixing raw and processed data in the same folders risks accidentally overwriting files, losing intermediate results, or making data transformations untraceable.
#### Naming conventions
Good naming conventions improve readability and reduce ambiguity, especially in collaborative or long-running studies.
> **Tip:** Keep naming consistent with the terminology used in the paper. Variable names, metrics, datasets, scripts, and outputs should map directly to the experimental setup and results described in the publication.
| Descriptive names ✅ | Generic names ❌ |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| - clean\_survey\_data.csv
- generate\_figures.py
- rq1\_results.csv
- interview\_protocol.md
| - final.csv
- script2.py
- new\_results.xlsx
- misc\_notes.txt
|
> **Consistency matters more than any particular naming style.** Avoid inconsistent abbreviations, duplicated patterns, or filenames that depend on personal interpretation.
## Reproducible environments
Artifacts may become difficult or impossible to execute when environment information is missing. Even when datasets, scripts, and documentation are publicly available, differences in operating systems, software versions, libraries, hardware configurations, or system settings may prevent workflows from executing correctly.
Many reproducibility problems emerge because artifacts implicitly depend on local machine configurations that are never documented. Common examples include missing dependency versions, OS-specific behavior, incompatible libraries, unavailable system tools, or hardcoded environment settings. As a result, workflows that function correctly for the original authors may fail when executed by others on different machines.
### What to document
Always document the execution environment used to develop and test the artifact:
* Operating system and kernel version.
* Hardware requirements (performance, storage, or non-commodity peripherals).
* All software dependencies and their exact versions.
* Experiment-specific tools, libraries, or frameworks.
* Any deviation from standard environments, with justification.
### Dependency specification files
Include a dependency specification file in the repository. These files preserve dependency versions, simplify environment reconstruction, and reduce inconsistencies across systems.
> **Tip:** Avoid hardcoded file paths and machine-specific settings. Use portable, repository-relative paths to improve portability across systems.
### Environment isolation
Virtual environments, containers, or virtual machines can isolate dependencies and simplify environment setup. Containers may also improve portability by distributing workflows together with the required execution environment. The goal is not to eliminate all setup complexity, but to ensure that environment requirements are identifiable, understandable, and executable by external users over time.
See [Module 4 - Reproducibility](/gaps/jQBaAQpYuk4HtfLcsK7Y/m4.md) for more details about containers, VMs, and dependency management strategies.
### Ease of use
* Users should be able to go from installation to a basic working execution within a reasonable amount of time.
* Ideally within one hour.
* If the full evaluation takes very long, provide a shorter representative subset to confirm the artifact works correctly.
* Provide small representative inputs for quick evaluation, or divide the workflow into independently executable parts, each producing results consistent with the paper.
* Individual steps should not take longer than 8-12 hours to execute.
* Long or complex setup procedures should be automated using containers or virtual environments.
## Scripts and workflow automation
> **Key principle:** Manual, undocumented workflows reduce reproducibility. Scripts make research processes traceable, repeatable, and easier to maintain.
### Prefer scripted workflows
* Use script-based, version-controllable tools (e.g., R, Python) over point-and-click software (e.g., SPSS without syntax) or binary project files (e.g., Excel).
* Make data cleaning reproducible. Provide scripts that perform all preprocessing steps and regenerate cleaned datasets from raw data automatically.
* Store scripts together with the artifact.
* Avoid workflow assumptions that depend on local or machine-specific configurations.
### Workflow orchestration
Explicitly define how outputs depend on inputs. Tools such as GNU Make allow researchers to document which commands generate which outputs and how files depend on one another.
A Makefile describes:
* **Targets:** what needs to be produced.
* **Dependencies:** which files the target depends on.
* **Commands:** the instructions executed to generate or update the target.
```
target: dependency1 ... dependencyN
command_to_generate_the_target
```
In the example below, the cleaned dataset `clean_data.csv` is generated from the raw datasets using the cleaning script. The figure `rq1_plot.png` is then generated from the cleaned dataset using the figure-generation script.
```makefile
# data/clean_data.csv depends on raw data and the cleaning script
data/clean_data.csv: data/raw/messy_data1.xlsx data/raw/messy_data2.csv scripts/clean_data.R
Rscript scripts/clean_data.R
# figures depend on clean data and the figure generation script
figures/rq1_plot.png: data/clean_data.csv scripts/generate_figures.R
Rscript scripts/generate_figures.R
```
If a dependency changes, Make automatically reruns the corresponding command to regenerate affected outputs. This helps keep derived datasets, figures, and results synchronized with their inputs while reducing manual effort and the risk of inconsistencies.
For more details, consult the [GNU Make manual](https://devdocs.io/gnu_make/).
### Automating outputs
> **Rule:** Figures, tables, and statistical summaries presented in papers should ideally be generated automatically from data and scripts, never manually edited.
* Provide a **single command or script** that runs the full experiment.
* Provide a **single script** that regenerates all relevant figures and results from the paper.
* Add scripts for build, execution, and preview.
* Use parameterized scripts with command-line flags to allow users to run specific stages or customize execution settings.
* Auto-generate plots directly from experimental results rather than asking users to manually inspect log files and compare numbers with figures.
Many programming environments support automated visualization workflows. You may use libraries in R, Python, or JavaScript to generate plots directly from experimental results.
### Version control
Version control systems preserve the history of scripts, data transformations, decisions, and workflow changes throughout the project. They facilitate collaboration by allowing multiple contributors to work on the same repository while maintaining traceability and consistency.
Without version control, it becomes difficult to track modifications, recover previous states, or understand how results were produced over time. For more details about versioning workflows, change logs, and the semantic difference between concept and version-specific PIDs, consult [Module 4 - Reproducibility](/gaps/jQBaAQpYuk4HtfLcsK7Y/m4.md).
## Data curation
The value of shared data depends on the quality of its documentation. Simply placing the data online without explanation of its content, structure, and origin is of limited value.
### What data artifacts should include
Data artifacts should document:
* How the data were collected.
* Preprocessing and cleaning procedures.
* Inclusion and exclusion criteria.
* Anonymization procedures applied.
* Ethical restrictions.
* Legal or licensing constraints associated with data sharing.
The documentation of non-executable artifacts (such as interview guides, protocols, codebooks, or qualitative datasets) should also explain how the materials can be interpreted and reused by other researchers or practitioners.
Technical documentation should be precise, covering each data field: variable names, metrics, units, and file structures.
### Aligning artifacts with the publication
* Align variable names, metrics, units, and outputs with those used in the paper.
* Guarantee that the artifact directly reflects the experimental setup described in the paper.
### Pre-publication checklist
Before sharing artifacts publicly:
1. **Translate materials to English.**
2. **Proofread and sanity-check** - review for typos, grammatical errors, and logical flow.
3. **Remove or anonymize sensitive data** - scrub internal comments, test credentials, personal data, and proprietary information.
4. **Verify links and references** - ensure all hyperlinks, cross-references, and embedded assets works.
5. **Apply consistent formatting** - fonts, spacing, headings, and code indentation.
6. **Define clear context and purpose** in the README:
* Include a succinct summary of the artifact.
* Be transparent.
* Avoid design decisions that belong in the paper.
* Include details that may appear trivial but are necessary to use the artifact.
7. **Choose appropriate formats and compression.**
* Archives: ZIP (`.zip`), tar+gzip (`.tgz`), or tar+bzip2 (`.tbz2`).
* Documents: `.txt`, `.html`, `.pdf`.
* Figures: `.png`.
8. **Configure permissions and access settings.**
9. **Confirm that all details needed for replication and reproduction are available.**
### When data cannot be fully shared
When the full dataset cannot be made publicly available, maximize transparency by:
* Sharing rich **metadata** describing the dataset's scope, structure, and characteristics.
* Sharing **process documents** explaining how, when, and where data were collected and processed.
* Clearly documenting **access conditions** - how and under which circumstances the full dataset can be accessed.
Even when the dataset cannot be shared at all, sharing metadata and process documentation increases transparency beyond what would otherwise be possible.
## Sensitive and restricted data
> **Key principle:** Privacy protection and data sharing are not mutually exclusive. Carefully evaluate what can be safely shared, partially shared, transformed, anonymized, or described through metadata only.
### Legal and ethical considerations
According to the Brazilian General Data Protection Law (LGPD - *Lei Geral de Proteção de Dados Pessoais*, Law No. 13,709/2018), personal data refers to any information related to an identified or identifiable natural person. Sensitive personal data includes racial or ethnic origin, religious beliefs, political opinions, trade union membership, health information, sexual life, and genetic or biometric data. These categories require special care during collection, storage, processing, and sharing.
Research Ethics Committees help researchers anticipate and address such concerns. **Explicit consent is required**, so researchers must obtain explicit permission from participants before publishing any data, clearly communicating what will be shared and how it will be used. Anonymization alone is not sufficient without proper consent agreements in place.
Ethical and legal constraints do not necessarily prevent data sharing, because sharing data is not a binary decision, but they often influence how data can be shared. Depending on the context, researchers may apply different levels of anonymization, filtering, access restriction, or confidentiality protection.
### Sharing strategies
Different strategies may be adopted depending on the sensitivity of the data:
| Strategy | When to use |
| --------------------------------------- | -------------------------------------------------------------------- |
| Share complete dataset | No restrictions apply |
| Share anonymized or filtered version | Sensitive identifiers present |
| Share only subsets | Parts of the dataset are shareable even when the full dataset is not |
| Controlled or restricted access | NDA or legal restrictions |
| Aggregated or transformed data | Individual-level data cannot be shared |
| Synthetic dataset | Full anonymization is not feasible |
| Metadata and process documentation only | Dataset cannot be shared at all |
A common practice is to maintain the original raw data in a **restricted (shadow) repository** while preparing a separate shareable version for public release. Clearly document how the shared version differs from the original, including any filtering, anonymization, aggregation, or transformation procedures applied.
For the technical implementation of this strategy, including how to set up access boundaries and write a Data Availability Statement (DAS) for industry partners, see the [Shadow Repositories section in Module 5](/gaps/jQBaAQpYuk4HtfLcsK7Y/m5.md#shadow-repositories) for further guidance on this approach.
Many datasets containing participant-level private information can be shared once de-identified using the **Safe Harbor method** or once an expert has determined the dataset is not individually identifiable using the **Expert Determination method**. Consult your Research Ethics Board or Institutional Review Board to learn how to apply these methods.
When a dataset cannot be safely de-identified, researchers can create and share **synthetic data**. This data is similar in structure, content, and distribution to the real data, designed so that statistical analyses return the same results.
> If confidentiality issues prevent public sharing, include a clear statement of the motivations in the `README.md`. Some venues accept private or password-protected access links when public release is not possible.
> **Warning:** Archived repositories are designed for long-term preservation. Once datasets are publicly released, removing them or fully undoing publication may be difficult or impossible. Verify anonymization, licensing, and documentation **before** publishing.
### Confidentiality and anonymity
* **Confidentiality** refers to protecting information from disclosure beyond the authorized research team.
* **Anonymity** is one form of confidentiality, specifically focused on preventing the identification of participants.
* In qualitative research, confidentiality may also require withholding parts of the data itself.
* Some information may remain too sensitive or identifying to share safely, even after anonymization.
## Anonymization strategies
> **Key principle:** Anonymization is an iterative process integrated throughout the research lifecycle, not a one-time task performed before submission.
In qualitative research especially, anonymization should be understood as a **continuum**. The goal is to reduce identification risk as much as reasonably possible while preserving the usefulness and analytical value of the data.
### Types of identifiers
Before sharing data, assess which elements may directly or indirectly identify participants or organizations:
| Type | Definition | Examples |
| ------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------- |
| **Direct identifiers** | Uniquely identify an individual | Full name, passport number, email address, photograph |
| **Strong indirect identifiers** | Can identify someone when combined with other data | Phone number, date of birth, employer name |
| **Indirect identifiers** | May contribute to identification in combination with other attributes | Age, city, occupation, education level |
### Anonymization methods
| Method | Description |
| -------------- | ----------------------------------------------------------------------------------------------------------- |
| **Remove** | Delete the information entirely |
| **Change** | Replace with a pseudonym or generic descriptor |
| **Categorize** | Generalize or group values (e.g., age ranges instead of exact age, regional reference instead of city name) |
> **Important distinction:** **Anonymization** irreversibly removes any possibility of identifying individuals. **Pseudonymization** replaces identifying information with artificial identifiers but allows re-identification if additional information is available. Pseudonymized data should still be treated as sensitive.
### Identifier classification and recommended actions
| Identifier | Direct | Strong indirect | Indirect | Recommended action |
| --------------------------------- | :----: | :-------------: | :------: | ------------------- |
| Personal ID (passport, CPF, RG) | ✓ | | | Remove |
| Full name | ✓ | | | Remove / Change |
| Email address | ✓ | ✓ | | Remove |
| Home address | ✓ | | | Remove |
| Phone number | | ✓ | | Remove |
| Postal code | | | ✓ | Remove / Categorize |
| City | | | ✓ | Categorize |
| State | | | ✓ | Categorize |
| Audio recording (voice) | ✓ | | | Remove |
| Video recording | ✓ | | | Remove |
| Photograph | ✓ | | | Remove |
| Date / year of birth | | ✓ | | Categorize |
| Age | | | ✓ | Categorize |
| Gender | | | ✓ | - |
| Marital status | | | ✓ | - |
| Occupation | | X | ✓ | Categorize |
| Employer / workplace | | X | ✓ | Categorize |
| Education level | | | ✓ | Categorize |
| Field of education | | | ✓ | - |
| Nationality | | | ✓ | Categorize |
| Vehicle registration number | | ✓ | | Remove |
| Web page address | | X | ✓ | Remove |
| Student ID / registration number | | ✓ | | Remove |
| IP address | | ✓ | | Remove |
| Health-related information\* | | X | ✓ | Categorize / Remove |
| Ethnic group | | X | ✓ | Categorize / Remove |
| Criminal or punishment history | | | ✓ | Categorize / Remove |
| Political or religious allegiance | | | ✓ | Categorize |
| Trade union membership | | | ✓ | Categorize |
| Sexual orientation | | | ✓ | Remove |
**X** *indicates the identifier may behave as a strong indirect identifier depending on context (e.g., rare populations, combination with other attributes).*
### Key practices
* Replacing names is usually **only the first step** - also evaluate indirect identifiers and combinations of attributes that together could enable re-identification.
* Replace identifiers with **pseudonyms or generic descriptors** - use bracket notation to clearly mark anonymized passages: `[a senior developer]`, `[a software company in Brazil]`.
* Maintain an **anonymization log** (de-anonymization key) of all replacements, aggregations, and removals - stored securely and separately from the anonymized data files.
* Use "search and replace" carefully to avoid unintended changes or missed misspellings.
* Apply pseudonyms and replacements **consistently** across the research team and across publications.
* Plan anonymization **at the time of transcription or initial write-up**, not only before submission.
* Beware of **over-anonymization**: removing too many contextual details may reduce the interpretability and analytical value of qualitative data.
* Be aware of **contextual identification risks**: in small populations, specialized institutions, or tightly connected communities, participants may remain identifiable even after names are removed, through uncommon experiences, institutional affiliations, or combinations of attributes.
* Recognize that anonymization may disproportionately obscure the experiences of minority or underrepresented participant groups, since uncommon characteristics increase identification risk.
Different stages of a project may require different levels of anonymization:
* An initial step may support internal sharing within the research team.
* Later steps may prepare excerpts or datasets for publication or archival.
* Public release typically requires stricter anonymization than internal collaborative use.
### Identification risks
Identification risks may come from different audiences:
* **Internal identification risk:** participants or people within the studied community recognize individuals through shared experiences or contextual details.
* **External identification risk:** outside audiences identify participants through publicly available information, media coverage, legal documents, or online content.
Researchers should evaluate both forms of risk when preparing qualitative data for sharing.
### Example: Anonymizing an interview transcript
**Study background:** A study investigating how software developers adopt new tools in their daily work. An interview was conducted with a senior developer from a mid-sized company in Brazil.
| Original transcript | Anonymized version |
| --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *"I'm Vando Azevedo, I work as a senior developer at Tech Solutions here in Recife. We started using CodeFlow around March this year."* | *"I'm \[a senior developer], working at \[a software company] in \[a large city in Brazil]. We started using \[a code review tool] earlier this year."* |
| *"Barbara, one of our junior developers, found it difficult to adapt."* | *"\[A junior developer] found it difficult to adapt."* |
| *"Our manager, Carol, organized some internal workshops. Our team is about eight people."* | *"\[The team manager] organized some internal workshops. Our team is \[a small team]."* |
**What was anonymized:**
| Information | Identifier type | Action |
| ---------------------------------- | -------------------------- | ---------------------- |
| Full name (Vando Azevedo) | Direct identifier | Removed |
| Company name (Tech Solutions) | Strong indirect identifier | Generalized |
| City (Recife) | Indirect identifier | Generalized |
| Tool name (CodeFlow) | Context-dependent | Generalized (optional) |
| Colleagues' names (Barbara, Carol) | Direct identifiers | Removed |
| Team size (8 people) | Indirect identifier | Coarsened |
> **Key takeaway:** Anonymization is not only about removing names. It involves identifying and handling combinations of information that could make individuals identifiable, even indirectly.
**Tool:** The UK Data Archive provides a [Text Anonymization Helper Tool](https://ukdataservice.ac.uk/app/uploads/md5_94fc0c2a25f3a75396059826a23b8224_textanonymisationhelpertool.zip), an MS Word macro add-on for aiding anonymization of qualitative data.
### Anonymizing quantitative data
* Remove or aggregate variables that directly identify individuals.
* Reduce the precision of variables such as age or place of residence. As a general rule, report the lowest level of geo-referencing that will not potentially breach respondent confidentiality.
* Generalize the meaning of detailed free-text variables by replacing potentially disclosive responses with more general descriptions.
* Restrict the upper or lower ranges of continuous variables to hide outliers or atypical values.
### Anonymizing qualitative data
Qualitative data is usually the most difficult to prepare for disclosure. It is personal and hard to anonymize within legal and ethical constraints.
Preparing qualitative data for sharing may require extensive manual review. Plan sufficient time and resources for:
* Removing direct identifiers.
* Evaluating indirect identification risks.
* Revising and checking excerpts.
* Preparing different sharing versions (e.g., internal version vs. public version).
Even when full anonymization is not possible, **at minimum share** the study protocol and coding schemas and coding rules used in the analysis. This allows reviewers and other researchers to assess the trustworthiness of the analysis process and understand how conclusions were drawn.
Audio and video artifacts may expose identifiable features such as voice, facial appearance, gestures, or environmental context. Discuss these risks with participants and consider whether voice alteration, image masking, selective editing, or restricted access are necessary before sharing.
Some excerpts may require stronger anonymization than others. Researchers may choose to:
* Isolate sensitive excerpts.
* Avoid linking excerpts from the same participant.
* Apply different pseudonyms for the same person across different publications or documents.
* Reduce cross-referencing between publications.
## Archival requirements for Open Science
Choosing the right archival platform is critical for long-term accessibility and citability.
### Where to publish
* Platforms not suitable as the sole archival repository:
* **GitHub, GitLab, Hugging Face** - Repositories can be renamed, modified, or deleted over time. Not designed for immutable, long-term archival.
* **Institutional, research group websites** - Frequently restructured. Links break when staff leave.
* **Employee web pages** - Taken offline when the employee leaves.
* **Google Drive, Dropbox, OneDrive** - Designed for backup/sync, not archival. URLs can be changed or deleted at any time.
* **ResearchGate, Academia.edu** - Not archival platforms. Content is volatile and not guaranteed to persist.
These platforms remain useful during development and collaboration, but must be complemented with dedicated archival repositories at publication time.
* Requirements for a valid archival platform:
* **Publicly accessible online** - no registration required for access.
* **Dedicated, immutable PIDs** - automatically generated, persistent identifiers (e.g., DOI, Handle, ARK, SWHIDs) that do not change, with a separate PID for each version.
* **Long-term maintainability** - the hosting organization must commit to maintaining access and URLs for the foreseeable future.
* Examples of archival platforms:
* **Zenodo** - for data, software, and general artifacts.
* **Figshare** - for data.
* **Dryad** - for datasets.
* **OSF (Open Science Framework)** - for organizing research projects, preregistration, collaboration, and sharing associated materials.
* **Software Heritage** - for source code.
* For papers and preprints:
* **arXiv** - for scholarly manuscripts and preprints.
Unlike repositories such as Zenodo and Dryad, which are primarily designed for archiving releases, OSF can also be used throughout the research lifecycle to organize projects, preregistration, protocols, datasets, and documentation.
Large-scale components such as trained neural-network weights or very large datasets may exceed the storage limits of traditional archival repositories. In these situations, community platforms such as Hugging Face can be used for active distribution, but researchers should also archive a version-specific snapshot, metadata record, or companion package in an archival repository (e.g., Zenodo) to obtain a persistent PID and ensure long-term preservation.
Regardless of whether artifacts are developed on GitHub, organized on OSF, or distributed through platforms such as Hugging Face, the version associated with a publication should be **archived in a dedicated archival repository that provides persistent identification and long-term preservation**.
See [Module 5 - Publishing](/gaps/jQBaAQpYuk4HtfLcsK7Y/m5.md#where-to-publish-artifacts) for more detailed guidance on where to publish artifacts.
### FAIR principles
Artifacts should comply with FAIR principles:
* Use searchable repositories and persistent identifiers.
* No restrictive or undocumented access procedures.
* Use open, standard, machine-readable formats.
* Provide sufficient documentation for reuse without author intervention.
* Structure and document datasets so they can be reused across multiple studies.
* Reusability is enhanced by open-source implementations and use of public benchmarks.
* When full openness is not possible, implement controlled access mechanisms that balance transparency with ethical and legal constraints.
* Adapt FAIR principles to sensitive data scenarios: maximize findability and accessibility through rich metadata and documented access conditions.
## Key takeaways
* Prepare artifacts **throughout** the research process, not only near submission time.
* Structure the project so it can be **directly shared as a replication package** from the start.
* Keep raw data **separate and untouched** - always transform via scripts that regenerate derived data.
* **Align artifact contents with the paper** - variable names, outputs, directory structure, etc.
* Document the **execution environment** explicitly.
* **Automate** workflows, figure generation, and table regeneration.
* Apply anonymization **iteratively and early** - it is a process, not a final one-time task.
* Balance privacy protection with the preservation of analytical value.
* Use **FAIR-compliant, persistent repositories** for archival.
* When full sharing is not possible, **maximize transparency through metadata**, process documentation, synthetic data, and clearly documented access conditions.
***
[Shared references used across modules.](/gaps/jQBaAQpYuk4HtfLcsK7Y/references.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, and the optional `goal` query parameter:
```
GET https://gaps.gitbook.io/gaps/jQBaAQpYuk4HtfLcsK7Y/m2.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.