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

Run it

Open this notebook to run it, see the dataset page for the full description, or browse the full catalog.