GPTomics/bio-reporting-jupyter-reports

Version Compatibility

Reference examples tested with: jupyter 1.0+, papermill 2.5+

Before using code patterns, verify installed versions match. If versions differ:

• Python: pip show <package> then help(module.function) to check signatures
• CLI: <tool> --version then <tool> --help to confirm flags

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.

Jupyter Reports with Papermill

"Generate reproducible analysis reports" -> Execute parameterized Jupyter notebooks programmatically and export as HTML/PDF reports.

• Python: papermill.execute_notebook(input, output, parameters={...})
• CLI: jupyter nbconvert --to html notebook.ipynb

Parameterized Notebooks

import papermill as pm

# Execute notebook with parameters
pm.execute_notebook(
    'analysis_template.ipynb',
    'output_report.ipynb',
    parameters={
        'input_file': 'data/counts.csv',
        'condition_col': 'treatment',
        'fdr_threshold': 0.05
    }
)

Creating Parameterized Templates

Mark a cell with the parameters tag in Jupyter:

# Parameters (tag this cell as "parameters")
input_file = 'default.csv'
output_dir = 'results/'
fdr_threshold = 0.05

Batch Processing

import papermill as pm
from pathlib import Path

samples = ['sample1', 'sample2', 'sample3']

for sample in samples:
    pm.execute_notebook(
        'qc_template.ipynb',
        f'reports/{sample}_qc.ipynb',
        parameters={'sample_id': sample}
    )

Converting to HTML/PDF

# Single notebook
jupyter nbconvert --to html report.ipynb

# With execution
jupyter nbconvert --execute --to html report.ipynb

# PDF (requires pandoc + LaTeX)
jupyter nbconvert --to pdf report.ipynb

Best Practices

• Keep analysis code in cells, explanatory text in markdown
• Use parameters for all configurable values
• Include version information and timestamps
• Clear outputs before committing to version control

Related Skills

• reporting/quarto-reports - Alternative report format
• reporting/rmarkdown-reports - R-based reports
• workflows/rnaseq-to-de - Embed in workflows