Migrating from the `--basedir` Layout

This page describes how to move from the older instrument-first raw directory layout (used with the --basedir flag) to the current mooring-first layout (used with --raw-dir and --proc-dir).

What changed

Raw directory layout

In the old layout, raw files were organised by instrument type first, with mooring subdirectories beneath:

{basedir}/raw/
└── microcat/
    └── dsG3_1_2026/
        ├── 5367_recovery.asc
        └── 26261_recovery.asc

In the new layout, mooring directories come first and instrument subdirectories appear beneath them:

{raw_dir}/
└── dsG3_1_2026/
    ├── microcat/
    │   ├── 5367_recovery.asc
    │   └── 26261_recovery.asc
    └── aquadopp/
        └── A400115_dsG3.aqd

CLI flags

The --basedir flag is replaced by two separate flags:

--raw-dir — points to the cruise-level directory that holds raw instrument data.
--proc-dir — points to the cruise-level directory that holds processed data and YAML files.

For a cruise where basedir was /data/cruise2026, the equivalent new flags are:

# Old
oceanarray process dsG3_1_2026 --basedir /data/cruise2026

# New
oceanarray process dsG3_1_2026 \
    --raw-dir /data/cruise2026/raw \
    --proc-dir /data/cruise2026/proc

The YAML file stays where it was

The YAML was already on the processed side in the old layout: {basedir}/proc/{mooring}/{mooring}.mooring.yaml. The new layout keeps it in the same relative location: {proc_dir}/{mooring}/{mooring}.mooring.yaml.

No changes to the YAML file itself are needed for migration.

If your YAML contains a directory key pointing to a raw-file override path under the old {basedir}/raw/ tree, you may remove it — in the new layout the directory is determined automatically from {raw_dir}/{mooring}/{instrument}/. If you leave the directory key in place and it points to a valid path, it will still be used as an absolute-path override.

Step-by-step migration

The steps below assume your old layout was:

/data/cruise2026/raw/{instrument}/{mooring}/filename
/data/cruise2026/proc/{mooring}/{mooring}.mooring.yaml

and you want to migrate to:

/data/cruise2026/raw/{mooring}/{instrument}/filename
/data/cruise2026/proc/{mooring}/{mooring}.mooring.yaml    ← no change

Create the new mooring directory inside raw:

mkdir -p /data/cruise2026/raw/dsG3_1_2026

Move raw files for each instrument:

mkdir -p /data/cruise2026/raw/dsG3_1_2026/microcat
mv /data/cruise2026/raw/microcat/dsG3_1_2026/* \
   /data/cruise2026/raw/dsG3_1_2026/microcat/

mkdir -p /data/cruise2026/raw/dsG3_1_2026/aquadopp
mv /data/cruise2026/raw/aquadopp/dsG3_1_2026/* \
   /data/cruise2026/raw/dsG3_1_2026/aquadopp/

Repeat for each instrument type present on the mooring.

The YAML does not move — it stays in /data/cruise2026/proc/dsG3_1_2026/.

Update shell scripts to use --raw-dir and --proc-dir instead of --basedir:

# Replace
oceanarray run dsG3_1_2026 --basedir /data/cruise2026

# With
oceanarray run dsG3_1_2026 \
    --raw-dir /data/cruise2026/raw \
    --proc-dir /data/cruise2026/proc

`--basedir` has been removed

The --basedir flag no longer runs. Passing it prints a migration message naming the replacement and exits without processing, so existing scripts that use it must be updated to --raw-dir + --proc-dir and the raw data moved to the mooring-first layout (see the mapping above).

Verify after migration

After moving the files, confirm that the YAML is still valid and that stage 1 can read the raw files in their new location:

oceanarray validate \
    /data/cruise2026/proc/dsG3_1_2026/dsG3_1_2026.mooring.yaml

oceanarray process dsG3_1_2026 \
    --raw-dir /data/cruise2026/raw \
    --proc-dir /data/cruise2026/proc \
    --stage 1 --serial 26261 --force

If stage 1 completes without errors, the migration was successful. The output file is the same as before — the only change is where oceanarray looked for the input.

Migrating from the --basedir Layout