Skip to main content

Project Creation Tutorial

This tutorial shows how to:

  • Install light weight version of MDV
  • Prepare supported input files (.h5ad, .h5mu, .vcf)
  • Convert each to an MDV project using the mdvtools CLI
  • Optionally zip the output folder for use in MDV's UI
  • Upload a project via command line and the docker container
  • Upload a project into MDV via the web user interface

Installation​

Install MDV Lite using pip:

pip install mdvtools

This provides access to the mdvtools command-line tool.

Convert a scanpy .h5ad file to MDV Project​

scanpy to MDV project

1. Create a Sample .h5ad File​

import scanpy as sc
adata = sc.datasets.pbmc3k()
adata.write("example.h5ad")

2. Convert to MDV Format​

mdvtools convert-scanpy output_folder example.h5ad \
  --chunk_data \
  --add_layer_data=False \
  --max_dims=3 \
  --delete_existing

Optional: Zip the Output Folder​

mdvtools convert-scanpy output_folder example.h5ad --zip

You can upload the resulting .zip file to MDV's UI via "Import existing project" on the MDV home screen.

ChatMDV Projects​

ChatMDV uses scanpy objects to allow natural language interaction with the data set.

To do this it needs a copy of the scanpy .h5ad object into the project before zipping the directory. It is also setting a the chat_enabled: true flag in the project.

mdvtools convert-scanpy output_folder example.h5ad \
  --chatmdv \
  --zip

This will now allow the project to be uploaded to MDV and it will also be a compressed file with LLM compatibility.

Convert MuData .h5mu to MDV Project​

mudata to MDV project

1. Create a Sample .h5mu File​

import scanpy as sc
import mudata as mu

mu.set_options(pull_on_update=True)

adata1 = sc.datasets.pbmc3k()
adata2 = adata1.copy()
adata2.X *= 0.5
adata2.var = adata2.var.assign(dummy=1)  # minimal metadata to avoid error

mdata = mu.MuData({"rna": adata1, "atac": adata2})
mdata.write("example.h5mu")

2. Convert to MDV Format​

mdvtools convert-mudata output_folder example.h5mu \
  --chunk_data --max_dims=3 --delete_existing

Optional: Zip the Output Folder​

mdvtools convert-mudata output_folder example.h5mu --zip

Zipped projects can be uploaded directly in MDV's "Import existing project" interface.

Convert VCF File to MDV Project​

vcf to MDV project

1. Use or Download a VCF File​

curl -o variants.vcf.gz https://ftp.1000genomes.ebi.ac.uk/vol1/ftp/release/20130502/ALL.chr1.phase3_shapeit2_mvncall_integrated_v5b.20130502.genotypes.vcf.gz 
gunzip variants.vcf.gz

2. Convert to MDV Format​

mdvtools convert-vcf output_folder variants.vcf

Optional: Zip the Output Folder​

mdvtools convert-vcf output_folder variants.vcf --zip

You can upload the .zip to MDV's web UI using "Import existing project".

🌐 Serve an MDV Project Locally​

To serve and explore a project locally in the browser:

mdvtools serve output_folder

✅ Summary of CLI Commands​

Input TypeFile FormatCLI CommandSupports --zipUpload to MDV UI
Scanpy.h5adconvert-scanpy✅✅
MuData.h5muconvert-mudata✅✅
VCF.vcfconvert-vcf✅✅

All zip files generated using --zip can be directly uploaded to MDV's "Import existing project" screen.

CLI Help​

Use --help for usage instructions:

mdvtools --help
mdvtools convert-scanpy --help

Loading projects into MDV​

Via Terminal loading into docker​

sudo docker cp <host_project_path> <container_id>:/app/mdv/
docker exec -u 0 -it <container_id> chown -R 1000:1000 /app/mdv/<project_name>

Go to the root MDV URL and add /rescan_projects. For example:

http://locahost:8080/rescan_projects

If the above does not work, then restart the docker containers using:

docker restart <container_name_or_id>

Via the Web Interface​

See the YouTube clip here:

https://youtu.be/oW5v_0sSd68