Matrix Axes and Empty Observations

MODEL "Matrix Axes and Empty Observations"
DESCRIPTION "Review a synthetic count matrix's axes and compare library-size normalization while preserving an empty observation."
VERSION "1.1.0"
TAGS "biology", "bioinformatics", "matrix", "normalization"

# Synthetic counts; observations are rows in the formula's representation.
input TargetTotal = 10000
  VALIDATE BETWEEN 1 AND 1000000 MESSAGE "Choose a target total from 1 to 1,000,000."

StoredRows = "%%MatrixMarket matrix coordinate integer general\n3 2 4\n1 1 8\n1 2 2\n2 1 4\n2 2 16\n"
Counts = BIO_PARSE_MATRIX_MARKET(StoredRows)
Normalized = BIO_OMICS_NORMALIZE(Counts, TargetTotal, FALSE)

# MAP transforms entries; BYROW supplies each complete observation row.
ObservationTable = {8, 2; 4, 16; 0, 0}
output RowTotals = BYROW(ObservationTable, (observation) => SUM(observation))
output DoubledEntries = MAP(ObservationTable, (count) => 2 * count)
output TableShapeGuide = "BYROW returns one total per observation: 10, 20, 0. MAP doubles individual entries and preserves the 3-by-2 shape; its argument is not an observation row."

# This companion input puts observations in file columns for axis review.
output MatrixToPaste = "%%MatrixMarket matrix coordinate integer general\n2 3 4\n1 1 8\n1 2 4\n2 1 2\n2 2 16\n"
output OriginalQc = BIO_OMICS_QC(Counts)
output NormalizedQc = BIO_OMICS_QC(Normalized)
output StudyQuestion = "Do the labels and empty observation survive transposition and normalization?"
output Workflow = "In Sequence, paste MatrixToPaste as Matrix Market. Choose observations in columns and raw counts. Add observation labels Cell A, Cell B, Empty and feature labels Gene A, Gene B, one per line. Preview: three observations, two features, totals 10, 20, 0. Import and normalize totals to 10,000 without log. The empty observation remains zero."
output Scenario = "Change TargetTotal to 100 in Inputs: formula QC totals become 100, 100, 0. Zero is rejected as a target. The workbench normalization action separately uses its displayed target 10,000. Save and reopen the study to preserve the edited formula input and imported artifacts."
output Assumptions = "Synthetic counts illustrate orientation and total scaling only. A zero-total observation is retained, not imputed or automatically excluded. Scaling does not correct batches, identify cell types, or establish suitability for a downstream statistical test."

Sequence_1!type = "sequence"
Sequence_1!config = <toml>
  version = 1
  kind = "sequence"
  title = "Review matrix axes and totals"
</toml>

END MODEL