making_code_ready.qmd

---
title: "Making Code Ready for Publication"
format: html
---

## Outline

- **Why** make your code ready for publication?
- **What** do you need to make it ready?
- **How** and where do you make it available?

## Who this is for

- Majority of us want to share analyses, not software
- Leverage some principles from software packaging to share scripts and notebooks
- Software packaging is its own topic


## Why?
![](project.png)

## Why: Documentation is Important

- Do it for Future You
- Others in your lab
- Others in your field

## Why: Reproducibility Matters

- [Duke Medicine biomarker scandal](https://www.science.org/content/blog-post/duke-cancer-scandal-and-personalized-medicine)
- Software is an important output

## Reproducibility is a Spectrum

- Do what you can
- Providing a good framework for running analyses

## Why: Languages are Moving Targets

- Packages may depend on certain versions of Python/R
- Dependency Hell
- Need a way to "freeze" or "pin" versions used in analysis

## Why: Reproducibility is an iterative process

- When possible, start from the beginning
- Use package management and environments from the start
    - `rv` / `uv` (in Package management session)
- Test out running scripts and notebooks as you go

# What: Parts of a Reproducible Project

## What: Minimum Information for Analyses

- Focus on Data Analysis in R / Python
    - Genomic analysis: future workshop?
- Organize your analysis in a folder and share in a repository
	- [ ] Notebook(s) / Scripts
	- [ ] Lockfile
	- [ ] Data (if small enough)
    - [ ] README

## Project Example:

```
my_project/                 ## Top level
├── data/                   ## Data directory
│   └── my_data.vcf  
├─- output/                 ## Share output    
└── 01_preprocessing.R      ## Scripts in order
└── 02_deseq2_analysis.qmd
└── 03_visualization.ipynb
├── renv.lock               ## R Packages 
├──	requirements.txt		## Python Packages
└── README.md
```

## What: Notebooks / Analysis Files
```
my_project/                ## Top level    
├── 01_preprocessing.R     ## Scripts in order
├── 02_deseq2_analysis.qmd
└── 03_visualization.ipynb
```

- Easiest: place in your root folder
- Number in order
	- `01_preprocessing.R`
	- `02_deseq2_analysis.qmd`
- Be sure to include a random seed for reproducibility

## Relative Paths

- Everything should be runnable from the top folder of the project. Put data in `data/` folder. Use relative paths from the top project folder:

```r
my_data <- readr::read_csv("data/datafile.csv")
```

- Ensures portability of project

Example of a reproducible project:

[https://github.com/biodev/beataml2_manuscript](https://github.com/biodev/beataml2_manuscript)


## What: Data in a Project
```
my_project/                ## Top level
├── data                   ## Data directory
│   └── my_data.vcf  
```

- Genomic and omics data is large
    - raw data is not practical for GitHub (100 Mb limit)
    - Store raw files in required respositories
- Supply intermediate formats used to do the analysis:
    - MAF
    - VCF
    - CSV

## What: A Note about data

[Reproducibility in the Genomics Era](https://pmc.ncbi.nlm.nih.gov/articles/PMC11312195/)

- Large genomic data - sharing raw data is impractical in a project
	- Use Intermediate formats instead, such as VCF files, CSV files
- With code, share metadata - list the files you processed
    - JSON files from workflows
    - Metadata / Experimental Design
        - Where does each sample fit into Experimental Design?


## Reproducible Environments

In order of complexity:

```{mermaid}
graph TD
A[Lockfile] --> B
B[Binder Ready] --> C
C[Dockerfile]
```

## What: Lockfile

```
my_project/                ## Top level
├── renv.lock   
├── requirements.txt
```

- List of packages and versions that you used in analysis
- Post analysis:
    - Python: `pip freeze > requirements.txt`
    - R: `renv::snapshot()`
- Talk about `rv` and `uv` in Package management session


## Lockfile Examples

::: {.panel-tabset}

## R

```r
{
  "R": {
    "Version": "4.2.3",
    "Repositories": [
      {
        "Name": "CRAN",
        "URL": "https://cloud.r-project.org"
      }
    ]
  },
  "Packages": {
    "markdown": {
      "Package": "markdown",
      "Version": "1.0",
      "Source": "Repository",
      "Repository": "CRAN",
      "Hash": "4584a57f565dd7987d59dda3a02cfb41"
    },
    "mime": {
      "Package": "mime",
      "Version": "0.7",
      "Source": "Repository",
      "Repository": "CRAN",
      "Hash": "908d95ccbfd1dd274073ef07a7c93934"
    }
  }
}
```

## Python 

```python
anyio==4.11.0
appnope==0.1.4
argon2-cffi==25.1.0
argon2-cffi-bindings==25.1.0
arrow==1.3.0
asttokens==3.0.0
async-lru==2.0.5
attrs==25.3.0
babel==2.17.0
beautifulsoup4==4.13.5
bleach==6.2.0
certifi==2025.8.3
cffi==2.0.0
[...]
```

:::


## What: Reproducing environment from lockfile

Give zipped folder to someone else or host on github

::: {.panel-tabset}

## Python

```python
venv
source venv/bin/activate
pip install -r requirements.txt
``` 

## R

```r
install.packages("renv")
renv::restore()
```

:::





## What: Making a Lockfile from your current project

::: {.panel-tabset}

## Python

```python
import session-info as si
# put this at the end of your notebook
si.show(na=True, os=True, cpu=False, jupyter=None, dependencies=None,  write_req_file=True, req_file_name="requirements.txt")
```

- Install the session-info module: 

## R

```r
renv::snapshot()
```

- Can use the `renv` package to generate a current list of packages
- Does not require a virtual environment to be initialized

:::

## Why not Conda?

Anaconda is charging institutions for using their forge - be aware that you will need to pay charges or change your forge to the Fred Hutch version.

For more info: <https://conda-forge.fredhutch.org/>

## What: Binder Ready Repository

A special way to share your analysis

- Put your project on GitHub
- Can plug your repository link into `mybinder.org`
- Generates JupyterLab / RStudio / Shiny Server instance


## What: Binder.org

![](binder.jpg)

## How does Binder work?

- Uses `requirements.txt` (Python) or `install.R` (R) or Dockerfiles in your repository
- Installs relevant packages 
- Launches your analysis in a container (Dockerizes your analysis)


## Some Cons about Binder

- Currently limited to 1 Gb of memory for an instance
- 

## Dockerfile

Takes a lot of work, builds on the work of others

A precise list of instructions to install your computational environment.

More useful if you are distributing software. 

## Dockerfile Tips

- Don’t try to create Dockerfiles from scratch
    - Community Images: BioC, Rocker Project, WILDS Docker Library
    - Use https://repo2docker.readthedocs.io/en/latest/
        - https://repo2docker.readthedocs.io/en/latest/configuration/#config-files


## Nix

- Currently investigating Nix as a language agnostic reproducibility framework


## What: README

```
my_project/                ## Top level
└── README.md
```

![workflow.png](workflow.png)

- First thing that people will see
	- https://github.com/biodev/HNSCC_Notebook
- Document the basic workflow of processing
	- How does the data come together in the analysis?



# How

## How and Where: Testing your shared project

- Try downloading and installing on a different computer to make sure that you can rerun analyses
- Take someone else through the process and test out the notebooks
- If making binder ready: test the repository on Binder


## How: Review Opportunities

- Review Opportunities
    - Data House Calls
    - PyOpenSci and ROpenSci for code review if you decide to package your code
    - WILDS WDL Library
    - WILDS Docker Library (?)
        - If you’re making a package

## How and Where: Sharing Your Analyses

- GitHub (for code)
- Open Science Framework (for code + data)
- Field specific databases
- Social Media: LinkedIn, Bluesky, etc.

## Where should you share code?

Share in a public repository:

- GitHub
- Codeberg
- ReadtheDocs

Be aware of file size limitations! 

## How: Data Repositories

- Data repositories
	- Open Science Framework
	- Required databases (dbGAP)
	- Be aware that you will need to provide metadata
		- Experimental design
    - Be careful when sharing human subjects data
        - If unsure, schedule a Data Governance House Call


## References

- <https://book.the-turing-way.org/reproducible-research/compendia/>
- https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1005510
- https://openscapes.github.io/series/core-lessons/coding-strategies.html
- https://hutchdatascience.org/Tools_for_Reproducible_Workflows_in_R/index.html
- https://www.nature.com/articles/s41467-021-25974-w
- https://journals.plos.org/plosone/s/materials-software-and-code-sharing - Materials, Software and Code
- https://osf.io/cb7z8/files/numa5 - AGILE Reproducible Paper Guidelines
- https://binderhub.readthedocs.io/en/latest/overview.html


Source: https://book.the-turing-way.org/reproducible-research/code-reuse

## Outline (old)

- Defining reproducibility
    - https://osf.io/numa5 reproducible paper checklist
    - [NIH Best Practices for Sharing Software](https://datascience.nih.gov/tools-and-analytics/best-practices-for-sharing-research-software-faq#:~:text=Making%20software%20and%20code%20%E2%80%9Copen,accessible%20repository%20with%20version%20control)
- Repeatable
    - The GitHub Ecosystem + Zenodo
    - Open Science Framework
- Re-runnable
    - Documentation
    - Functions
    - Packaging
- Portable
    - Containerization
    - Starting points
    - BinderHub
    - GitHub Codespaces