# VibeTube-0 dataset — CNT chirality from TEM images

Data supporting: D. Tang, G. Raj, E. Picheau, S. Hasan, P.-X. Hou and C. Liu,
*VibeTube: a code for accurate extraction of CNTs' chirality from TEM images*,
Science and Technology of Advanced Materials (2026). DOI: 10.1080/14686996.2026.2705816

Analysis code (MIT license): https://github.com/tangdaiming/VibeTube-0

## Contents and paper mapping

| Folder | Contents | Paper |
|---|---|---|
| `data/simulated/6-0-to-25-25/` | 6,930 simulated TEM images (330 chiralities (6,0)-(25,25), defocus -10..+10 nm, 60 kV, 0.05 nm/px) + `summary.csv` (per-image ground truth) + `params.json` | Figs 2-5, S3-S9, Table 1; the 84.5 % / 92.3 % benchmark |
| `data/simulated/20-0-to-20-20/` | 441-image (20,0)-(20,20) series | diameter-mode companion notebook |
| `data/simulated/DWCNT_bundle/` | simulated DWCNT (10,5)@(20,3) and two-tube bundle images (`images/*.npy`) + reference panels | Figs S10, S11 |
| `data/simulated/robustness_20series/` | 19 clean base images (20,1)-(20,19) (`clean/*.npy`, 0.0127 nm/px) + `manifest.json` (ground truth) + robustness result tables + figure panels | Fig S12, practical usage guideline |
| `data/experimental/TEM_Experiment/` | 5 raw Gatan `.dm4` HRTEM images (60 kV) + preprocessed versions | Fig 6 |
| `data/experimental/defocus_series/` | 31 preprocessed images of one CNT, defocus -22.8..+22.8 nm + `df_series.csv` | Fig 7 |
| `data/experimental/g1/` | 67 preprocessed images of 50 FCCVD-grown CNTs | Fig 8 |
| `results_reference/` | analysis result tables and summary figures produced by the released code from these inputs | sources of Figs 5, 7, 8 |

Per-image acquisition metadata (pixel scale, voltage, magnification, orientation, ROI)
is in each folder's `params.json`.

## Using the data with the code

Get the code, then extract every dataset zip **at the repository root** (the folder
that contains `analysis/` and `simulation/`). The zips carry their internal `data/...`
paths, so extraction merges them into the layout the notebooks expect:

```
git clone https://github.com/tangdaiming/VibeTube-0
cd VibeTube-0
# extract each zip HERE -> data/simulated/..., data/experimental/..., results_reference/...
```

(The dataset's documentation files are named `DATASET_README.md` and
`DATASET_MANIFEST_sha256.txt` so they do not collide with the repository's own README.)

**Simulated benchmark** (uniform 0.05 nm/px):

```
python analysis/main.py --batch data/simulated/6-0-to-25-25 --scale 0.05
```

**Experimental sets** (per-image pixel scale from each folder's `params.json`):

```
python analysis/main.py --batch data/experimental/TEM_Experiment/preprocessed --params data/experimental/TEM_Experiment/preprocessed/params.json
python analysis/main.py --batch data/experimental/defocus_series --params data/experimental/defocus_series/params.json
python analysis/main.py --batch data/experimental/g1            --params data/experimental/g1/params.json
```

or open the corresponding notebooks: `analysis/chirality_analysis_experimental.ipynb`
(Fig 6 walkthrough), `..._experimental_df_series.ipynb` (Fig 7),
`..._experimental_g1.ipynb` (Fig 8). Expected outputs for every set are in
`results_reference/` for comparison.

**Your own experimental images**: run `analysis/preprocessing_dm4.ipynb` first
(orientation, rotation to vertical, ROI, background subtraction, normalization — it
writes the `.npy` files and a matching `params.json`), then analyze as above. Observe
the acquisition guidelines in the paper: one isolated straight SWCNT per region,
pixel size <= 0.05 nm/px, >= 15 nm of straight tube, dose >= ~1000 e/A^2,
defocus 2 < |df| < 10 nm.

## Notes

- `results_reference/simulated_6-0-to-25-25/chirality_analysis_summary.csv` is a
  from-scratch regeneration of the benchmark with the released code; it reproduces the
  paper's accuracy to within frozen-phonon statistics (84.1 % / 92.2 % vs the paper's
  84.5 % / 92.3 %). The simulated images themselves regenerate with
  `simulation/batch_nanotube_simulations.py` (parameters in the paper's Methods).
- Accuracy windows: the 92.2 % reference value is computed on the inclusive window
  2 ≤ |df| ≤ 10 nm (`results_reference/simulated_6-0-to-25-25/
  chirality_analysis_summary_excl_near_focus.csv`, 5,940 images);
  `chirality_analysis_summary_sweet_spot.csv` is a narrower ±2–5 nm subset (89.7 %),
  not the source of the headline window number.
- File-path fields inside `params.json` / `summary.csv` were reduced to file names
  (basenames) for the public deposit; all scientific content is unchanged.
- Preprocessed experimental images are float `.npy` arrays normalized as described in
  the paper's Methods; raw `.dm4` files are included for the Fig 6 set. In each
  experimental `params.json`, `file_name` refers to the shipped `.npy`; the original
  acquisition file name is preserved as `source_file`.

## License

CC BY 4.0 (Creative Commons Attribution 4.0 International).

## Checksums

SHA-256 for every file: `DATASET_MANIFEST_sha256.txt`.
