Skip to content

readers: 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 choosing between the readers, see the Readers guide.

Parameters are listed under their Python keyword. Where it differs from the wire option, the wire spelling is given too. A unit of "—" means the value has none: a count of things, a flag or a name.

Performance, for every verb here: each call starts one bridge process, about 120 ms before mzLib does any work, and mzLib parses the whole file on every call whatever limit and offset say. For a large file, make one call with out instead of paging.

Many files at once, for every verb here but formats: the wire verb also takes --paths-stdin, and pyMzLib spells that form <function>_many - read_spectra_many, read_records_many, identify_many and so on. One process reads the whole list, threads files at a time, into one long table whose first columns are source_index and source_path, with one files[] entry per input. The output is byte-identical at any thread count. Each verb's parameters and fields for that form are in its spec's bulk section, and the readers guide walks through it.

formats

List every file type mzLib recognises, with the extension it dispatches on, the reader class that parses it, and the cross-format views it offers.

Wire verb readers formats · Python pymzlib.readers.formats

Wraps

Parameters

This verb takes no parameters.

Returns

Top-level fields:

Field Type Unit Null? Meaning
format_count int formats never Number of entries in formats; equal to the number of SupportedFileType members. 38 at mzLib 1.0.593 (36 at 1.0.592, 32 at 1.0.591).
formats table — never One entry per SupportedFileType, in enum declaration order. Enumerated from mzLib, not transcribed, so it cannot drift from what mzLib dispatches.

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

Field Type Unit Null? Meaning
file_type string — never mzLib's SupportedFileType member name, e.g. "MsFraggerPsm", "psmtsv", "MzIdentMLGz".
extension string — yes: mzLib has no extension mapping for this member (a broken mzLib build); the listing reports it rather than failing The suffix mzLib dispatches on, e.g. ".mzid.gz" or "QuantifiedProteinGroups.tsv". NOT unique: both Bruker types are ".d" and several share ".tsv"; DiaNnReport and PytheasResult dispatch on content, not on this value.
reader string — yes: mzLib has no reader mapping for this member (a broken mzLib build) The mzLib reader class name, e.g. "MzIdentMLResultFile".
views string[] — never Cross-format views this type offers, from quantifiable, ms1_features, spectra, spectral_match. Empty is a real answer: 19 of 38 types offer none and are readable only through read-records.

Errors

Kind pyMzLib raises When
usage UsageError never raised by this verb
correctness BridgeError never raised by this verb
service_unavailable ServiceUnavailableError never raised by this verb

Caveats

  • Extensions are not unique and not always how dispatch works: identify a real path rather than matching on extension.
  • An empty views list means mzLib parses the format into its own record type with no cross-format interface; read-records still reads it.
  • At mzLib 1.0.593 the view families are: quantifiable 4, ms1_features 2, spectral_match 6, spectra 7, none 19. These counts are the pin's, not the contract's: bindings should call formats rather than repeat them in prose.

Example

formats = pymzlib.readers.formats()

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

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.readers.formats mzlib::readers::formats readers_formats

References

None: no publication is attached to this verb.

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.1.0 0.1.0 0.1.0

read_records

Read any file mzLib recognises into a table of that format's own record fields, naming every field that could not become a column.

Wire verb readers read-records · Python pymzlib.readers.read_records

Wraps

Parameters

Parameter Type Default Unit Range Meaning
path path required — — Any of the file types readers formats lists (38 at mzLib 1.0.593), including spectra files and the Bruker .d directories.
offset int 0 records >= 0 Skip this many records. A window, not a cursor: mzLib parses the whole file on every call, so paging re-reads it. For a large file use out in one call.
limit int absent records >= 0 Return at most this many records. Absent means no limit; there is deliberately no default cap.
out path absent — .tsv only, any case (PYB-1) Write the selected window as a tab-separated table here instead of returning columns (header = column_names). Must differ from path. Parent directories are created. Must end in .tsv, any case (PYB-1); any other extension, or none, is a usage error before any input is read, and no extension is appended.

Returns

Top-level fields:

Field Type Unit Null? Meaning
path string — never Absolute path of the input.
file_type string — never The SupportedFileType mzLib dispatched, not a guess from the extension.
reader string — never The mzLib reader class that parsed it.
record_type string — never The mzLib record class the columns are properties of (e.g. ToppicPrsm, MzIdentMLRecord, ProteinGroupFromTsv), so a column is cross-referenceable against the mzLib source.
views string[] — never The cross-format views this file also offers; same values as readers formats.
record_count int records never Records mzLib parsed from the whole file, before the window. Records, not lines: see caveats.
returned_count int records never Records in columns; 0 when written to out.
offset int records never The offset applied.
truncated bool — never True whenever records were left out by offset or limit.
excluded_fields table — never Every property of record_type that could not become a column, as {field, type, reason, verb}: nested objects, lists of composites, and dictionaries (reason starts "a dictionary"), and an SDRF row's header and cells (reason "use sdrf read", verb "sdrf read"; PYB-2). verb names the command that carries the field (sample_groups: readers read-protein-groups; samples: readers read-quantified-peptides; mzIdentML scores: readers read-matches) or is null. Empty when every property projects.
rows_not_read int rows yes: the count is not meaningful for this format (only the psmtsv family and MSFragger are one line per record) Data rows that did not become records; mzLib drops a malformed psmtsv line silently.
retention_time_unit string — yes: always: the columns are the format's own, and several formats carry more than one time column Always null for this verb; use a typed view when units matter.
caveats string[] — never Always empty for this verb; the static caveats below apply.
absent_fields string[] — never Columns this file's header has no column for: the record type reads them from an [Optional] CsvHelper column the file lacks, so every value is mzLib's default and crosses null (e.g. mbr_score on a current FlashLFQ peaks table, #1345; q_value and pep_q_value on an MsPathFinderT targets file). Judged from mzLib's own [Name]/[Optional] attributes against the file's header; empty means none found or no basis to judge.
error object — yes: always, for a single path: a file that cannot be read fails the call instead {kind, type, message}; non-null only in a files[] entry under on-error skip.
skipped_count int items yes: the format keeps no skip list (every format but mzIdentML) mzIdentML items mzLib did not represent as records (crosslinks, unresolvable modifications, substitutions; #1313).
skipped object[] — yes: as skipped_count {spectrum_identification_item_id, spectrum_id, reason} per skipped item.
failed_fields string[] — never "field: ExceptionType" for every property that threw while being read on a returned record; those cells are null.
column_names string[] — never The record type's projectable public properties in snake_case, base class first, in declaration order.
columns table — yes: the table was written to out instead Column name to per-record values, in column_names order.
output object — yes: out was not given {path, format: "tsv", row_count} when out was given; row_count is the window written, not the whole file.

The columns are per-format: they are the file's own record fields, listed in column_names on every result. Every cell follows these rules:

  • A cell is null when mzLib's value is null, when a double is NaN or infinite (JSON cannot carry it), or when the property threw (then named in failed_fields).
  • -1 crosses unchanged: in a format's own columns it is often a real measurement. The one exception is retention_time and monoisotopic_mass on IQuantifiableRecord types (psmtsv, osmtsv, MsFraggerPsm, DiaNnReport), where mzLib documents -1 as absent; those are null, matching read-results.
  • Units are the writing tool's and are not normalised: retention time is minutes for psmtsv/osmtsv/MsFraggerPsm/DiaNnReport and undeclared for the rest. read-records carries no retention_time_unit; use a typed view when units matter.
  • Enums cross as their member names, dates as ISO 8601 strings, and a list of scalars as ONE ';'-joined string, on the wire and in out alike; split it yourself. The one exception is an SDRF row, whose header and cells lists are excluded rather than joined (PYB-2): SDRF cells contain ';' themselves.
  • A column named in absent_fields is null in every row, whatever default mzLib filled in.

Errors

Kind pyMzLib raises When
usage UsageError path missing or blank; file or directory not found
usage UsageError mzLib does not recognise the file type (the message points at readers formats)
usage UsageError offset, limit or out given with no value; offset or limit < 0; non-integer value; out resolves to the same file as path
correctness BridgeError the file is recognised but mzLib fails to parse it; the error type is mzLib's own (e.g. HeaderValidationException, MzLibException)
correctness BridgeError a vendor format that cannot load on this platform surfaces as its real failure (Bruker/timsTOF native DLLs are Windows x64 only)
usage UsageError paths-stdin with path, offset or limit; paths-stdin with a value; no paths on stdin; a repeated path; threads 0 or below -1; on-error not fail or skip; on-error skip with a single path; out naming an input
usage UsageError with on-error fail, an input that is missing or not this view: the usage error of that input, prefixed 'Input ()'
correctness BridgeError with on-error fail, mzLib failing to parse an input: that input's own error type, message prefixed 'Input ()'
usage UsageError with paths-stdin, inputs of more than one record type: refused before any file is parsed, naming the groups, whatever on-error says
usage UsageError out (with path or paths-stdin) whose extension is not .tsv, any case, including none (PYB-1); checked before any input is opened
usage UsageError the answer is too large to return as one JSON document (PYB-3 part 1; measured: past the ~1.07 G-character .NET string ceiling, not RAM). Message: 'this read (N records) is too large to return as one document; use --limit/--offset or --out', N the parsed record_count
service_unavailable ServiceUnavailableError never raised by this verb

Caveats

  • Columns are this format's own fields under mzLib's names. Two formats do not share columns, and a same-named column need not mean the same thing; use a typed view (read-results, read-features, read-matches, read-spectra) for comparable columns.
  • No field is silently dropped: anything that cannot be a column is in excluded_fields, whose verb names where it IS carried. At mzLib 1.0.592 that includes the most important values of three new readers, which are dictionaries: MetaMorpheusQuantifiedProteinGroups.sample_groups (read-protein-groups, and read-occupancy for the occupancy cells), FlashLFQQuantifiedPeptide.samples (read-quantified-peptides) and MzIdentML/MzIdentMLGz.scores (read-matches --scores).
  • An SDRF reads with ZERO columns and a real record_count: SdrfRow's only fields, header and cells, are lists of strings, and a ';'-join could not be split back because SDRF cells contain ';' (NT=Oxidation;AC=UNIMOD:35). Both are in excluded_fields with reason "use sdrf read" (PYB-2, pyMzLib #76); read the document with sdrf read. With out, the file is an empty header line and one empty line per record.
  • record_count counts what mzLib parsed, not lines. What mzLib drops is reported beside it: rows_not_read counts malformed psmtsv/MSFragger lines, and skipped_count/skipped list the mzIdentML items it could not represent.
  • Since mzLib 1.0.592 (#1346), pro_forma on psmtsv/osmtsv from MetaMorpheus 1.1.11 or earlier is computed from full_sequence instead of null; ambiguous or unconvertible rows stay null. Measured cost: 12.9 s -> 15.6 s on a 271,551-row psmtsv.
  • Since mzLib 1.0.592 (#1345), mbr_score on FlashLFQQuantifiedPeak is null, not 0, when a peak has no score, and current-format peaks tables (no MBR Score column) read, with seven more columns.
  • offset/limit window after a full parse; memory and time scale with the file, not the window.
  • pro_forma is never absent at mzLib 1.0.592: when a psmtsv has no ProForma column it is computed from Full Sequence, which the reader REQUIRES (SpectrumMatchFromTsv.cs:194), so a file without both fails to read instead.
  • Many files: --paths-stdin needs every input to have the same record type (the long table has one column set); a mixed list is a usage error naming the groups. Otherwise as every bulk verb: one process, --threads at a time, output identical at any thread count.

Example

result = pymzlib.readers.read_records(path, limit=3)

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

result = pymzlib.readers.read_records(path)

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

result = pymzlib.readers.read_records(path, limit=3)

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

result = pymzlib.readers.read_records(path, limit=2)

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

result = pymzlib.readers.read_records(path)

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

result = pymzlib.readers.read_records('FlashLFQ_MzLib1.0.591_QuantifiedPeaks.tsv', limit=2)

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

batch = pymzlib.readers.read_records_many(['PXD078927_msgf_1_1_0.mzid', 'PXD078927_msgf_1_1_0.mzid.gz'], threads=2)

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

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.readers.read_records mzlib::readers::read_records_with with ReadOptions readers_read_records

References

None: no publication is attached to this verb.

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.1.0 0.1.0 0.1.0

Not yet verified

  • The three mzLib 1.0.592 fixtures (mzid_gz, mm_protein_groups, mm_peptides) exist only on pyMzLib#61 until it merges; mzLibRust and mzLibR have not copied them.
  • absent_fields for read-records is judged only for record types mapped with CsvHelper [Name] attributes (FlashLFQ peaks, MSFragger, MsPathFinderT, TopFD, the #1347 tables, ...). psmtsv/osmtsv parse their own header dictionary, so their optional columns are not judged yet; an empty list there means no basis, not nothing absent.
  • PYB-3 part 2: refusing a too-large answer BEFORE serialising, when the parsed record count already predicts it, is not built. It needs a characters-per-record threshold measured per format (dataRepo's ~805 per record is one file type); part 1 catches the failure after serialising.

read_spectra

Read the scans of a spectra file: every scan's header always, and its peak arrays only on request.

Wire verb readers read-spectra · Python pymzlib.readers.read_spectra

Wraps

Parameters

Parameter Type Default Unit Range Meaning
path path required — — A spectra file: mzML, MGF, ms1/ms2 msalign, Thermo .raw, Bruker .d or timsTOF .d.
ms_order (wire --ms-order) int absent — >= 1 Keep only scans at this MS level. Applied BEFORE offset and limit, so ms-order 2 with limit 10 is the first ten MS2 scans. Given with no value is a usage error; absent means every level.
offset int 0 scans >= 0 Skip this many scans (after the ms-order filter).
limit int absent scans >= 0 Return at most this many scans. Absent means no limit.
peaks flag false — — Include the mz and intensity arrays. Off by default because peaks are roughly the size of the file; combine with limit, a scan filter, or out.
out path absent — .tsv only, any case (PYB-1) Write the table to this path as TSV instead of returning columns. Must differ from path. Peak arrays are written as ';'-joined lists. Must end in .tsv, any case (PYB-1); any other extension, or none, is a usage error before any input is read, and no extension is appended.

Returns

Top-level fields:

Field Type Unit Null? Meaning
path string — never Absolute path of the input.
file_type string — never mzLib SupportedFileType name.
reader string — never The mzLib MsDataFile class that read it.
scan_count int scans never The file's true total, before any filter, so a filter matching nothing never looks like an empty file.
ms_order int — yes: no ms-order filter was applied The ms-order filter, echoed.
record_count int scans never Scans that passed the ms-order filter.
returned_count int scans never Scans in columns; 0 when written to out.
offset int scans never The offset applied.
truncated bool — never True whenever scans were left out by offset or limit.
peaks_included bool — never Whether mz and intensity columns are present.
retention_time_unit string — never Always "minutes" for this verb: every mzLib MsDataFile reader converts at the boundary.
caveats string[] — never Format-specific traps for THIS file; see caveats below.
column_names string[] — never Column order.
columns table — yes: the table was written to out instead Column name to per-scan values.
output object — yes: out was not given {path, format: "tsv", row_count} when out was given.
source object — yes: the reader built no source-file description at all (inner fields are null individually when the file does not record them) {instrument_model, instrument_model_accession, instrument_serial_number, acquisition_start_time, acquisition_start_time_is_utc} from mzLib SourceFile (#1349). instrument_model is the model NAME and instrument_model_accession its PSI-MS accession (mzML has both; Thermo .raw only the name, so the accession is null - match on the accession, never the name). acquisition_start_time is ISO-8601 text, ending in Z only when the source fixed the instant (mzML startTimeStamp with an offset); otherwise the acquisition PC's wall-clock time. acquisition_start_time_is_utc is never null: false means local instrument-PC time or absent, and is always false for Thermo .raw. Each inner field is null when the file does not record it (MGF and msalign record none).
rows_not_read int rows yes: never counted for this verb Always null.
absent_fields string[] — never Always empty for this verb: an unrecorded scan field is null per scan.
failed_fields string[] — never 'field: ExceptionType' for each column whose read threw on some scans; those cells are null.
excluded_fields object[] — never Always empty for this verb.
error object — yes: always, for a single path: a file that cannot be read fails the call instead {kind, type, message}; non-null only in a files[] entry under on-error skip.

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

Field Type Unit Null? Meaning
one_based_scan_number int — never Scan number. For MGF it may be assigned in file order; see caveats.
ms_order int — never MS level (1, 2, ...).
retention_time float min never Retention time.
polarity string — never mzLib Polarity enum name.
mz_analyzer string — never mzLib MZAnalyzerType enum name.
is_centroid bool — never Whether the spectrum is centroided.
total_ion_current float intensity (instrument units) never Total ion current.
injection_time float ms yes: the file did not record it Ion injection time.
peak_count int peaks never Peaks in the scan; 0 when it has no spectrum.
scan_window_lower_mz float m/z yes: no scan window recorded Lower scan-window bound. DERIVED for MGF (first observed peak).
scan_window_upper_mz float m/z yes: no scan window recorded Upper scan-window bound. DERIVED for MGF (last observed peak).
scan_filter string — yes: the file did not record one Vendor scan filter string.
native_id string — yes: the file did not record one Vendor native ID.
scan_description string — yes: the file did not record one Free-text scan description.
one_based_precursor_scan_number int — yes: MS1 scan, or the file does not record the survey scan (standard MGF) Survey scan this scan was selected from.
isolation_mz float m/z yes: MS1 scan, or not recorded Isolation window centre. May be calibration-adjusted.
isolation_width float m/z yes: MS1 scan, or not recorded Isolation window width.
selected_ion_mz float m/z yes: MS1 scan, or not recorded Selected precursor m/z. May be calibration-adjusted.
selected_ion_intensity float intensity (instrument units) yes: MS1 scan, or not recorded Selected precursor intensity.
selected_ion_charge_state_guess int charge yes: MS1 scan, or no charge assigned Instrument or file charge-state guess.
selected_ion_monoisotopic_guess_mz float m/z yes: MS1 scan, or no monoisotopic guess Monoisotopic precursor m/z guess.
dissociation_type string — yes: MS1 scan, or not recorded mzLib DissociationType enum name.
hcd_energy string — yes: not HCD, or not recorded Collision energy AS WRITTEN by the file (mzLib keeps it a string, e.g. "35" or "25,30,35"); not parsed.
compensation_voltage float V yes: no FAIMS on this instrument FAIMS compensation voltage.
mz float[] m/z yes: scan has no spectrum Peak m/z values. Present only with peaks.
intensity float[] intensity (instrument units) yes: scan has no spectrum Peak intensities, parallel to mz. Present only with peaks.

Errors

Kind pyMzLib raises When
usage UsageError path missing or blank; file not found; the file is not one of the seven spectra types (the message names the views it does have)
usage UsageError ms-order, offset, limit or out given with no value; ms-order < 1; offset or limit < 0; non-integer value
usage UsageError out resolves to the same file as path
correctness BridgeError a vendor format that cannot load on this platform surfaces as its real failure (Bruker/timsTOF native DLLs are Windows x64 only)
usage UsageError paths-stdin with path, offset or limit; paths-stdin with a value; no paths on stdin; a repeated path; threads 0 or below -1; on-error not fail or skip; on-error skip with a single path; out naming an input
usage UsageError with on-error fail, an input that is missing or not this view: the usage error of that input, prefixed 'Input ()'
correctness BridgeError with on-error fail, mzLib failing to parse an input: that input's own error type, message prefixed 'Input ()'
usage UsageError out (with path or paths-stdin) whose extension is not .tsv, any case, including none (PYB-1); checked before any input is opened
usage UsageError the answer is too large to return as one JSON document (PYB-3 part 1; measured: past the ~1.07 G-character .NET string ceiling, not RAM). Message: 'this read (N records) is too large to return as one document; use --limit/--offset or --out', N the parsed record_count
service_unavailable ServiceUnavailableError never raised by this verb

Caveats

  • Headers only unless peaks is set; peak_count tells you how many peaks, not what they are.
  • Bruker .d and timsTOF .d need vendor native DLLs and read only on Windows x64. Thermo .raw is managed and reads everywhere.
  • MGF: scan numbers may be file order; precursor scan is null unless the mzLib PRECURSORSCAN header is present; ms_order comes from MSLEVEL or is inferred from PEPMASS; the scan window is derived from observed peaks.
  • msalign holds DECONVOLVED neutral monoisotopic masses, not raw m/z: the mz column is not comparable with an mzML or raw file's mz and must not be re-deconvolved.
  • msalign: scan_window_lower_mz/_upper_mz are in m/z while the mz column is neutral MASS, so they are not on the same axis. mzLib synthesises the window by converting each mass back to m/z at its reported charge (MsAlign.cs:526); msalign records no window of its own.
  • timsTOF .d is ion-mobility-resolved and this view flattens it: the mobility dimension is collapsed into scans and no 1/K0 value is reported.
  • source.acquisition_start_time from a Thermo .raw is the acquisition PC's local clock (is_utc false); ProteoWizard's mzML of the same run writes it as UTC assuming the CONVERTING machine's time zone, so the two can differ by the site's UTC offset (SourceFile.AcquisitionStartTime).
  • Many files: --paths-stdin reads the list in ONE process, --threads at a time, into one long table with source_index and source_path first. The output does not depend on --threads (a tested property); the default of 1 is a memory choice, since every reader materialises the whole file.

Example

result = pymzlib.readers.read_spectra(path, limit=3)

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

batch = pymzlib.readers.read_spectra_many(['sliced_ethcd.mzML', 'no-such-run.mzML', 'withZeros.mgf'], threads=2, on_error='skip')

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

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.readers.read_spectra mzlib::readers::read_spectra_with with SpectraOptions readers_read_spectra

References

None: no publication is attached to this verb.

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.1.0 0.1.0 0.1.0

Not yet verified

  • injection_time unit 'ms' is from the mzML CV term (MS:1000927); not yet confirmed that every mzLib vendor reader (Thermo, Bruker, timsTOF, MGF) emits ms.
  • source is read from MsDataFile.SourceFile after LoadAllStaticData; Bruker .d and timsTOF .d have not been checked for which of its fields they fill.
  • PYB-3 part 2: refusing a too-large answer BEFORE serialising, when the parsed record count already predicts it, is not built. It needs a characters-per-record threshold measured per format (dataRepo's ~805 per record is one file type); part 1 catches the failure after serialising.

identify

Say what kind of file a path is - the mzLib file type, its extension, its reader and the cross-format views it offers - without parsing its contents.

Wire verb readers identify · Python pymzlib.readers.identify

Wraps

Parameters

Parameter Type Default Unit Range Meaning
path path required — — Any file (or Bruker .d directory). For many paths see the caveat on --paths-stdin.

Returns

Top-level fields:

Field Type Unit Null? Meaning
path string — never Absolute path identified.
file_type string — never The mzLib SupportedFileType.
extension string — yes: mzLib maps no extension to this type The extension mzLib dispatched on.
reader string — never The mzLib reader class that would parse it.
views string[] — never The cross-format views it offers; often empty.
error object — yes: always, for a single path; in a paths-stdin entry, the path was identified {kind, type, message} for a path that failed under on-error skip.

Errors

Kind pyMzLib raises When
usage UsageError path missing, blank or not found; mzLib does not recognise the file type
usage UsageError paths-stdin with path, offset or limit; paths-stdin with a value; no paths on stdin; a repeated path; threads 0 or below -1; on-error not fail or skip; on-error skip with a single path; out naming an input
usage UsageError with on-error fail, an input that is missing or not this view: the usage error of that input, prefixed 'Input ()'
usage UsageError out with paths-stdin: identify returns no table
service_unavailable ServiceUnavailableError never raised by this verb

Caveats

  • Cheap but not pure: mzLib reads a bare .tsv's first line, a .mztab's first five and a .d directory's listing to dispatch them.
  • No software field: mzLib's Software property is Unspecified for everything its factory builds; file_type already names the tool.
  • Many paths: --paths-stdin (newline-delimited paths on stdin) with --threads N (default 1, -1 = one per core; the answer is identical at any value) and --on-error fail|skip answers {file_count, read_count, failed_count, on_error, files}, files[i] being path i's answer in input order with error set when it could not be identified under skip (readers_many_identify.json). There is no table and no --out.

Example

result = pymzlib.readers.identify('PXD078927_msgf_1_1_0.mzid')

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

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.readers.identify mzlib::readers::identify readers_identify

References

None: no publication is attached to this verb.

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.1.0 0.1.0 0.1.0

Not yet verified

  • The --paths-stdin answer is not declared as result.bulk because check_verbs.py requires a record_count there (BULK.md section 2), and the bridge sends none: at pyMzLib v0.2.0 (pkg/bridge/Reading.cs Identify) it is {file_count, read_count, failed_count, on_error, files}, as are IdentifyBatch (Rust) and readers_identify_many (R). All three bindings ship identify_many. Declare result.bulk once the checker allows a table-less bulk verb, or add record_count (0) to the wire.

read_results

Read a result file through the cross-format quantifiable view: sequence, retention time, charge, theoretical mass, decoy flag and protein groups, the same columns for every format that offers it.

Wire verb readers read-results · Python pymzlib.readers.read_results

Wraps

Parameters

Parameter Type Default Unit Range Meaning
path path required — — A MetaMorpheus .psmtsv/.osmtsv, an MSFragger psm.tsv or a DIA-NN report.tsv.
offset int 0 records >= 0 Skip this many records. A window, not a cursor: mzLib parses the whole file on every call, so paging re-reads it.
limit int absent records >= 0 Return at most this many records. Absent means no limit; there is deliberately no default cap.
out path absent — .tsv only, any case (PYB-1) Write the table to this path as tab-separated text instead of returning columns. Must differ from path. Parent directories are created. Must end in .tsv, any case (PYB-1); any other extension, or none, is a usage error before any input is read, and no extension is appended.

Returns

Top-level fields:

Field Type Unit Null? Meaning
path string — never Absolute path of the input.
file_type string — never The mzLib SupportedFileType that was dispatched.
reader string — never The mzLib reader class that parsed the file.
record_count int records never Records in the whole file, before the window.
rows_not_read int rows yes: the count is not meaningful for this format (only the psmtsv family and MSFragger are one line per record) Data rows that did not become records: mzLib drops a malformed line silently.
retention_time_unit string — never The unit of retention_time for THIS format: minutes for all four at mzLib 1.0.592, unknown when mzLib gives no basis.
caveats string[] — never What this view cannot be trusted to mean for THIS file, each citing the mzLib source.
column_names string[] — never Column order.
absent_fields string[] — never Columns the view defines that this file's format has no column or source for; null in every row (BULK.md section 4). Empty when every column has a source.
failed_fields string[] — never 'field: ExceptionType' for each column whose read threw on some returned rows; those cells are null.
excluded_fields object[] — never {field, type, reason, verb} for each field with no column shape; verb names the command that carries it, or null.
error object — yes: always, for a single path: a file that cannot be read fails the call instead {kind, type, message}; non-null only in a files[] entry under on-error skip.
returned_count int records never Records returned in columns (the unit offset and limit count in); 0 when written to out.
offset int records never The offset applied, in records.
truncated bool — never True whenever records were left out by offset or limit.
columns table — yes: the table was written to out instead Column name to per-row values, in column_names order.
output object — yes: out was not given {path, format: "tsv", row_count} when out was given.

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 row's input in the stdin list. Present only with --paths-stdin.
source_path string — never Absolute path of the row's input. Present only with --paths-stdin.
file_name string — never The spectra file the record came from, as the format writes it (not a join key across formats).
base_sequence string — never Unmodified sequence.
full_sequence string — never Modified sequence; on an ambiguous psmtsv row every candidate '|'-joined.
retention_time float min yes: mzLib's -1 'absent' sentinel, or a non-finite value Retention time, in retention_time_unit.
charge_state int charge never Precursor charge.
monoisotopic_mass float Da yes: mzLib's -1 'absent' sentinel THEORETICAL peptide mass, not the observed precursor.
is_decoy bool — yes: the format cannot report decoys: MSFragger and DIA-NN, where is_decoy is also in absent_fields Decoy flag where the format carries one.
protein_accessions string — never ';'-joined accessions.
gene_name string — never ';'-joined gene names.
organism string — never ';'-joined organisms.

Errors

Kind pyMzLib raises When
usage UsageError path missing or blank; file or directory not found; mzLib does not recognise the file type (the message points at readers formats)
usage UsageError offset, limit or out given with no value; offset or limit < 0; non-integer value; out resolves to the same file as path
usage UsageError the file has no quantifiable view (the message names the views it does have)
correctness BridgeError mzLib recognises the file and fails to parse it
usage UsageError paths-stdin with path, offset or limit; paths-stdin with a value; no paths on stdin; a repeated path; threads 0 or below -1; on-error not fail or skip; on-error skip with a single path; out naming an input
usage UsageError with on-error fail, an input that is missing or not this view: the usage error of that input, prefixed 'Input ()'
correctness BridgeError with on-error fail, mzLib failing to parse an input: that input's own error type, message prefixed 'Input ()'
usage UsageError out (with path or paths-stdin) whose extension is not .tsv, any case, including none (PYB-1); checked before any input is opened
usage UsageError the answer is too large to return as one JSON document (PYB-3 part 1; measured: past the ~1.07 G-character .NET string ceiling, not RAM). Message: 'this read (N records) is too large to return as one document; use --limit/--offset or --out', N the parsed record_count
service_unavailable ServiceUnavailableError never raised by this verb

Caveats

  • No q-value, PEP or score: nothing here is FDR-filtered.
  • is_decoy is absent for MSFragger and DIA-NN, which write no target/decoy label; null there means unknown, not target.
  • monoisotopic_mass is the theoretical mass in every format; the observed precursor is not in this view.
  • psmtsv: monoisotopic_mass keeps the first candidate of an ambiguous row while full_sequence keeps them all (SpectrumMatchFromTsv.cs:119, :194).
  • A malformed psmtsv row is dropped silently by mzLib; rows_not_read counts them.
  • Many files: --paths-stdin reads the list in ONE process, --threads at a time, into one long table with source_index and source_path first. The output does not depend on --threads (a tested property); the default of 1 is a memory choice, since every reader materialises the whole file.

Example

result = pymzlib.readers.read_results('FraggerPsm_FragPipev21.1_psm.tsv', limit=2)

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

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.readers.read_results mzlib::readers::read_results_with with ReadOptions readers_read_results

References

None: no publication is attached to this verb.

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.1.0 0.1.0 0.1.0

Not yet verified

  • PYB-3 part 2: refusing a too-large answer BEFORE serialising, when the parsed record count already predicts it, is not built. It needs a characters-per-record threshold measured per format (dataRepo's ~805 per record is one file type); part 1 catches the failure after serialising.

read_features

Read deconvolved MS1 features through the cross-format ms1_features view: m/z, charge, retention-time range, apex intensity and isotope count.

Wire verb readers read-features · Python pymzlib.readers.read_features

Wraps

Parameters

Parameter Type Default Unit Range Meaning
path path required — — A TopFD/FLASHDeconv _ms1.feature or a Dinosaur .feature.tsv.
offset int 0 features >= 0 Skip this many features. A window, not a cursor: mzLib parses the whole file on every call, so paging re-reads it.
limit int absent features >= 0 Return at most this many features. Absent means no limit; there is deliberately no default cap.
out path absent — .tsv only, any case (PYB-1) Write the table to this path as tab-separated text instead of returning columns. Must differ from path. Parent directories are created. Must end in .tsv, any case (PYB-1); any other extension, or none, is a usage error before any input is read, and no extension is appended.

Returns

Top-level fields:

Field Type Unit Null? Meaning
path string — never Absolute path of the input.
file_type string — never The mzLib SupportedFileType that was dispatched.
reader string — never The mzLib reader class that parsed the file.
record_count int features never Features in the whole file, before the window.
rows_not_read int rows yes: never counted: one line is not one feature (_ms1.feature rows are expanded per charge) Data rows that did not become records.
retention_time_unit string — never minutes for Dinosaur; unknown for _ms1.feature, whose unit changed at TopFD v1.7.0 without a format change.
caveats string[] — never What this view cannot be trusted to mean for THIS file, each citing the mzLib source.
column_names string[] — never Column order.
absent_fields string[] — never Columns the view defines that this file's format has no column or source for; null in every row (BULK.md section 4). Empty when every column has a source.
failed_fields string[] — never 'field: ExceptionType' for each column whose read threw on some returned rows; those cells are null.
excluded_fields object[] — never {field, type, reason, verb} for each field with no column shape; verb names the command that carries it, or null.
error object — yes: always, for a single path: a file that cannot be read fails the call instead {kind, type, message}; non-null only in a files[] entry under on-error skip.
returned_count int features never Features returned in columns (the unit offset and limit count in); 0 when written to out.
offset int features never The offset applied, in features.
truncated bool — never True whenever records were left out by offset or limit.
columns table — yes: the table was written to out instead Column name to per-row values, in column_names order.
output object — yes: out was not given {path, format: "tsv", row_count} when out was given.

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 row's input in the stdin list. Present only with --paths-stdin.
source_path string — never Absolute path of the row's input. Present only with --paths-stdin.
mz float m/z never Monoisotopic m/z of this single-charge feature.
charge int charge never Charge state.
retention_time_start float retention_time_unit never Feature start, in retention_time_unit.
retention_time_end float retention_time_unit never Feature end, in retention_time_unit.
intensity float intensity (instrument units) yes: the file has no apex intensity (FLASHDeconv schema, then in absent_fields) or this feature has none Apex intensity (Dinosaur intensityApex; TopFD Apex_intensity).
number_of_isotopes int — yes: _ms1.feature: mzLib never sets it (then in absent_fields) Isotopes in the feature.

Errors

Kind pyMzLib raises When
usage UsageError path missing or blank; file or directory not found; mzLib does not recognise the file type (the message points at readers formats)
usage UsageError offset, limit or out given with no value; offset or limit < 0; non-integer value; out resolves to the same file as path
usage UsageError the file has no ms1_features view
correctness BridgeError mzLib recognises the file and fails to parse it
usage UsageError paths-stdin with path, offset or limit; paths-stdin with a value; no paths on stdin; a repeated path; threads 0 or below -1; on-error not fail or skip; on-error skip with a single path; out naming an input
usage UsageError with on-error fail, an input that is missing or not this view: the usage error of that input, prefixed 'Input ()'
correctness BridgeError with on-error fail, mzLib failing to parse an input: that input's own error type, message prefixed 'Input ()'
usage UsageError out (with path or paths-stdin) whose extension is not .tsv, any case, including none (PYB-1); checked before any input is opened
usage UsageError the answer is too large to return as one JSON document (PYB-3 part 1; measured: past the ~1.07 G-character .NET string ceiling, not RAM). Message: 'this read (N records) is too large to return as one document; use --limit/--offset or --out', N the parsed record_count
service_unavailable ServiceUnavailableError never raised by this verb

Caveats

  • _ms1.feature rows are expanded to one per charge in [ChargeStateMin, ChargeStateMax] (Ms1Feature.cs:84); Dinosaur is one row per file line.
  • intensity is the per-charge APEX intensity (Ms1Feature.cs:86); a FLASHDeconv file has none and names intensity in absent_fields instead of reporting mzLib's zero.
  • number_of_isotopes is absent for every _ms1.feature (Ms1Feature.cs:91).
  • Many files: --paths-stdin reads the list in ONE process, --threads at a time, into one long table with source_index and source_path first. The output does not depend on --threads (a tested property); the default of 1 is a memory choice, since every reader materialises the whole file.

Example

result = pymzlib.readers.read_features('Ms1Feature_TopFDv1.6.2_ms1.feature', limit=5)

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

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.readers.read_features mzlib::readers::read_features_with with ReadOptions readers_read_features

References

None: no publication is attached to this verb.

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.1.0 0.1.0 0.1.0

Not yet verified

  • retention_time_start/_end declare their unit as the envelope's retention_time_unit, not a fixed unit, because it genuinely varies per file.
  • PYB-3 part 2: refusing a too-large answer BEFORE serialising, when the parsed record count already predicts it, is not built. It needs a characters-per-record threshold measured per format (dataRepo's ~805 per record is one file type); part 1 catches the failure after serialising.

read_matches

Read identifications through the cross-format spectral_match view - scan, sequences, accession, decoy flag, modifications and the q-value, rank and threshold a format records - optionally with each engine's scores as long rows.

Wire verb readers read-matches · Python pymzlib.readers.read_matches

Wraps

Parameters

Parameter Type Default Unit Range Meaning
path path required — — An MsPathFinderT _IcTarget/_IcDecoy/_IcTda.tsv, a Casanovo .mztab, or an mzIdentML .mzid / .mzid.gz.
offset int 0 matches >= 0 Skip this many matches. A window, not a cursor: mzLib parses the whole file on every call, so paging re-reads it.
limit int absent matches >= 0 Return at most this many matches. Absent means no limit; there is deliberately no default cap.
scores flag false — — Make the table long by score: one row per match and engine score, adding match_index, score_name and score_value. Only mzIdentML records scores (#1306); other formats keep one row per match with the two columns in absent_fields. offset and limit still count matches.
out path absent — .tsv only, any case (PYB-1) Write the table to this path as tab-separated text instead of returning columns. Must differ from path. Parent directories are created. Must end in .tsv, any case (PYB-1); any other extension, or none, is a usage error before any input is read, and no extension is appended.

Returns

Top-level fields:

Field Type Unit Null? Meaning
path string — never Absolute path of the input.
file_type string — never The mzLib SupportedFileType that was dispatched.
reader string — never The mzLib reader class that parsed the file.
skipped_count int items yes: the format keeps no skip list (every format but mzIdentML) mzIdentML items mzLib did not represent (crosslinks, unresolvable modifications, substitutions); record_count + skipped_count is the items in the file (#1313).
skipped object[] — yes: as skipped_count {spectrum_identification_item_id, spectrum_id, reason} per skipped item.
record_count int matches never Matches in the whole file, before the window.
rows_not_read int rows yes: never counted for this view Data rows that did not become records.
retention_time_unit string — yes: the view has no time column Always null for this view.
caveats string[] — never What this view cannot be trusted to mean for THIS file, each citing the mzLib source.
column_names string[] — never Column order.
absent_fields string[] — never Columns the view defines that this file's format has no column or source for; null in every row (BULK.md section 4). Empty when every column has a source.
failed_fields string[] — never 'field: ExceptionType' for each column whose read threw on some returned rows; those cells are null.
excluded_fields object[] — never {field, type, reason, verb} for each field with no column shape; verb names the command that carries it, or null.
error object — yes: always, for a single path: a file that cannot be read fails the call instead {kind, type, message}; non-null only in a files[] entry under on-error skip.
scores_included bool — never Whether --scores made the table long by score.
returned_count int matches never Matches returned in columns (the unit offset and limit count in); 0 when written to out.
row_count int rows never Rows in columns: more than returned_count in a long table, where one record gives several rows; 0 when written to out.
offset int matches never The offset applied, in matches.
truncated bool — never True whenever records were left out by offset or limit.
columns table — yes: the table was written to out instead Column name to per-row values, in column_names order.
output object — yes: out was not given {path, format: "tsv", row_count} when out was given.

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 row's input in the stdin list. Present only with --paths-stdin.
source_path string — never Absolute path of the row's input. Present only with --paths-stdin.
file_name_without_extension string — never The spectra file of the match.
one_based_scan_number int — never Scan number; see caveats for mzIdentML index= and Casanovo.
base_sequence string — never Unmodified sequence.
full_sequence string — never Modified sequence.
accession string — yes: the property threw (then in failed_fields) Protein accession(s).
is_decoy bool — yes: every format but MsPathFinderT (then in absent_fields) Decoy flag.
modifications string — never 'position:name' pairs, ';'-joined, 1 = N-terminus.
modification_count int — never Modifications on the match.
q_value float fraction (0 to 1) yes: the format has no q-value (in absent_fields) or this mzIdentML item reports none PSM-level q-value (mzIdentML MS:1002354 or a child; MsPathFinderT QValue).
rank int — yes: not mzIdentML (in absent_fields) The item's rank; filter on rank == 1.
pass_threshold bool — yes: not mzIdentML (in absent_fields) The item's passThreshold.
match_index int — never 0-based position of the match among the file's matches. Present only with scores.
score_name string — yes: the match has no scores, or the format records none (in absent_fields) Engine score name as written, e.g. MS-GF:SpecEValue. Present only with scores.
score_value float engine-defined (see score_name) yes: as score_name The score's value. Present only with scores.

Errors

Kind pyMzLib raises When
usage UsageError path missing or blank; file or directory not found; mzLib does not recognise the file type (the message points at readers formats)
usage UsageError offset, limit or out given with no value; offset or limit < 0; non-integer value; out resolves to the same file as path
usage UsageError the file has no spectral_match view
correctness BridgeError mzLib recognises the file and fails to parse it
usage UsageError paths-stdin with path, offset or limit; paths-stdin with a value; no paths on stdin; a repeated path; threads 0 or below -1; on-error not fail or skip; on-error skip with a single path; out naming an input
usage UsageError with on-error fail, an input that is missing or not this view: the usage error of that input, prefixed 'Input ()'
correctness BridgeError with on-error fail, mzLib failing to parse an input: that input's own error type, message prefixed 'Input ()'
usage UsageError out (with path or paths-stdin) whose extension is not .tsv, any case, including none (PYB-1); checked before any input is opened
usage UsageError the answer is too large to return as one JSON document (PYB-3 part 1; measured: past the ~1.07 G-character .NET string ceiling, not RAM). Message: 'this read (N records) is too large to return as one document; use --limit/--offset or --out', N the parsed record_count
service_unavailable ServiceUnavailableError never raised by this verb

Caveats

  • Nothing is FDR-filtered. q_value is filled only by mzIdentML and an MsPathFinderT file with a QValue column; an _IcTarget/_IcDecoy file has none and names it absent (mzLib would report 0).
  • mzIdentML: every SpectrumIdentificationItem is a row, lower ranks and failed thresholds included (MzIdentMLResultFile.cs:193). Filter on rank == 1 and pass_threshold.
  • mzIdentML: is_decoy is absent because the isDecoy attribute defaults to false when omitted (MzIdentMLResultFile.cs:189).
  • mzIdentML: items mzLib cannot represent are skipped, not failed, and listed in skipped (MzIdentMLResultFile.cs:123).
  • MsPathFinderT: is_decoy comes from an XXX protein-name prefix (MsPathFinderTResult.cs:92); accession assumes a UniProt header and lands in failed_fields otherwise.
  • Casanovo: one_based_scan_number is the mzTab index plus one (CasanovoMzTabFile.cs:116).
  • Many files: --paths-stdin reads the list in ONE process, --threads at a time, into one long table with source_index and source_path first. The output does not depend on --threads (a tested property); the default of 1 is a memory choice, since every reader materialises the whole file.

Example

result = pymzlib.readers.read_matches('PXD078927_msgf_1_1_0.mzid', limit=3)

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

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.readers.read_matches mzlib::readers::read_matches_with with MatchOptions readers_read_matches

References

None: no publication is attached to this verb.

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.1.0 0.1.0 0.1.0

Not yet verified

  • readers_matches_mzid_scores.json (--scores) is replayed through the pyMzLib conftest rather than listed here: check_verbs.py excludes present_when columns from its column check, so a --scores fixture cannot be a spec example yet.
  • q_value, rank and pass_threshold join a view whose other columns are Readers.ISpectralMatch members; they are read from the record types that carry them. If mzLib adds them to the interface, the per-format reads go away.
  • PYB-3 part 2: refusing a too-large answer BEFORE serialising, when the parsed record count already predicts it, is not built. It needs a characters-per-record threshold measured per format (dataRepo's ~805 per record is one file type); part 1 catches the failure after serialising.

read_protein_groups

Read a MetaMorpheus AllQuantifiedProteinGroups.tsv as one row per protein group per sample group, with each sample group's spectral count and intensity as columns.

Wire verb readers read-protein-groups · Python pymzlib.readers.read_protein_groups

Wraps

Parameters

Parameter Type Default Unit Range Meaning
path path required — — A MetaMorpheus protein-group table: AllQuantifiedProteinGroups.tsv, or (mzLib 1.0.593, #1365) AllProteinGroups.tsv and _ProteinGroups.tsv; or an RNA search's AllQuantifiedTranscriptGroups.tsv (#1388), whose reader subclasses the protein-group one.
offset int 0 groups >= 0 Skip this many protein groups (each gives one row per sample group). A window, not a cursor: mzLib parses the whole file on every call, so paging re-reads it.
limit int absent groups >= 0 Return at most this many protein groups (each gives one row per sample group). Absent means no limit; there is deliberately no default cap.
out path absent — .tsv only, any case (PYB-1) Write the table to this path as tab-separated text instead of returning columns. Must differ from path. Parent directories are created. Must end in .tsv, any case (PYB-1); any other extension, or none, is a usage error before any input is read, and no extension is appended.

Returns

Top-level fields:

Field Type Unit Null? Meaning
path string — never Absolute path of the input.
file_type string — never The mzLib SupportedFileType that was dispatched.
reader string — never The mzLib reader class that parsed the file.
sample_labels string[] — never The file's sample-group labels in header order, verbatim (e.g. QE-002106_GM1_a-calib). Condition and replicate cannot be recovered from them.
record_count int groups never Groups in the whole file, before the window.
rows_not_read int rows yes: not counted for this table: one line is one group, and every group is read or the file fails Data rows that did not become records.
retention_time_unit string — yes: the table has no time column Always null for this table.
caveats string[] — never What this view cannot be trusted to mean for THIS file, each citing the mzLib source.
column_names string[] — never Column order.
absent_fields string[] — never Columns the view defines that this file's format has no column or source for; null in every row (BULK.md section 4). Empty when every column has a source.
failed_fields string[] — never 'field: ExceptionType' for each column whose read threw on some returned rows; those cells are null.
excluded_fields object[] — never {field, type, reason, verb} for each field with no column shape; verb names the command that carries it, or null.
error object — yes: always, for a single path: a file that cannot be read fails the call instead {kind, type, message}; non-null only in a files[] entry under on-error skip.
returned_count int groups never Groups returned in columns (the unit offset and limit count in); 0 when written to out.
row_count int rows never Rows in columns: more than returned_count in a long table, where one record gives several rows; 0 when written to out.
offset int groups never The offset applied, in groups.
truncated bool — never True whenever records were left out by offset or limit.
columns table — yes: the table was written to out instead Column name to per-row values, in column_names order.
output object — yes: out was not given {path, format: "tsv", row_count} when out was given.

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 row's input in the stdin list. Present only with --paths-stdin.
source_path string — never Absolute path of the row's input. Present only with --paths-stdin.
protein_group_name string — never The members' accessions '|'-joined in accession order (ProteinGroupFromTsv.ProteinGroupName); the join key to read-records.
gene string — yes: the file has no Gene column (then also in absent_fields) or the cell is blank Gene name(s) as written.
organism string — yes: the file has no Organism column (then also in absent_fields) or the cell is blank Organism as written.
decoy_contaminant_target string — never T, D, C, or entrapment ET/ED, as written.
is_decoy bool — never decoy_contaminant_target contains D (mzLib's IsDecoy).
is_contaminant bool — never decoy_contaminant_target is C.
is_entrapment bool — never decoy_contaminant_target starts with E.
q_value float fraction (0 to 1) never The group's q-value; the table is unfiltered and this is what filtering reads.
sample_label string — yes: the file has no per-sample columns: the group is one row and this is in absent_fields The sample group this row measures.
spectral_count int PSMs yes: the cell is blank, or the file has no SpectralCount_ columns (then in absent_fields); an isobaric intensity-only label has none PSMs from this sample group assigned to the group (SpectralCount_).
intensity float intensity (instrument units) yes: the cell was blank: not quantified in this sample group, which is not zero The group's intensity in this sample group (Intensity_).

Errors

Kind pyMzLib raises When
usage UsageError path missing or blank; file or directory not found; mzLib does not recognise the file type (the message points at readers formats)
usage UsageError offset, limit or out given with no value; offset or limit < 0; non-integer value; out resolves to the same file as path
usage UsageError the file is not a MetaMorpheus protein-group table (the message names what it is and points at read-records)
correctness BridgeError mzLib cannot parse the table (MzLibException)
usage UsageError paths-stdin with path, offset or limit; paths-stdin with a value; no paths on stdin; a repeated path; threads 0 or below -1; on-error not fail or skip; on-error skip with a single path; out naming an input
usage UsageError with on-error fail, an input that is missing or not this view: the usage error of that input, prefixed 'Input ()'
correctness BridgeError with on-error fail, mzLib failing to parse an input: that input's own error type, message prefixed 'Input ()'
usage UsageError out (with path or paths-stdin) whose extension is not .tsv, any case, including none (PYB-1); checked before any input is opened
usage UsageError the answer is too large to return as one JSON document (PYB-3 part 1; measured: past the ~1.07 G-character .NET string ceiling, not RAM). Message: 'this read (N records) is too large to return as one document; use --limit/--offset or --out', N the parsed record_count
service_unavailable ServiceUnavailableError never raised by this verb

Caveats

  • The table is UNFILTERED as MetaMorpheus writes it: decoys, contaminants and groups above 1% FDR are all rows (ProteinGroupFromTsv.cs:15). Filter on q_value and decoy_contaminant_target before counting.
  • Long format: one row per group per sample group. offset and limit count GROUPS, and returned_count counts rows.
  • A table MetaMorpheus wrote without label-free quantification (AllProteinGroups.tsv, ProteinGroups.tsv; readable from mzLib 1.0.593, #1365) has SpectralCount columns but no Intensity_ columns, so intensity is in absent_fields: no basis, not zero.
  • sample_label is the header label verbatim; condition, replicate and channel cannot be recovered from it (ProteinGroupFromTsv.cs:103).
  • A blank intensity is null, not zero (ProteinGroupFromTsv.cs:114). An isobaric file has one counting label and one intensity label per channel, so a row can carry only spectral_count or only intensity.
  • No member is a leading protein: members are sorted by accession (ProteinGroupFromTsv.cs:17).
  • Occupancy cells are excluded_fields with verb readers read-occupancy; the group's other fields are in read-records, joined on protein_group_name.
  • Many files: --paths-stdin reads the list in ONE process, --threads at a time, into one long table with source_index and source_path first. The output does not depend on --threads (a tested property); the default of 1 is a memory choice, since every reader materialises the whole file.

Example

result = pymzlib.readers.read_protein_groups('MetaMorpheus_1.1.11_AllQuantifiedProteinGroups.tsv', limit=1)

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

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.readers.read_protein_groups mzlib::readers::read_protein_groups_with with ReadOptions readers_read_protein_groups

References

None: no publication is attached to this verb.

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.2.0 0.1.0 0.1.0

Not yet verified

  • The group-level columns carried beside each sample (identity, q-value, decoy label) are a choice made here; coverage, masses and counts stay in read-records. Revisit if every binding ends up joining for the same field.
  • Only the MetaMorpheus 1.1.11 fixture exists (label-free); no isobaric or 1.2+ (BioPolymer ...) header table has been read through this verb yet.
  • PYB-3 part 2: refusing a too-large answer BEFORE serialising, when the parsed record count already predicts it, is not built. It needs a characters-per-record threshold measured per format (dataRepo's ~805 per record is one file type); part 1 catches the failure after serialising.

read_quantified_peptides

Read a FlashLFQ QuantifiedPeptides.tsv (or MetaMorpheus AllQuantifiedPeptides.tsv) as one row per peptide per sample, with the sample's intensity and detection type as columns.

Wire verb readers read-quantified-peptides · Python pymzlib.readers.read_quantified_peptides

Wraps

Parameters

Parameter Type Default Unit Range Meaning
path path required — — A FlashLFQ QuantifiedPeptides.tsv or MetaMorpheus AllQuantifiedPeptides.tsv (readers identify reports FlashLFQQuantifiedPeptide), or an RNA search's AllQuantifiedOligos.tsv (mzLib 1.0.593, #1388: FlashLFQQuantifiedOligo, whose reader subclasses the peptide one; sequence then holds an oligonucleotide).
offset int 0 peptides >= 0 Skip this many peptides (each gives one row per sample). A window, not a cursor: mzLib parses the whole file on every call, so paging re-reads it.
limit int absent peptides >= 0 Return at most this many peptides (each gives one row per sample). Absent means no limit; there is deliberately no default cap.
out path absent — .tsv only, any case (PYB-1) Write the table to this path as tab-separated text instead of returning columns. Must differ from path. Parent directories are created. Must end in .tsv, any case (PYB-1); any other extension, or none, is a usage error before any input is read, and no extension is appended.

Returns

Top-level fields:

Field Type Unit Null? Meaning
path string — never Absolute path of the input.
file_type string — never The mzLib SupportedFileType that was dispatched.
reader string — never The mzLib reader class that parsed the file.
sample_labels string[] — never The file's sample labels in header order, verbatim.
record_count int peptides never Peptides in the whole file, before the window.
rows_not_read int rows yes: not counted for this table Data rows that did not become records.
retention_time_unit string — never Always "minutes": the per-sample header is RetentionTime (min)_.
caveats string[] — never What this view cannot be trusted to mean for THIS file, each citing the mzLib source.
column_names string[] — never Column order.
absent_fields string[] — never Columns the view defines that this file's format has no column or source for; null in every row (BULK.md section 4). Empty when every column has a source.
failed_fields string[] — never 'field: ExceptionType' for each column whose read threw on some returned rows; those cells are null.
excluded_fields object[] — never {field, type, reason, verb} for each field with no column shape; verb names the command that carries it, or null.
error object — yes: always, for a single path: a file that cannot be read fails the call instead {kind, type, message}; non-null only in a files[] entry under on-error skip.
returned_count int peptides never Peptides returned in columns (the unit offset and limit count in); 0 when written to out.
row_count int rows never Rows in columns: more than returned_count in a long table, where one record gives several rows; 0 when written to out.
offset int peptides never The offset applied, in peptides.
truncated bool — never True whenever records were left out by offset or limit.
columns table — yes: the table was written to out instead Column name to per-row values, in column_names order.
output object — yes: out was not given {path, format: "tsv", row_count} when out was given.

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 row's input in the stdin list. Present only with --paths-stdin.
source_path string — never Absolute path of the row's input. Present only with --paths-stdin.
sequence string — never Full sequence with modifications (QuantifiedPeptideFromTsv.Sequence).
base_sequence string — never Unmodified sequence.
peak_order int — yes: not IsoTracker output: no Peak Order column (then in absent_fields) IsoTracker's peak order.
protein_groups string — yes: no Protein Groups column, or a blank cell Protein groups the peptide maps to, ';'-joined as written.
gene_names string — yes: no Gene Names column, or a blank cell Gene names as written.
organism string — yes: no Organism column, or a blank cell Organism as written.
sample_label string — yes: the file has no per-sample columns (then in absent_fields) The sample this row measures.
intensity float intensity (instrument units) yes: the cell was blank Intensity_ as written. FlashLFQ writes 0 for a peptide it did not quantify, and 0 crosses as 0: read detection_type.
detection_type string — yes: the cell was blank MSMS, MBR, NotDetected, ... verbatim (Detection Type_).
retention_time float min yes: not IsoTracker output (then in absent_fields) or a blank cell RetentionTime (min)_ for this sample.

Errors

Kind pyMzLib raises When
usage UsageError path missing or blank; file or directory not found; mzLib does not recognise the file type (the message points at readers formats)
usage UsageError offset, limit or out given with no value; offset or limit < 0; non-integer value; out resolves to the same file as path
usage UsageError the file is not a FlashLFQ peptide table
correctness BridgeError mzLib cannot parse the table (MzLibException)
usage UsageError paths-stdin with path, offset or limit; paths-stdin with a value; no paths on stdin; a repeated path; threads 0 or below -1; on-error not fail or skip; on-error skip with a single path; out naming an input
usage UsageError with on-error fail, an input that is missing or not this view: the usage error of that input, prefixed 'Input ()'
correctness BridgeError with on-error fail, mzLib failing to parse an input: that input's own error type, message prefixed 'Input ()'
usage UsageError out (with path or paths-stdin) whose extension is not .tsv, any case, including none (PYB-1); checked before any input is opened
usage UsageError the answer is too large to return as one JSON document (PYB-3 part 1; measured: past the ~1.07 G-character .NET string ceiling, not RAM). Message: 'this read (N records) is too large to return as one document; use --limit/--offset or --out', N the parsed record_count
service_unavailable ServiceUnavailableError never raised by this verb

Caveats

  • intensity 0 is NOT a measured zero: FlashLFQ writes a literal 0 for a peptide it did not quantify in a sample, and mzLib keeps it (QuantifiedPeptideFromTsv.cs:14). Filter on detection_type before a mean or a log.
  • retention_time is IsoTracker output only (QuantifiedPeptideFromTsv.cs:61); plain FlashLFQ and MetaMorpheus tables name it in absent_fields, and peak_order likewise.
  • Long format: offset and limit count PEPTIDES, and returned_count counts rows.
  • Many files: --paths-stdin reads the list in ONE process, --threads at a time, into one long table with source_index and source_path first. The output does not depend on --threads (a tested property); the default of 1 is a memory choice, since every reader materialises the whole file.

Example

result = pymzlib.readers.read_quantified_peptides('MetaMorpheus_1.1.11_AllQuantifiedPeptides.tsv', limit=1)

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

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.readers.read_quantified_peptides mzlib::readers::read_quantified_peptides_with with ReadOptions readers_read_quantified_peptides

References

None: no publication is attached to this verb.

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.2.0 0.1.0 0.1.0

Not yet verified

  • quant median-polish still parses QuantifiedPeptides.tsv with a private reader (Quantification.cs); switching it to mzLib's QuantifiedPeptideFile is out of this verb's scope.
  • No IsoTracker fixture exists, so retention_time and peak_order have only been seen absent.
  • PYB-3 part 2: refusing a too-large answer BEFORE serialising, when the parsed record count already predicts it, is not built. It needs a characters-per-record threshold measured per format (dataRepo's ~805 per record is one file type); part 1 catches the failure after serialising.

read_occupancy

Read the PTM site occupancy of a MetaMorpheus AllQuantifiedProteinGroups.tsv as one row per group, sample group, basis and modified site.

Wire verb readers read-occupancy · Python pymzlib.readers.read_occupancy

Wraps

Parameters

Parameter Type Default Unit Range Meaning
path path required — — A MetaMorpheus protein-group table (any name readers read-protein-groups accepts), including an RNA search's AllQuantifiedTranscriptGroups.tsv (mzLib 1.0.593, #1388), whose occupancy cells name RNA modifications.
offset int 0 groups >= 0 Skip this many protein groups (a group with no modified sites gives no rows). A window, not a cursor: mzLib parses the whole file on every call, so paging re-reads it.
limit int absent groups >= 0 Return at most this many protein groups (a group with no modified sites gives no rows). Absent means no limit; there is deliberately no default cap.
out path absent — .tsv only, any case (PYB-1) Write the table to this path as tab-separated text instead of returning columns. Must differ from path. Parent directories are created. Must end in .tsv, any case (PYB-1); any other extension, or none, is a usage error before any input is read, and no extension is appended.

Returns

Top-level fields:

Field Type Unit Null? Meaning
path string — never Absolute path of the input.
file_type string — never The mzLib SupportedFileType that was dispatched.
reader string — never The mzLib reader class that parsed the file.
sample_labels string[] — never The file's sample-group labels in header order.
truncated_cell_count int cells never Occupancy cells the writer cut short or replaced with 'Output too long for Excel', including those left with no complete site (which give no rows).
record_count int groups never Groups in the whole file, before the window.
rows_not_read int rows yes: not counted for this table Data rows that did not become records.
retention_time_unit string — yes: the table has no time column Always null for this table.
caveats string[] — never What this view cannot be trusted to mean for THIS file, each citing the mzLib source.
column_names string[] — never Column order.
absent_fields string[] — never Columns the view defines that this file's format has no column or source for; null in every row (BULK.md section 4). Empty when every column has a source.
failed_fields string[] — never 'field: ExceptionType' for each column whose read threw on some returned rows; those cells are null.
excluded_fields object[] — never {field, type, reason, verb} for each field with no column shape; verb names the command that carries it, or null.
error object — yes: always, for a single path: a file that cannot be read fails the call instead {kind, type, message}; non-null only in a files[] entry under on-error skip.
returned_count int groups never Groups returned in columns (the unit offset and limit count in); 0 when written to out.
row_count int rows never Rows in columns: more than returned_count in a long table, where one record gives several rows; 0 when written to out.
offset int groups never The offset applied, in groups.
truncated bool — never True whenever records were left out by offset or limit.
columns table — yes: the table was written to out instead Column name to per-row values, in column_names order.
output object — yes: out was not given {path, format: "tsv", row_count} when out was given.

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 row's input in the stdin list. Present only with --paths-stdin.
source_path string — never Absolute path of the row's input. Present only with --paths-stdin.
protein_group_name string — never The group, as in read-protein-groups.
sample_label string — never The sample group whose cell this site came from.
basis string — never count (CountOccupancy_ cell, from PSM counts) or intensity (IntensityOccupancy_ cell).
entity_index int — never 0-based index among the cell's entities THAT HAVE SITES; not zippable with the group's accessions.
position int — never Position as written: 0 is the N-terminus, residues count from 1, length + 1 is the C-terminus (OccupancySite.Position).
is_n_terminus bool — never position == 0.
modification string — never ModificationIdWithMotif, e.g. 'Oxidation on M'; may contain commas and brackets.
fraction float fraction (0 to 1) never The fraction as printed: two decimals for count cells, four for intensity cells.
numerator float PSMs (basis count) or intensity (basis intensity) never Modified count, or modified intensity to four significant digits.
denominator float PSMs (basis count) or intensity (basis intensity) never Total count, or total intensity to four significant digits.
cell_is_truncated bool — never The cell this site came from was cut short; its complete sites are still rows.

Errors

Kind pyMzLib raises When
usage UsageError path missing or blank; file or directory not found; mzLib does not recognise the file type (the message points at readers formats)
usage UsageError offset, limit or out given with no value; offset or limit < 0; non-integer value; out resolves to the same file as path
usage UsageError the file is not a MetaMorpheus protein-group table
correctness BridgeError mzLib cannot parse the table (MzLibException). A single malformed cell does NOT fail the read: it is named in failed_fields and gives no rows
usage UsageError paths-stdin with path, offset or limit; paths-stdin with a value; no paths on stdin; a repeated path; threads 0 or below -1; on-error not fail or skip; on-error skip with a single path; out naming an input
usage UsageError with on-error fail, an input that is missing or not this view: the usage error of that input, prefixed 'Input ()'
correctness BridgeError with on-error fail, mzLib failing to parse an input: that input's own error type, message prefixed 'Input ()'
usage UsageError out (with path or paths-stdin) whose extension is not .tsv, any case, including none (PYB-1); checked before any input is opened
usage UsageError the answer is too large to return as one JSON document (PYB-3 part 1; measured: past the ~1.07 G-character .NET string ceiling, not RAM). Message: 'this read (N records) is too large to return as one document; use --limit/--offset or --out', N the parsed record_count
service_unavailable ServiceUnavailableError never raised by this verb

Caveats

  • Trust numerator/denominator on basis count rows and fraction on basis intensity rows: each cell rounds the other (ModificationOccupancyCell).
  • entity_index cannot be zipped with protein_group_name's accessions: an entity with no sites is dropped from the cell.
  • A malformed cell is refused by mzLib (FormatException), named in failed_fields as count_occupancy or intensity_occupancy, and gives no rows.
  • A truncated cell keeps its complete sites with cell_is_truncated true; truncated_cell_count counts every cut cell, including those with no rows.
  • offset and limit count GROUPS; a group with no modified sites gives no rows.
  • Many files: --paths-stdin reads the list in ONE process, --threads at a time, into one long table with source_index and source_path first. The output does not depend on --threads (a tested property); the default of 1 is a memory choice, since every reader materialises the whole file.

Example

result = pymzlib.readers.read_occupancy('MetaMorpheus_1.1.11_AllQuantifiedProteinGroups.tsv')

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

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.readers.read_occupancy mzlib::readers::read_occupancy_with with ReadOptions readers_read_occupancy

References

None: no publication is attached to this verb.

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.2.0 0.1.0 0.1.0

Not yet verified

  • Peptide-level occupancy: ModificationOccupancyCell also parses peptide tables' cells, but QuantifiedPeptideFromTsv at the pin exposes none, so this verb reads protein groups only.
  • numerator and denominator are floats for both bases; a count-basis value crosses as a whole number (1, not 1.0) and bindings must read it as a float.
  • PYB-3 part 2: refusing a too-large answer BEFORE serialising, when the parsed record count already predicts it, is not built. It needs a characters-per-record threshold measured per format (dataRepo's ~805 per record is one file type); part 1 catches the failure after serialising.