Tutorials

There are two tutorials, each split into two pages. Both follow a full run of Starfold from the table to the written claim and show the exact output after every step.

Tutorial

Table

Choose it when

Digits: Tutorial: groups in the scikit-learn digits dataset, part 1 and Tutorial: groups in the scikit-learn digits dataset, part 2

The scikit-learn digits dataset: 1,797 images, 64 pixel columns, true classes known

You are new to Starfold, or you want to check a result against known classes.

APOGEE: Tutorial: two groups in the APOGEE DR19 example table, part 1 and Tutorial: two groups in the APOGEE DR19 example table, part 2

The APOGEE DR19 example table: 9,242 stars, 8 columns, no labels

You have a real table with no labels, and you want to see how to report the result.

Start with Tutorial: groups in the scikit-learn digits dataset, part 1. The APOGEE tutorial assumes you know the words the digits tutorial explains: flag, recurrence, count interval and co-association. The notebooks behind the tutorials are notebooks/01_digits.ipynb and notebooks/02_apogee.ipynb in the clone.

Page

What it covers

Tutorial: groups in the scikit-learn digits dataset, part 1

Load, run, flags, map, settings

Tutorial: groups in the scikit-learn digits dataset, part 2

Support, recurrence, group count, post hoc check, save

Tutorial: two groups in the APOGEE DR19 example table, part 1

Features, run, groups

Tutorial: two groups in the APOGEE DR19 example table, part 2

Co-association, copy and gap, calibration, reporting

Expected time

The time is compute time from the recorded runs on a laptop GPU with RAPIDS cuML. The time on a CPU is not measured, so expect longer. The time you need to read each tutorial is not measured.

Tutorial

Recorded run

Digits

93.9 s on a laptop RTX 3060 (search 77.4 s, refits 7.2 s), 314 fits (each fit is one UMAP plus one HDBSCAN run), 1,422 MB peak host memory.

APOGEE

163 s (search 140 s, refits 13 s), 334 fits, 1,684 MB peak host memory. The calibration test adds 2,176 s (1,938 fits).

What you need

  • Python 3.11 or 3.12.

  • A clone of the repository, because both tutorials use files that ship with the clone and not with the installed package. Install as in Install Starfold.

  • A graphics card is optional. Without one, Starfold runs on the CPU.

  • No knowledge of UMAP, HDBSCAN or Optuna. Each tutorial defines a word where it first appears, and the Glossary lists them all.

If you would rather run one call on your own table first, go to Your first run. If you want the ideas before the code, read Concepts.