Skip to content

Multi letter rows and cli errors - #8

Merged
mcnaughtonadm merged 5 commits into
mainfrom
multi-letter-rows-and-cli-errors
Oct 1, 2026
Merged

mcnaughtonadm merged 5 commits into
mainfrom
multi-letter-rows-and-cli-errors

Conversation

@mcnaughtonadm

Copy link
Copy Markdown
Contributor

Summary

Adds support for plates with more than 26 rows, and makes shuffle report
invalid input as a usage error rather than a traceback.

What changed

  • Multi-letter rows. Rows beyond Z now continue as AA, AB, ...,
    matching 1536-well plates (32 rows = A-Z, AA-AF). Two conversions,
    letters_to_row_index and row_index_to_letters, now own the row-label
    logic, replacing inline arithmetic at eight sites.
  • Correct labels past row Z. Tracing a 32-row plate previously emitted
    labels like [12; out-of-bounds errors reported a maximum well of ^. Both
    now name real wells.
  • ASCII-only row labels. str.isalpha() accepts any Unicode letter, and
    Unicode case-mapping folds some non-ASCII input onto A-Z, so i1 with a
    dotless i silently resolved to I1. Now rejected.
  • Clean input errors. Validation failures surface as click usage errors
    (exit 2) instead of tracebacks. This includes load_sample_ids, so a
    duplicated well in a sample file is reported rather than crashing the shell.
  • Canonical well keys. Both position maps are rewritten to one standard form
    before being compared or merged. Two spellings of one well no longer produce
    a false conflict, nor silently drop a sample.
  • .gitignore. Ignores scratch output from manual runs at the repo root.
    Patterns are root-anchored so tracked example_files/*.csv inputs stay
    visible.

Compatibility

shuffle output is byte-identical to main for 96- and 384-well plates, verified
by comparing output hashes across four seeded configurations (neighbor-aware,
simple, with and without controls). Trace CSV output is unchanged for any plate
with 26 or fewer rows. Both standard sizes are unaffected.

Testing

59 tests pass, up from 10. Adds tests/test_cli.py (9 tests), which the project
did not previously have: CLI behaviour was untested. 12 new tests in
tests/test_plate_generator.py. ruff, ruff format, mypy, prettier, and
the packaging smoke test all pass.

Rows are labelled A-Z and then continue into multiple letters, matching
1536-well plates where row 27 is AA. This required replacing the inline
chr(ord("A") + r) at eight sites with two bijective base-26 helpers,
letters_to_row_index and row_index_to_letters, which now own the
conversion. Plate output is unchanged for 96- and 384-well plates, which
never exceed 26 rows.

Rows past Z previously produced punctuation instead of letters, so trace
labelled a 32-row plate with wells like '[12', and out-of-bounds errors
named a maximum well of '^'. Both now report real wells. Shuffle output
was never affected, since it writes a plain grid of sample IDs.

Row labels are restricted to ASCII A-Z. str.isalpha() accepts any Unicode
letter, and Unicode case-mapping can turn non-ASCII input into a real row
label, so a sample file naming well 'i1' would place a sample at I1 with no
error raised.

shuffle now surfaces input-validation ValueErrors as click usage errors
instead of letting tracebacks escape. load_sample_ids is inside that block
too, so a duplicated well in a sample file is reported cleanly rather than
crashing the shell.
A well can be written several ways -- 1, A1, A01 and a1 all name the same
well -- and each spelling was kept as its own dictionary key. Two maps
therefore disagreed about which sample occupied a well depending only on
how it happened to be spelled:

- A sample file placing a control at "1" alongside --fixed-map A1:control-1
  was reported as a conflict, though both named the same well.
- Placing a different sample at "1" alongside --fixed-map A1:control-1
  raised nothing. Plate 1 got the control in A1 and the sample appeared on
  no plate at all, silently dropping it.

Both well maps are now rewritten to a canonical form via well_to_index once
the plate size is known, before the conflict check and the plate merge, and
two entries resolving to one well are rejected rather than overwriting each
other.

Case folding is limited to ASCII input, since Unicode upper() folds some
non-ASCII letters onto A-Z and would let such a well validate as a real one.

Output is unchanged for plates that do not use initial positions or a fixed
control map.
@mcnaughtonadm mcnaughtonadm self-assigned this Oct 1, 2026
@mcnaughtonadm mcnaughtonadm added the enhancement New feature or request label Oct 1, 2026
open() without an encoding argument uses the platform locale, so a UTF-8 file
read on Windows decoded as cp1252. Four tests that write a non-ASCII well into
a fixture failed there with UnicodeEncodeError while passing on Linux and macOS.

The same default applied to production code, where the failure is quieter: a
sample file written on one platform and read on another decoded to mojibake
rather than raising, silently corrupting sample IDs. All six open() calls in
cli.py and utilities.py now pass encoding="utf-8". numpy.savetxt is untouched,
since it already writes UTF-8 regardless of locale.

Console output is not covered by this change. click.echo of a non-ASCII sample
ID still depends on the console encoding, which on Windows means setting
PYTHONUTF8=1 or chcp 65001.
@mcnaughtonadm

Copy link
Copy Markdown
Contributor Author
  • Explicit UTF-8 file I/O. open() without encoding= uses the platform
    locale, so a UTF-8 file read on Windows decoded as cp1251 and silently mangled
    sample IDs. All six production calls now pass encoding="utf-8". Console output
    is unaffected by this and still depends on the console encoding.

@mcnaughtonadm
mcnaughtonadm merged commit df57a20 into main Oct 1, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant