FaceBase: craniofacial research data (open access): sample notebook
A worked notebook for FaceBase: craniofacial research data (open access), with 8 code cells and the output each one printed. On Scigantic it opens in a hosted JupyterLab with the dataset already mounted, so nothing is downloaded first.
- Provider
- FaceBase Consortium (University of Southern California; NIDCR, NIDCD)
- License
- Per dataset. Copyright is held by the contributing investigators; FaceBase Terms of Use for Open Access Data apply (cite the dataset DOI, do not redistribute files).
- Stored at
- www.facebase.org
- Access
- Free and public. No account with the data provider is needed.
- DOI
- 10.1177/00220345221107905
The notebook
FaceBase: craniofacial data, read in place
FaceBase is the NIH craniofacial research hub: about 1,070 open datasets of micro-CT, light-sheet and confocal imaging, ChIP-seq and RNA-seq, and expression tables, mostly from mouse and zebrafish. The preinstalled scigantic_facebase library searches it and reads its files over HTTP, so a 50 MB micro-CT scan can be looked at without downloading all of it.
Two things from FaceBase's Terms of Use shape how to use this: copyright stays with the contributing investigators, and the files are not to be passed on to other people, so send them to FaceBase instead. Cite every dataset you use. fb.cite() writes the citation.
import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
import scigantic_facebase as fb
%config InlineBackend.figure_formats = ["jpeg"]
%config InlineBackend.print_figure_kwargs = {"bbox_inches": "tight", "pil_kwargs": {"quality": 80}}
plt.rcParams.update({"figure.dpi": 100, "axes.spines.top": False, "axes.spines.right": False})
print("open datasets:", fb.count())
Output:
open datasets: 1074
1. Find data
search matches every word against the whole record, newest first, and treats species names as synonyms: "zebrafish" also finds "Danio rerio". Protected human-subjects datasets are left out, since their files need a data access request.
topics = ["cleft palate", "zebrafish", "mouse", "microCT", "scRNA-seq", "ChIP-seq", "enhancer", "human"]
counts = pd.Series({t: fb.count(t) for t in topics}).sort_values()
ax = counts.plot.barh(figsize=(6, 3), color="#2b6cb0")
ax.set_xlabel("open datasets mentioning the term")
for i, v in enumerate(counts):
ax.text(v + 4, i, str(v), va="center", fontsize=9)
plt.show()
hits = fb.search("cleft palate mouse", limit=6)
pd.DataFrame([{"rid": h.rid, "released": h.release_date, "title": h.title[:80]} for h in hits])
Output:
rid released title 0 9J-SPH8 2026-04-27 Visium HD gene expression patterns 1 AB-SJQA 2026-04-16 Mandible vs tongue involvement in cleft palate... 2 44-HVCJ 2024-01-11 BRD4 binds to active cranial neural crest enha... 3 48-EJN8 2023-11-13 Single cell RNA sequencing (scRNA-seq) of E13.... 4 3-JQMG 2021-11-05 Ap2: A standardized mouse morphology dataset f... 5 3-JVE6 2021-11-05 Shh: A standardized mouse morphology dataset f...
2. A thyroid atlas in 81 zebrafish heads
One project (McMenamin lab) scanned zebrafish from 12 to 25 mm standard length raised hypothyroid, euthyroid (normal) or hyperthyroid, one dataset per fish. Each scan is a zip of reconstructed TIFF slices, and a zip keeps its index at the end, so one slice costs one range request.
atlas = fb.microct.thyroid_atlas()
df = pd.DataFrame([{"condition": s.condition, "length_mm": s.standard_length_mm, "rid": s.dataset.rid} for s in atlas])
df.pivot_table(index="condition", values="length_mm", aggfunc=["count", "min", "max"])
Output:
count min max
length_mm length_mm length_mm
condition
euthyroid 27 12.0 25.0
hyperthyroid 27 12.0 25.0
hypothyroid 27 12.0 25.0
# The same body length in all three conditions; pick one with a single zip each.
L = 14.0
pick = {s.condition: s for s in atlas if s.standard_length_mm == L}
fig, axes = plt.subplots(1, 3, figsize=(11, 3.8))
for ax, cond in zip(axes, ["hypothyroid", "euthyroid", "hyperthyroid"]):
f = fb.files(pick[cond].dataset)[0]
with fb.microct.open_stack(f) as stack:
img = stack.read_slice(len(stack) // 2)
vox = stack.voxel_size_um
print(f"{cond:13s} {f.filename:16s} {len(stack)} slices, {vox:.1f} um voxels, {img.dtype}, "
f"fetched {stack.bytes_fetched / 1e6:.1f} MB of {f.size / 1e6:.0f} MB in {stack.requests} requests")
ax.imshow(img, cmap="gray", vmax=np.percentile(img, 99.8))
ax.set_title(f"{cond}, {L:g} mm", fontsize=10)
bar = 1000 / vox # 1 mm in pixels
ax.plot([20, 20 + bar], [img.shape[0] - 20] * 2, color="white", lw=3)
ax.axis("off")
plt.show()
Output:
hypothyroid HypoTH14.0mm3.zip 537 slices, 10.5 um voxels, uint8, fetched 2.8 MB of 27 MB in 3 requests euthyroid EuTH14.0mm1.zip 691 slices, 8.0 um voxels, uint16, fetched 2.9 MB of 47 MB in 3 requests hyperthyroid HyperTH14.0mm3.zip 438 slices, 10.5 um voxels, uint16, fetched 2.6 MB of 14 MB in 3 requests
These are three different fish, not registered to each other. Voxel size and bit depth differ between scans (8.0 and 10.5 micrometres, 8-bit and 16-bit here), so compare shape and structure, not raw intensities, and read stack.voxel_size_um before measuring anything.
# Reslice one scan into the plane perpendicular to the slices: read every 6th slice.
cond = "euthyroid"
f = fb.files(pick[cond].dataset)[0]
with fb.microct.open_stack(f) as stack:
step = 6
vol = stack.volume(step=step)
vox = stack.voxel_size_um
cor = vol[:, :, vol.shape[2] // 2] # (z, y) plane at mid-width
fig, ax = plt.subplots(figsize=(5, 4.5))
ax.imshow(cor, cmap="gray", aspect=step, vmax=np.percentile(cor, 99.8))
ax.set_title(f"{cond} {L:g} mm, reslice at mid-width ({vol.shape[0]} of {len(stack)} slices)", fontsize=10)
ax.axis("off")
plt.show()
Larger fish need several overlapping scans, so those datasets hold several zips. Each zip is one section of the head, named by scan number.
big = fb.get("2E-K5EG")
print(big.title)
pd.DataFrame([{"file": x.filename, "MB": round(x.size / 1e6)} for x in fb.files(big)])
Output:
microCT scan of 19.0 mm hypothyroid Danio rerio head
file MB
0 HypoTH19.0mm1.zip 33
1 HypoTH19.0mm2.zip 29
2 HypoTH19.0mm3.zip 56
3 HypoTH19.0mm5.zip 50
4 HypoTH19.0mm6.zip 34
3. Cite what you used
FaceBase asks for the dataset DOI, the project, and an acknowledgement of FaceBase itself.
for rid in sorted({s.dataset.rid for s in pick.values()}):
print(fb.cite(rid), "\n")
print(fb.project(fb.get("2E-DSTE")).name)
Output:
Sarah K. McMenamin, Stacy Nguyen, John Blythe. microCT scan of 14.0 mm euthyroid Danio rerio head. FaceBase Consortium https://doi.org/10.25550/2E-DSTE (2023). Sarah K. McMenamin, John Blythe, Stacy Nguyen. microCT scan of 14.0 mm hypothyroid Danio rerio head. FaceBase Consortium https://doi.org/10.25550/2E-JY5E (2024). John Blythe, Sarah K. McMenamin, Stacy Nguyen. microCT scan of 14.0 mm hyperthyroid Danio rerio head. FaceBase Consortium https://doi.org/10.25550/2E-YW1J (2024). Thyroid hormone mediates juvenile and adult craniofacial shape change in zebrafish
Where next
- fb.download(file, "data/") saves a file with an MD5 check, for tools that need a local path.
- fb.open_remote(file) gives any file as a seekable object that zipfile, tifffile and h5py can read in place.
- FaceBase's other large imaging formats are MINC, NIfTI and SCANCO AIM; nibabel reads the first two.
- If you publish with FaceBase data, tell them at help@facebase.org. Their Terms of Use ask for it.
Run it
Open this notebook to run it, see the dataset page for the full description, or browse the full catalog.