- Free software: MIT license
BasalCell is a cookiecutter template designed for reproducible and distributable bioinformatics data analysis. It streamlines the creation of isolated Python and R environments integrated within JupyterLab.
👀 See it in action: Check out the BasalCellDemo repository for a complete scRNA-seq workflow example.
@article{okano2026basalcell,
title={BasalCell: A project scaffold generator for bioinformatics analysis},
author={Okano, Yuji and Ishikawa, Tetsuo and Sakurada, Kazuhiro},
journal={bioRxiv},
pages={2026--05},
year={2026},
publisher={Cold Spring Harbor Laboratory}
}
- Poetry-managed Python environment: Pre-configured with
jupyterlaband essential data science tools. - Optional R Integration: Seamlessly setup an isolated R kernel using
renv. - Automated Documentation: Ready-to-use
Sphinxconfiguration (supporting MyST Markdown and Jupyter Notebooks). - One-command Workflow: Setup and launch everything via
make.
Before using BasalCell, ensure you have the following installed on your system:
Miniforge(This automatically providesPythonandpip)makegit
For macOS
Using Homebrew is the easiest way:
brew install miniforge make git
conda init zshFor Windows (WSL2 / Ubuntu)
Run the following command to install all the prerequisites at once:
sudo apt update && sudo apt install -y make gitThen, install Miniforge by downloading the official installer:
wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh"
bash Miniforge3-Linux-x86_64.sh -b -p $HOME/miniforge3
source $HOME/miniforge3/bin/activate
conda init bash
pip install -U cookiecuttercookiecutter git@github.com:yo-aka-gene/BasalCell.git💡 Note for GitHub authentication: Alternatively, you can install via HTTPS instead of SSH:
cookiecutter https://github.com/yo-aka-gene/BasalCell.git
Answer the prompts to define your project configurations:
- arguments:
project_name: name your project heredescription: description for your projectauthor_name: your name (required whencreate_packageistrue)email: your contact info (required whencreate_packageistrue)github_username: your GitHub IDpython_ver: the version of Python: choose from3.12,3.13, or3.14. Python 3.12 is covered by the full CI test suite.r_ver: the version of R: choose fromnone(then R setup will be omitted),4.3, or4.4.create_package: choosetrueif you will publish your project as a Python package; otherwisefalse
Once you've answered the prompts, the initialization script (make init) will automatically run to set up your environments.
Navigate to your project directory and run:
cd <your-directory-name>
make launchThen Jupyter Lab will pop up in your default browser.
Default token will be your project slug:
e.g., Your Project Name -> your_project_name
# For main analysis (e.g., polars, torch, scanpy)
make add-py PKG=polars
make add-py PKG="torch scanpy<1.12"
# Remove packages
make remove-py PKG=polars
make remove-py PKG="torch scanpy"
# Add/remove development tools
make add-pydev PKG=tqdm
make remove-pydev PKG=tqdmpip or poetry.
Use the BasalCell make commands to keep the environment configuration and lock files synchronized.
# Add R packages
make add-r PKG="ggplot2 dplyr Seurat DESeq2 org.Hs.eg.db"
# Remove R packages
make remove-r PKG="Seurat DESeq2"BasalCell installs R packages through Mamba when available and otherwise falls back to renv. remove-r removes packages according to their current package manager ownership.
Sometimes R packages require OS-level dependencies. If so, you can manage them to the Mamba env with make commands:
# Add system-level dependencies
make add-os PKG=perl
make add-os PKG="cmake cxx-compiler git>=2.30.0"
# Remove system-level dependencies
make remove-os PKG="cmake cxx-compiler git"install.packages, renv::install, mamba install, or apt-get.
Use the BasalCell make commands instead.
Create a new blank repository on GitHub:
- Repository name: the same as
<your-directory-name> - Add README:
OFF - Add .gitignore:
No .gitignore - Add license:
No license
Then, after generating your project, run:
cd <your-directory-name>
git add .
git commit -m ':tada: Initial commit from BasalCell template'
git remote add origin https://github.com/<your-id>/<project-name>.git
git push -u origin mainNote: During make init, git init has already executed.
Documentation is a cornerstone of the readability of your analysis code. Utilize the following frameworks to create your own documentation:
- Sphinx: A widely used framework for Python code documentation. BasalCell comes with a built-in system that allows you to easily write documentation in
.mdformat and build it into HTML. Please refer todocs/index.mdinside the generated project for syntax examples. - docstrings: If you create custom modules in directories like
toolswithin the generated project, or if you publish your project as a package, adding docstrings to your functions and classes will allow Sphinx to automatically build documentation for them. BasalCell supports the NumPy style by default. - Read the Docs: Hosts and publishes documentation directly from your GitHub repository. While BasalCell comes pre-configured with the basic settings, you will need to create a Read the Docs account, link it to your GitHub account, and import your repository to actually publish the documentation.
Once you are ready to build your documentation, run:
cd <your-directory-name>
make docsThis allows you to preview the documentation in your local environment. The output will be generated in docs/_build/html/.
The HTML files that will actually be published are automatically generated on the server when you push to the main branch.
As a placeholder for the README.md and documentation icon, the following image is inserted by default:
Please create your own icon image or graphical abstract and replace it accordingly.
Writing test code is crucial for verifying the behavior of your developed code. Additionally, linting is essential to improve code readability. BasalCell makes it easy to run tests and linters by utilizing the following frameworks:
- Pytest: The standard testing library for Python. Please refer to the official documentation on how to write test code, and place your tests in the appropriate paths within the
testsdirectory of your generated project. - Ruff: Performs linting and automatically reformats your
.pyand.ipynbfiles. In BasalCell, Ruff is integrated withpre-commit, meaning it will automatically run whenever you make agit commit. - GitHub Actions: A CI/CD platform. BasalCell is pre-configured to automatically run the aforementioned workflows on the server whenever a
pull requestis created orgit push origin mainis executed, ensuring code quality and reproducibility even during collaborative data analysis.
- Usage: select
r_verand an R kernel will be set in your Jupyter Lab env. - Analysis: run analysis codes in R using
.ipynbfiles and the R kernel in Jupyter Lab. - Documentation: While
nbsphinxhandles your Jupyter Notebooks, BasalCell usespkgdownto automatically generate a dedicated reference website for your custom R functions. Simply document your functions using standardroxygen2comments, and this R API site is seamlessly integrated and accessible directly from the main Sphinx documentation. When creating R-related documentation, make sure to runmake docslocally and commit the generated HTML files to the GitHub repository. - Test: use
testthatpackage.testthat.Rand test directory for Rtestthat/are all set intestsinside your project directory. - Linting:
pre-commitautomatically runs linting usinglintrandstyler. - CI/CD: GitHub Actions are also implemented for R language as well.
- BasalCell utilizes
GNU Maketo streamline complex CLI operations into simple one-liners. Please perform fundamental operations via themakecommands listed below.
| command | run when... | description |
|---|---|---|
init |
initializing environments | This command is automatically triggered in cookiecutter git@github.com:yo-aka-gene/BasalCell.git. Run this command when you reboot the environment after make terminate or when your cloned a repository based on BasalCell. |
launch |
launching Jupyter Lab | This connects Jupyter Lab and your default browser. Sometimes access token will be asked: the default token will be your project slug (e.g., Your Project-ABC -> your_project_abc) |
lock |
manually regenerating all lock files | Regenerates the Conda, Poetry, and, when applicable, renv lock files. Package-management commands such as add-* and remove-* automatically update the relevant lock files. |
dump-all |
exporting all version configurations as a matrix (after make lock) |
This exports version configurations of all packages (including Python, R, and System dependencies) as a matrix in the designated data format. Run make dump-all to have a csv file. For alternative file formats, ipc, feather, pq, and parquet are supported (designate them like make dump-all EXT=pq). |
dump-core |
exporting core version configurations as a matrix (after make lock) |
This exports version configurations of core packages (non-development Python and R packages) as a matrix in the designated data format. Run make dump-core to have a csv file. For alternative file formats, ipc, feather, pq, and parquet are supported (designate them like make dump-core EXT=pq). |
dump |
exporting queried version configurations as a matrix (after make lock) |
This exports version configurations of queried packages as a matrix in the designated data format (e.g., make dump KEYS='numpy DESeq2' EXT=pq). |
report |
exporting version configurations as a human-readable .md file (after make lock) |
This exports version configurations of queried packages as a md file. Pass KEYS=all, KEYS=core, or KEYS=<query> (e.g., make report KEYS='numpy DESeq2') to get necessary information. |
install |
copying existing enviroment | This command is automatically triggered in make init for cloned repositories. This reproduces locked environments. |
test |
unit test | This command is triggers unit test modules defined via pytest (test code deposited in tests/), doctest (Examples in docstrings), or testthat (test code deposited in <your_project_name>_rtools/tests/testthat/) if available |
docs |
building documentations | This command builds documentation HTML files with Sphinx or pkgdown. Created HTML files will pop in your default browser. |
terminate |
deprecating existing environment | Run make terminate init to restart the environment (e.g., when you got stuck with certain errors). |
| command | run when... | description |
|---|---|---|
add-py |
adding python package(s) | e.g., make add-py PKG='scanpy pandas numpy' |
add-pydev |
adding python package(s) for development | e.g., make add-pydev PKG=watchdog |
remove-py |
removing python package(s) | e.g., make remove-py PKG='scanpy pandas numpy' |
remove-pydev |
removing python package(s) for development | e.g., make remove-pydev PKG=watchdog |
| command | run when... | description |
|---|---|---|
add-r |
adding R package(s) | e.g., make add-r PKG='ggplot2 dplyr Seurat DESeq2 org.Hs.eg.db' |
remove-r |
removing R package(s) | e.g., make remove-r PKG='Seurat DESeq2' |
| command | run when... | description |
|---|---|---|
add-os |
adding OS software(s) | e.g., make add-os PKG='cmake cxx-compiler'. Use this command when Python/R packages require additional native or system-level dependencies. |
remove-os |
removing OS software(s) | e.g., make remove-os PKG='cmake cxx-compiler' |
| command | run when... | description |
|---|---|---|
bump-patch |
before git version patch |
A shortcurt for mamba run <mamba_env> poetry version patch |
bump-minor |
before git version minor |
A shortcurt for mamba run <mamba_env> poetry version minor |
bump-major |
before git version major |
A shortcurt for mamba run <mamba_env> poetry version major |
- Julia kernel
- Executable ipynb
- Yuji Okano
- GitHub: @yo-aka-gene
- email: yujiokano@keio.jp
Open for collaboration! Feel free to open issues or pull requests.
