====== File Naming Convention ======

How run folders are named and organized on the NAS. Follow this whenever you set up a run.



==== The Path ====

<code>
# General Form
<nas_root>/<equipment_name>/<project_id>/{EXPERIMENT|TEST}/<DATE>_<NICKNAME>/


# Example
//nas01/data/ucr_liquid_handler/UCR-005-I-D_Wheeldon/EXPERIMENT/2026-04-17-14_layer5-sweep/
</code>

| Tier | What it is | How it's set |
|---|---|---|
| `<equipment_name>` | The instrument | Fixed per instrument |
| `<project_id>` | Short project slug | Chosen once, when the project starts |
| `EXPERIMENT` or `TEST` | Real data, or not | Chosen when you start the run |
| `<DATE>_<NICKNAME>` | The run | Date from the clock; nickname is yours |

==== Why It Matters ====

Analysis picks up work by pattern-matching the tree. `*/*/EXPERIMENT/*` should be a complete list of every experimental run in the lab. A folder named off-convention doesn't error — it is silently skipped, which is worse.

==== Equipment and Project ====

**`<equipment_name>`** is fixed per instrument and spelled the same way every time. Use the exact string the lab has agreed on for that machine, not a variation.

**`<project_id>`** is a short slug, not a title. Set it once and never rename the folder — anything already pointing at it breaks.

<code>
UCR-005-I-D_Wheeldon
</code>

The readable project title belongs in the run README, where it can be edited freely.

The same project can exist under several instruments. Those are separate folders that happen to share a name.

Both use the same character rules as the nickname, below. Neither may be the literal word `EXPERIMENT` or `TEST`.

==== EXPERIMENT vs TEST ====

Two literal uppercase folders between the project and the run. Every run goes in one of them; a run folder never sits directly under the project folder.

**`EXPERIMENT/`** is data you intend to analyze.

**`TEST/`** is calibration, debugging, and smoke tests. Analysis skips it.

Unsure? Ask: if this run ended up in a figure, would that be wrong? If yes, use `TEST`.

Create both folders when you create the project, even if one stays empty. An empty `TEST/` means no test runs were taken — that's normal, not a broken folder.

**The run folder name carries no marker of which one it is.** `2026-04-17-14_calib` looks identical whether it's real data or a calibration sweep; only its parent folder tells you. So never classify a run by its name alone, and be careful when copying a run folder out of the tree — it loses that context.

==== The Date ====

**Year, month, and day are required. Hour, minutes, and seconds are optional.** All zero-padded, 24-hour clock, hyphen-separated.

<code>
2026-04-17              day        (10 chars)
2026-04-17-14           hour       (13)
2026-04-17-14-32        minute     (16)
2026-04-17-14-32-08     second     (19)
</code>

All four are valid. Add the time fields left to right: hour without minutes is fine, minutes without an hour is not.

Use the local clock on the instrument, so the folder matches what you saw on the console.

Still wrong:
<code>
2026-4-17               not zero-padded
2026-04-17-14-32-08-5   too many fields
2026-04-17-2pm          use 14
2026-04-17-14:32        no colons
</code>

Rigid because sorting the text gives the same order as sorting by time.

One caveat: that only holds when names use the *same* precision. `2026-04-17-14_x` sorts after `2026-04-17-14-32_x`, even though 14:00 came first. **Pick one precision per instrument and stick with it.** Busy instruments should use minute or second; one-run-a-day instruments can use day.

Same prefix and nickname already taken? Add `_02`, then `_03`:

<code>
2026-04-17-08_laser-power-check
2026-04-17-08_laser-power-check_02
</code>

==== The Nickname ====

**Anything you want.** If the date in front is correct, nothing cares what comes after the underscore. No vocabulary, no keywords. Nothing parses it.

<code>
2026-04-17-14_layer5-sweep
2026-04-17-14_plate3
2026-04-17-14_rerun-after-laser-swap
2026-04-17-14_v2
2026-04-17-14_asdf
</code>

Four rules, so the path survives every filesystem it touches:

| | |
|---|---|
| Characters | `A-Z` `a-z` `0-9` `.` `_` `-` only. No spaces, no accents, no emoji, no `/ \ : * ? " < > \|` |
| Length | 1 to 64 |
| Start | Letter or digit |
| End | Not a dot |

Spaces break shell scripts. Colons break Mac and SMB mounts. Accents break sync (macOS and Linux store them differently). Angle brackets look like unfilled placeholders.

**Suggestions, not rules:** describe the run, not the date or the project — both are already in the path. Reusing the same nickname across many runs is fine and reads well; the date makes them unique. Say *why* a run is unusual (`rerun-after-laser-swap`) rather than *what number* it is (`run2b-final-FINAL`).

==== Bad Names ====

| | |
|---|---|
| `2026-4-17-14_sweep` | Not zero-padded |
| `2026-04-17-32_sweep` | Hour out of range |
| `2026-04-17-14 sweep` | Space instead of `_` |
| `2026-04-17-14_layer 5` | Space in nickname |
| `2026-04-17-14_run:2` | Colon |
| `2026-04-17-14_François` | Non-ASCII |
| `2026-04-17-14_.hidden` | Starts with a dot |
| `2026-04-17-14_NUL` | Windows reserved name |
| `UCR-005-I-D/2026-04-17-14_sweep` | Missing the `EXPERIMENT`/`TEST` folder |
| `UCR-005-I-D/Experiment/...` | Must be uppercase |
| `UCR-005-I-D/EXPERIMENTS/...` | Singular |

==== Cheat Sheet ====

<code>
<nas_root>/<equipment_name>/<project_id>/{EXPERIMENT|TEST}/<DATE>_<NICKNAME>/

equipment_name   fixed per instrument, spelled the same every time
project_id       short slug, set once, never renamed
EXPERIMENT|TEST  literal, uppercase, pick one
DATE             YYYY-MM-DD required;
                 -HH, -HH-MM, -HH-MM-SS optional
_                the separator
NICKNAME         yours: A-Z a-z 0-9 . _ -   (1-64 chars, starts alphanumeric)
_02 _03          only if the name is already taken
</code>

Get the date right and the nickname is yours.