Skip to content

sdrf: wire verbs

The facts on this page are the same facts mzLibRust and mzLibR publish, because all three render them from one spec per wire verb. The parameter, result, error and caveat tables are generated; edit the spec, not this page. How the reference facts are generated explains the mechanism. For the Python signatures and result classes, see the API reference. For which verb answers which question - and a worked example of each - see the SDRF guide.

validate, assess and samples take one path or many (--paths-stdin). Python spells the two forms as two functions, validate() and validate_many(), so the bulk-only options (threads, on_error) appear only on the _many form; the tables list the wire options for both. A unit of "—" means the value has none: a count of things, a flag or a name.

read

Read one SDRF-Proteomics file as its header and rows of raw cells, keeping repeated column names and ragged rows exactly as written.

Wire verb sdrf read · Python pymzlib.sdrf.read

Wraps

Parameters

Parameter Type Default Unit Range Meaning
path path required — — A .sdrf.tsv file.
offset int 0 rows >= 0 Skip this many data rows. The whole file is parsed on every call.
limit int absent rows >= 0 Return at most this many data rows. Absent means every row.

Returns

Top-level fields:

Field Type Unit Null? Meaning
path string — never The path as given.
column_names string[] — never The header, verbatim and in order. A LIST that may repeat names (comment[modification parameters] up to eight times) and may contain empty names; a name identifies a position, not a column.
row_count int rows never Data rows in the whole file, before the window.
returned_count int rows never Rows in rows.
offset int rows never The offset applied.
truncated bool — never True whenever rows were left out by offset or limit, including an offset past the end.
rows string[][] — never One list of raw cells per row, row-major. RAGGED: a row may be shorter than column_names; a missing position is absent, not empty.
caveats string[] — never Three static caveats, plus a count of short rows over the WHOLE document when any row is short.

Errors

Kind pyMzLib raises When
usage UsageError path missing or blank; offset or limit negative or not an integer
correctness BridgeError mzLib cannot read the file (MzLibException for an empty or missing file)
service_unavailable ServiceUnavailableError never raised by this verb

Caveats

  • readers read-records also opens .sdrf.tsv, but joins each row's cells with ';' into one string that cannot be split back, because the SDRF grammar is itself ';'-delimited. Use this verb for SDRF.
  • offset and limit window after a full parse.

Example

doc = pymzlib.sdrf.read('PXD000070.sdrf.tsv')

Recorded from the live bridge as sdrf_read_PXD000070.json. The doctests in the API reference replay these recordings in CI.

doc = pymzlib.sdrf.read('PXD059974.sdrf.tsv')

Recorded from the live bridge as sdrf_read_ragged.json. The doctests in the API reference replay these recordings in CI.

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.sdrf.read mzlib::sdrf::read_with with ReadOptions sdrf_read

References

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.1.0 0.1.0 0.1.0

pool

Merge several SDRF documents into one analysis table, stamping each row with the document it came from.

Wire verb sdrf pool · Python pymzlib.sdrf.pool

Wraps

Parameters

Parameter Type Default Unit Range Meaning
stdin string[] required — >= 1 line One document per line: path, optionally a TAB and a provenance label. Label every line or none; a partial set is a usage error. Blank lines are ignored.
out path absent — — Write the WHOLE merged document here as SDRF, whatever offset and limit are. The write is atomic since mzLib 1.0.592 (#1324): a temp file moved into place.
offset int 0 rows >= 0 Skip this many merged rows in the payload.
limit int absent rows >= 0 Return at most this many merged rows. Absent means every row.

Returns

Top-level fields:

Field Type Unit Null? Meaning
document_count int documents never Documents pooled.
paths string[] — never The paths, in stdin order.
labels string[] — never The label stamped for each document: the one supplied, or mzLib's containing-folder/file-stem default.
column_names string[] — never The union header in SDRF block order; a repeated name at the highest multiplicity any one document used; comment[source document] added.
row_count int rows never Merged rows before the window.
returned_count int rows never Rows in rows.
offset int rows never The offset applied.
truncated bool — never True whenever rows were left out.
rows string[][] — never Row-major raw cells, as for sdrf read.
written object — yes: out was not given {path, row_count}; row_count is the whole merged document.
caveats string[] — never Four static caveats, plus a fifth when no labels were supplied.

Errors

Kind pyMzLib raises When
usage UsageError stdin empty; a blank path; a file not found; some lines labelled and some not
usage UsageError offset or limit negative or not an integer
correctness BridgeError mzLib cannot read one of the documents
service_unavailable ServiceUnavailableError never raised by this verb

Caveats

  • An ANALYSIS table, not a deposit: source name + assay name + comment[label] is unique per document, not across documents. Key on comment[source document] too.
  • Without labels, provenance depends on where the files sit, so the table is not reproducible on another machine.

Example

pooled = pymzlib.sdrf.pool({'PXD000070.sdrf.tsv': 'malaria', 'PXD026824.sdrf.tsv': 'colon'}, limit=4)

Recorded from the live bridge as sdrf_pool_two.json. The doctests in the API reference replay these recordings in CI.

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.sdrf.pool mzlib::sdrf::pool_with with PoolOptions sdrf_pool

References

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.1.0 0.1.0 0.1.0

Not yet verified

  • out has no extension check, unlike the reader verbs, sdrf design and proteins annotate-go (PYB-1). It writes an SDRF, conventionally .sdrf.tsv; should it share their .tsv-only rule? Behaviour unchanged until decided (noted on pyMzLib #76).

validate and validate_many

Check SDRF-Proteomics files against the specification's structural rules, one row per finding.

Wire verb sdrf validate · Python pymzlib.sdrf.validate

Wraps

Parameters

Parameter Type Default Unit Range Meaning
path path absent — — One .sdrf.tsv file. Exactly one of path and paths-stdin is required.
paths_stdin (wire --paths-stdin) flag absent — — Read many paths from stdin, one per line (BULK.md section 1). Blank lines are ignored; a repeated path is a usage error. Switches the result to the bulk shape below.
threads int 1 documents >= 1, or -1 Documents validated at once; -1 is every core. The output is byte-identical at any value (tested at 1, 4 and -1).
on_error (wire --on-error) string fail — fail \| skip fail: the first failure IN INPUT ORDER aborts the call. skip: recorded in files[i].error and the batch carries on. skip with path is a usage error.

Returns

Top-level fields:

Field Type Unit Null? Meaning
path string — never The absolute path validated.
is_valid bool — never No Error findings. Warnings never make a document invalid.
error_count int findings never Findings of severity Error.
warning_count int findings never Findings of severity Warning.
message_count int findings never All findings; the length of every column.
row_count int rows never Data rows in the document.
column_names string[] — never The table's columns in order.
columns table — never Column name to one value per finding, in mzLib's order.
caveats string[] — never Four static caveats.

Per-row fields (one value per record, in columns or each list entry):

Field Type Unit Null? Meaning
source_index int — never 0-based position of the document in the stdin list. Present only with --paths-stdin.
source_path string — never Absolute path of the document. Present only with --paths-stdin.
severity string — never Error (cannot be reliably consumed) or Warning (deviates, still joinable). mzLib's SdrfValidationSeverity member name.
rule string — never Stable rule id: EmptyHeader, RequiredColumn, RecommendedColumn, EmptyColumnName, ColumnNameCase, MalformedColumnName, ColumnOrdering, NoRows, RowWidth, EmptyCell, ReservedWordCase, NonIntegerValue, RowKeyUniqueness (at 23c2490e).
message string — never Human-readable, including the offending value.
row_index int — yes: the finding is about the whole document (a missing column, an empty header, no rows), not one row 0-based index into the data rows.
line_number int — yes: same as row_index: a document-level finding 1-based line in the file: row_index + 2, because the header is line 1.
column_name string — yes: the finding is not about one column (RowWidth, RowKeyUniqueness, NoRows, EmptyHeader) The column involved; for a ragged row's extra cells, "(column N)".

Errors

Kind pyMzLib raises When
usage UsageError neither or both of path and paths-stdin; stdin empty under paths-stdin; a repeated path
usage UsageError a file not found (under fail, checked before any document is read)
usage UsageError threads 0 or below -1 or not an integer; on-error not fail or skip, or given without a value; on-error skip with path
correctness BridgeError mzLib cannot read a document (MzLibException for an empty file); under fail, the lowest input position's failure is raised
service_unavailable ServiceUnavailableError never raised by this verb

Caveats

  • STRUCTURE ONLY: column presence, order, casing, cell shape and row-key uniqueness against v1.1.0. Controlled-vocabulary accessions are not resolved.
  • Severities were calibrated by mzLib against the 1,236-file bigbio curated corpus; a rule that fired on most curated files was demoted, not the files condemned.
  • A document of reserved words validates cleanly. Use sdrf assess for whether it says anything, sdrf lint for whether several agree.

Example

result = pymzlib.sdrf.validate('sdrf_cohort.sdrf.tsv')

Recorded from the live bridge as sdrf_validate_cohort.json. The doctests in the API reference replay these recordings in CI.

result = pymzlib.sdrf.validate('sdrf_skeleton.sdrf.tsv')

Recorded from the live bridge as sdrf_validate_skeleton.json. The doctests in the API reference replay these recordings in CI.

batch = pymzlib.sdrf.validate_many(['sdrf_skeleton.sdrf.tsv', 'sdrf_cohort.sdrf.tsv', 'missing.sdrf.tsv'], on_error='skip')

Recorded from the live bridge as sdrf_validate_bulk.json. The doctests in the API reference replay these recordings in CI.

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.sdrf.validate mzlib::sdrf::validate with BulkOptions sdrf_validate

References

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.2.0 0.1.0 0.1.0

lint

Find the concepts a set of SDRF documents wrote inconsistently, one row per finding and spelling.

Wire verb sdrf lint · Python pymzlib.sdrf.lint

Wraps

Parameters

Parameter Type Default Unit Range Meaning
stdin string[] required — >= 1 line Exactly as sdrf pool: one document per line, path then optionally a TAB and a label; label all or none. Labels are how the documents column names each file.

Returns

Top-level fields:

Field Type Unit Null? Meaning
document_count int documents never Documents linted.
paths string[] — never The paths in stdin order.
labels string[] — never Each document's label: supplied, or mzLib's containing-folder/file-stem default.
finding_count int findings never Distinct findings (not rows).
column_names string[] — never The table's columns.
columns table — never One row per finding x variant, findings in mzLib's impact order, variants majority first.
caveats string[] — never Five static caveats, plus one when no labels were supplied.

Per-row fields (one value per record, in columns or each list entry):

Field Type Unit Null? Meaning
finding_index int — never 0-based finding; rows of one finding share it.
kind string — never AccessionNameConflict | NameAccessionConflict | MixedTermAndFreeText | ColumnNameVariant | ValueCaseVariant (SdrfDriftKind member names).
concept string — never What was written inconsistently: an accession, a term name, a normalised free-text value, or a normalised column name (lower-cased, whitespace runs collapsed), by kind.
column_name string — yes: a ColumnNameVariant finding, which is about a column's NAME rather than its values The column whose values drift.
variant_rank int — never 0 = the majority spelling, then by frequency. Descriptive, not advice.
value string — never This spelling as written; for MixedTermAndFreeText, "controlled vocabulary term" or "free text".
occurrences int documents never How widely this spelling was used. At 23c2490e every kind counts documents.
documents string[] — never Labels of the documents that used this spelling, a list cell (labels are caller text, so no delimiter could be undone).

Errors

Kind pyMzLib raises When
usage UsageError stdin empty; a blank path; a file not found; some lines labelled and some not
correctness BridgeError mzLib cannot read one of the documents
service_unavailable ServiceUnavailableError never raised by this verb

Caveats

  • The majority spelling describes what the documents do; it is not advice (organism is free text in 963 curated documents and a CV term in 275).
  • Never compared, being unique per row by construction: source name, assay name, comment[data file], comment[searched data file] (mzLib 1.0.592, #1335), comment[file uri], comment[source document].
  • Reserved words and empty cells are skipped, so documents that say nothing lint clean; see sdrf assess.
  • No --threads: SdrfDriftLint.Analyze is one call over the whole collection and does not parallelise.

Example

drift = pymzlib.sdrf.lint({'sdrf_cohort.sdrf.tsv': 'cohort', 'sdrf_cohort_partner.sdrf.tsv': 'partner'})

Recorded from the live bridge as sdrf_lint_cohort.json. The doctests in the API reference replay these recordings in CI.

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.sdrf.lint mzlib::sdrf::lint_labelled sdrf_lint

References

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.2.0 0.1.0 0.1.0

assess and assess_many

Decide whether each SDRF file's sample half describes an experimental design - Informative, Partial or Skeleton - with the per-column counts behind the verdict.

Wire verb sdrf assess · Python pymzlib.sdrf.assess

Wraps

Parameters

Parameter Type Default Unit Range Meaning
path path absent — — One .sdrf.tsv file. Exactly one of path and paths-stdin.
paths_stdin (wire --paths-stdin) flag absent — — Many paths on stdin, as for sdrf validate.
threads int 1 documents >= 1, or -1 Documents assessed at once; output identical at any value.
on_error (wire --on-error) string fail — fail \| skip As for sdrf validate.

Returns

Top-level fields:

Field Type Unit Null? Meaning
path string — never The absolute path assessed.
verdict string — never Informative (all three checks pass), Skeleton (none), Partial (between). mzLib's SdrfSampleVerdict member name.
factor_value_varies bool — never Some factor value[...] column holds >= 2 distinct real answers.
sample_is_described bool — never Some characteristics[...] column other than organism and biological replicate holds a real answer.
biological_replicate_varies bool — never characteristics[biological replicate] holds >= 2 distinct real answers; false when the column is missing.
row_count int rows never Data rows in the document.
column_names string[] — never The evidence table's columns.
columns table — never One row per column a check read: factor values, then sample characteristics, then biological replicate, each in mzLib's (ordinal) order.
caveats string[] — never Four static caveats.

Per-row fields (one value per record, in columns or each list entry):

Field Type Unit Null? Meaning
source_index int — never 0-based input position. Present only with --paths-stdin.
source_path string — never Absolute path. Present only with --paths-stdin.
role string — never factor_value | sample_characteristic | biological_replicate: which check read this column.
column_name string — never The column as the header spells it.
rows int rows never Rows, counted once per row per column NAME (a repeated column does not inflate it).
filled int rows never Rows with a real answer in at least one of the column's cells.
absent int rows never Rows that are empty or a reserved word (any case): rows - filled.
distinct_values int values never Different real answers, compared case-insensitively after trimming.
fill_rate float fraction (0-1) never filled / rows; 0 when rows is 0. May cross as an integer 0 or 1.

Errors

Kind pyMzLib raises When
usage UsageError as for sdrf validate (path / paths-stdin / threads / on-error rules, missing or repeated files)
correctness BridgeError mzLib cannot read a document
service_unavailable ServiceUnavailableError never raised by this verb

Caveats

  • Partial is often legitimate (a single-condition study has nothing to vary); the booleans say which check failed and the caller decides.
  • On the 1,236-file bigbio curated corpus at 4f823dcd mzLib measured 300 Informative, 742 Partial, 194 Skeleton.
  • Organism is excluded from sample_is_described because a search can fill it without a human describing the samples.
  • Looks only at the sample half; says nothing about structure (sdrf validate) or cross-file agreement (sdrf lint).

Example

result = pymzlib.sdrf.assess('sdrf_cohort.sdrf.tsv')

Recorded from the live bridge as sdrf_assess_cohort.json. The doctests in the API reference replay these recordings in CI.

batch = pymzlib.sdrf.assess_many(['sdrf_cohort.sdrf.tsv', 'sdrf_skeleton.sdrf.tsv', 'PXD000070.sdrf.tsv'])

Recorded from the live bridge as sdrf_assess_bulk.json. The doctests in the API reference replay these recordings in CI.

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.sdrf.assess mzlib::sdrf::assess with BulkOptions sdrf_assess

References

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.2.0 0.1.0 0.1.0

Not yet verified

  • fill_rate is a C# double that serialises 1.0 as 1; bindings must read it as a float.

samples and samples_many

One row per sample, column and position: what each source name's rows agree on, the columns they disagree about named and withheld, and characteristics[age] read into years.

Wire verb sdrf samples · Python pymzlib.sdrf.samples

Wraps

Parameters

Parameter Type Default Unit Range Meaning
path path absent — — One .sdrf.tsv file. Exactly one of path and paths-stdin.
paths_stdin (wire --paths-stdin) flag absent — — Many paths on stdin, as for sdrf validate.
threads int 1 documents >= 1, or -1 Documents read at once; output identical at any value.
on_error (wire --on-error) string fail — fail \| skip As for sdrf validate.

Returns

Top-level fields:

Field Type Unit Null? Meaning
path string — never The absolute path read.
sample_count int samples never Distinct source names.
row_count int rows never Data rows in the document.
conflict_count int — never Sample x column pairs withheld as conflicting.
problems string[] — never mzLib's BySourceName problems: no source name column, or a row with a blank source name. Empty for a well-formed document.
column_names string[] — never The table's columns.
columns table — never Samples in order of first appearance in the document; within a sample: source name, characteristics, factor values (header order), then conflicting columns.
caveats string[] — never Four static caveats.

Per-row fields (one value per record, in columns or each list entry):

Field Type Unit Null? Meaning
source_index int — never 0-based input position. Present only with --paths-stdin.
source_path string — never Absolute path. Present only with --paths-stdin.
source_name string — never The sample as its first row spelled it, trimmed. Matched case-insensitively (mzLib's key).
sample_row_count int rows never Rows carrying this sample.
column_name string — never The header's own spelling; characteristics[age] and characteristics[Age] are two columns.
column_kind string — never source_name | characteristic | factor_value.
position int — yes: status is conflicting: the column was withheld, so it has no positions 0-based occurrence of a repeated column.
status string — never agreed | conflicting (the sample's rows disagree; mzLib withheld the column).
value string — yes: status is conflicting (withheld, not absent) The cell verbatim, reserved words included.
age_years float years yes: not a characteristics[age] row, or the cell was refused (age_refusal says why) The age, a range's midpoint, or a bound.
age_min_years float years yes: as age_years Youngest the cell allows; 0 for UpperBound.
age_max_years float years yes: not an age row; refused; OR precision is LowerBound, meaning UNBOUNDED (mzLib's +infinity, which JSON cannot carry) Oldest the cell allows.
age_precision string — yes: not an age row, or refused Exact | Range | LowerBound | UpperBound (SdrfAgePrecision).
age_follows_specification bool — yes: not an age row, or refused true for nYnMnD / nW grammar, false for unambiguous words.
age_refusal string — yes: not an age row, or the cell was read empty | reserved_word | no_unit | unreadable. Classified by the bridge; mzLib's TryParse answers only true/false.

Errors

Kind pyMzLib raises When
usage UsageError as for sdrf validate
correctness BridgeError mzLib cannot read a document
service_unavailable ServiceUnavailableError never raised by this verb

Caveats

  • A source name is unique only within a document; across a bulk result key on (source_index, source_name).
  • Age units: a month is 1/12 year, a week 7/365.25, a day 1/365.25, an hour 1/(365.25 x 24).
  • The age column is matched ignoring case, so characteristics[Age] is still read; sdrf validate reports the casing.
  • A conflicting characteristics[age] has no parsed age: the column is withheld.

Example

result = pymzlib.sdrf.samples('sdrf_cohort.sdrf.tsv')

Recorded from the live bridge as sdrf_samples_cohort.json. The doctests in the API reference replay these recordings in CI.

batch = pymzlib.sdrf.samples_many(['sdrf_cohort.sdrf.tsv', 'sdrf_cohort_partner.sdrf.tsv'])

Recorded from the live bridge as sdrf_samples_bulk.json. The doctests in the API reference replay these recordings in CI.

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.sdrf.samples mzlib::sdrf::samples with BulkOptions sdrf_samples

References

  • doi:10.1038/s41467-021-26111-3: SDRF-Proteomics source name, characteristics and factor value columns, and the age grammar (Dai et al., Nat Commun 12, 5854, 2021)

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.2.0 0.1.0 0.1.0

Not yet verified

  • The refusal classification (empty, reserved_word, no_unit, unreadable) is bridge-side. It uses mzLib's own SdrfValidator.ReservedWords, but a TryParse overload returning the reason would move it upstream where it belongs; propose to mzLib.
  • Sample order is first appearance in the document, recovered through BySourceName's own dictionary comparer because the dictionary's enumeration order is not contractual; an ordered return from mzLib would remove that step.

parse_ages

Read characteristics[age] cells into years with an honest precision, refusing any cell that would need a guess.

Wire verb sdrf parse-age · Python pymzlib.sdrf.parse_ages

Wraps

Parameters

Parameter Type Default Unit Range Meaning
stdin string[] required — >= 1 line One cell per line. BLANK LINES ARE KEPT (unlike every other stdin verb) so output row i is line i; one trailing newline does not add a cell. A UTF-8 BOM is dropped.

Returns

Top-level fields:

Field Type Unit Null? Meaning
cell_count int cells never Cells read from stdin; the length of every column.
parsed_count int cells never Cells read as an age.
column_names string[] — never The table's columns.
columns table — never One row per input line, in order.
caveats string[] — never Four static caveats.

Per-row fields (one value per record, in columns or each list entry):

Field Type Unit Null? Meaning
cell string — never The line exactly as given (mzLib's SdrfAge.Cell is the trimmed form).
years float years yes: the cell was refused; refusal says why The age, a range's MIDPOINT, or a bound.
min_years float years yes: refused Youngest the cell allows; 0 for UpperBound.
max_years float years yes: refused, OR precision is LowerBound: UNBOUNDED (mzLib's +infinity, which JSON cannot carry) Oldest the cell allows.
precision string — yes: refused Exact (incl. degenerate 40Y-40Y since #1333) | Range | LowerBound | UpperBound.
follows_specification bool — yes: refused true for the spec grammar, false for unambiguous words ("3 year", "6-8 weeks", "4 hour").
refusal string — yes: the cell was read empty | reserved_word (any case) | no_unit (a bare number) | unreadable.

Errors

Kind pyMzLib raises When
usage UsageError stdin empty
correctness BridgeError never expected: TryParse does not throw
service_unavailable ServiceUnavailableError never raised by this verb

Caveats

  • Units are years: month 1/12, week 7/365.25, day 1/365.25, hour 1/(365.25 x 24).
  • A bare number (63, 11% of real corpus age cells) is refused, never assumed to be years.
  • years for a wide Range is a poor stand-in for any one sample; filter on precision.
  • Every cell costs one line, not one process: send all cells in one call.

Example

ages = pymzlib.sdrf.parse_ages(['58Y', '30Y6M', '40Y-85Y', '40Y-40Y', '>=90Y', '<1Y', '6-8 weeks', '63', 'not available', '', 'about forty'])

Recorded from the live bridge as sdrf_parse_age.json. The doctests in the API reference replay these recordings in CI.

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.sdrf.parse_ages mzlib::sdrf::parse_ages sdrf_parse_ages

References

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.2.0 0.1.0 0.1.0

Not yet verified

  • The refusal reason is a bridge-side classification of TryParse's false; see sdrf.samples.yaml. An upstream TryParse(cell, out age, out reason) would retire it.
  • Binding name is parse_ages (plural) for the verb parse-age (one cell per line). Kept because the function takes a list; revisit if a binding wants the wire name.

design

Python spells two options differently from the wire. condition_columns= is a list; pyMzLib joins it with tabs for condition-columns, because a tab is the one character an SDRF column name cannot contain. searched_files= is a list; pyMzLib sends it on stdin and sets searched-files-stdin. The result's design coordinates are 0-based on the wire and in Python; ExperimentalDesign.tsv, which out= writes, is 1-based.

Read a label-free experimental design out of an SDRF, in MetaMorpheus's terms, or every reason it was refused.

Wire verb sdrf design · Python pymzlib.sdrf.design

Wraps

Parameters

Parameter Type Default Unit Range Meaning
path path required — — One .sdrf.tsv file. A file that does not exist is a usage error.
condition_columns (wire --condition-columns) string absent — — The factor value[...] columns the condition is built from, by exact (case-sensitive) name, separated by TAB characters, in join order; the condition is their values joined with "_". Absent: mzLib uses the document's only factor column, and refuses a document with several. Given but blank, or with a blank name, is a usage error.
searched_files_stdin (wire --searched-files-stdin) flag absent — — stdin holds the files the search will read, one per line, as paths or bare names. Each must be named EXACTLY (case and extension) by one row; rows for other files are dropped and reported in notes; the searched paths replace the SDRF's names in full_path. An empty list is mzLib's refusal, not a usage error.
out path absent — .tsv only, any case (PYB-1) Also write MetaMorpheus's ExperimentalDesign.tsv (1-based) here, through mzLib's writer. Must end in .tsv, case-insensitive (PYB-1), checked before the SDRF is read. Written only when is_valid; a refused design writes nothing and written is null.

Returns

Top-level fields:

Field Type Unit Null? Meaning
path string — never The SDRF path as given.
is_valid bool — never No refusals. False is an answer, not an error: the table is then empty.
file_key_column string — yes: the SDRF has neither comment[searched data file] nor comment[data file], so no row names a file (also a refusal) The column files were keyed on: comment[searched data file] when present, else comment[data file] (mapping row MAP-12).
condition_columns string[] — never The factor columns the condition was built from, in join order; empty when none could be chosen.
condition_columns_declared bool — never Whether --condition-columns was given.
searched_files_given bool — never Whether --searched-files-stdin was given.
file_count int files never Rows in the table; 0 when refused.
refusals string[] — never Every reason the design was refused, all at once, in mzLib's words. Empty when valid.
notes string[] — never Every relabelling on the way to a valid design: biological replicates ranked within a condition, with the old -> new mapping (MAP-33), and rows dropped because the search does not read their file.
report string — never mzLib's human-readable account (SdrfLabelFreeDesign.Report): counts, key column, condition columns, notes, refusals.
column_names string[] — never The table's columns in order.
columns table — never Column name to one value per file, in SDRF row order.
written object — yes: --out was not given, or the design was refused and nothing was written {path, file_count} of the ExperimentalDesign.tsv written.
caveats string[] — never Six static caveats.

Per-row fields (one value per record, in columns or each list entry):

Field Type Unit Null? Meaning
full_path string — never The file as the SDRF's key column names it, or the matching searched path when --searched-files-stdin was given.
file_name string — never full_path's file name without its extension (SpectraFileInfo.FilenameWithoutExtension): the run key the quant verbs use.
condition string — never The condition columns' values joined with _.
biological_replicate int — never 0-based, ranked within the condition (ExperimentalDesign.tsv's Biorep minus 1).
technical_replicate int — never 0-based (Techrep minus 1).
fraction int — never 0-based (Fraction minus 1).

Errors

Kind pyMzLib raises When
usage UsageError path missing or the file does not exist
usage UsageError --out without a value, or not ending in .tsv (checked before the SDRF is read)
usage UsageError --condition-columns without a value, or with a blank name
correctness BridgeError mzLib cannot parse the SDRF at all, or the --out directory cannot be written
service_unavailable ServiceUnavailableError never raised by this verb

Caveats

  • Label-free only. An isobaric (TMT, iTRAQ) SDRF needs a channel design this verb does not produce.
  • is_valid = false is an answer: refusals lists every reason at once and the table is empty. mzLib refuses rather than repairs because MetaMorpheus skips quantification with only a warning when its design file is invalid.
  • The table is 0-based, as SpectraFileInfo and the quant verbs take it. ExperimentalDesign.tsv is 1-based; mzLib converts when it writes.
  • notes is the only record of a renumbering; read it.
  • A factor holding not available or not applicable is refused: it would pair samples nobody said were alike.
  • MetaMorpheus finds the design only as a file named ExperimentalDesign.tsv beside the spectra; --out writes any .tsv path.

Example

design = pymzlib.sdrf.design('PXD067622.sdrf.tsv', condition_columns=['factor value[genotype]', 'factor value[treatment]'])

Recorded from the live bridge as sdrf_design_PXD067622.json. The doctests in the API reference replay these recordings in CI.

design = pymzlib.sdrf.design('PXD049018.sdrf.tsv', condition_columns=['factor value[genotype]', 'factor value[treatment]'])

Recorded from the live bridge as sdrf_design_PXD049018.json. The doctests in the API reference replay these recordings in CI.

design = pymzlib.sdrf.design('PXD067622_studywide.sdrf.tsv', condition_columns=['factor value[genotype]', 'factor value[treatment]'])

Recorded from the live bridge as sdrf_design_studywide.json. The doctests in the API reference replay these recordings in CI.

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.sdrf.design mzlib::sdrf::design_with with DesignOptions sdrf_design

References

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.3.0 not yet shipped not yet shipped

Not yet verified

  • No --paths-stdin form. The condition columns and searched files are per-deposit facts; a batch would need either one shared declaration (only sensible with none, i.e. each document's only factor column) or a per-document list. Decide before adding sdrf design_many.
  • Not yet ported: mzLibRust and mzLibR names above are proposals until their ports land (parity order).