Skip to content

peptidoform: 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 worked examples, see the Peptidoforms guide.

Python groups five census fields into one object. annotated_modification_sites, annotated_modifications_loaded, uniprot_annotated_features, unresolved_modifications and uniprot_features_by_type arrive as Digest.modification_census (sites, applied, annotated, unresolved, by_type), which can also explain() itself in a sentence. The wire's no-modifications flag is modifications=False, and max-mods is max_modifications=.

fragments

Fetch a UniProt entry with its annotated modifications, digest it, and return every peptidoform with its fragment ions, plus a census of which annotations were applied.

Wire verb peptidoform fragments · Python pymzlib.peptidoform.fragments

Wraps

Parameters

Parameter Type Default Unit Range Meaning
accession string required — — A UniProtKB accession, e.g. P02768; fetched from rest.uniprot.org. The bridge checks only that it is not blank (the bindings upper-case it and check its shape first). UniProt's 400 or 404 becomes a usage error.
protease string trypsin\|P — a key of mzLib's ProteaseDictionary mzLib protease name. The default "trypsin|P" is the Keil rule (cleave after K/R EXCEPT before P); mzLib's plain "trypsin" cleaves before P too. The bracket/bar marks a PREVENTING residue, the reverse of MaxQuant's and Mascot's "Trypsin/P".
dissociation string ETD — a mzLib DissociationType name, case-insensitive: HCD, CID, ETD, EThcD, ... Which fragment series to generate: HCD/CID give b and y; ETD gives c and zDot.
terminus string Both — a mzLib FragmentationTerminus name, case-insensitive: Both, N, C Which fragment termini to generate; also passed to DigestionParams.
no_modifications (wire --no-modifications) flag false — — Digest the bare sequence: UniProt's modifications are discarded but its signal-peptide and propeptide boundaries are kept (pyMzLib#8), so the backbone peptide list is unchanged and only the modified variants go away. A clean control.
missed_cleavages (wire --missed-cleavages) int 2 cleavage sites >= 0 Maximum missed cleavage sites per peptide.
min_length (wire --min-length) int 7 residues >= 1 Shortest peptide kept. The default silently drops shorter peptides (about a third of a histone digest); pass 1 for every peptide.
max_length (wire --max-length) int 0 residues >= 0 Longest peptide kept; 0 means unbounded.
max_mods (wire --max-mods) int 2 modifications >= 0 Maximum modifications per peptidoform (DigestionParams maxModsForPeptides). Isoforms grow combinatorially: histone H3.1 gives 49 bare tryptic peptides, 2,563 at 2 and 7,040 at 3.
max_isoforms (wire --max-isoforms) int 1024 peptidoforms >= 1 Cap on modification isoforms per peptide position (DigestionParams maxModificationIsoforms). mzLib truncates SILENTLY at the cap; peptides_at_isoform_cap reports it.

Returns

Top-level fields:

Field Type Unit Null? Meaning
accession string — never The accession UniProt returned.
name string — yes: the entry records no entry name UniProt entry name, e.g. ALBU_HUMAN.
full_name string — yes: the entry records no recommended name Recommended protein name, e.g. Albumin.
organism string — yes: the entry records no organism Scientific name.
sequence_length int residues never Length of the full precursor sequence.
modifications_applied bool — never False under no-modifications.
annotated_modification_sites int residues never Distinct residue positions carrying at least one loaded modification. Not a modification count: K9me1/me2/me3/ac are four modifications at one site.
annotated_modifications_loaded int modifications never Modifications mzLib loaded onto the protein (summed over sites). Counted from the annotated entry, so unchanged by no-modifications.
uniprot_annotated_features int features never Modification-like features in the XML: modified residue, glycosylation site, lipid moiety-binding region and cross-link.
unresolved_modifications string[] — never Modification names the entry annotates that could not be resolved against UniProt's ptmlist, sorted. These are dropped silently by mzLib otherwise.
uniprot_features_by_type object[] — never {type, count, loaded} per feature type, sorted by type. loaded is true only for 'modified residue' and 'lipid moiety-binding region': mzLib drops the others on feature TYPE alone, before any mass lookup.
protease string — never The protease used.
dissociation string — never DissociationType name used.
terminus string — never FragmentationTerminus name used.
max_modifications int modifications never max-mods, echoed.
max_modification_isoforms int peptidoforms never max-isoforms, echoed.
peptides_at_isoform_cap int peptide positions never Peptide positions (start, end) whose distinct peptidoforms reached max-isoforms. Non-zero means the list is TRUNCATED.
peptide_count int peptidoforms never Entries in peptides.
peptides object[] — never One entry per distinct peptidoform (start, end, full sequence), in digestion order; fields under result.columns.

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

Field Type Unit Null? Meaning
base_sequence string — never Bare residues.
full_sequence string — never mzLib full sequence with modifications inline, e.g. ...K[UniProt:N6-succinyllysine on K].
monoisotopic_mass float Da never Neutral monoisotopic mass, modifications included.
length int residues never Peptide length.
one_based_start int — never First residue's position in the protein, 1-based.
one_based_end int — never Last residue's position in the protein, 1-based, inclusive.
missed_cleavages int cleavage sites never Missed cleavage sites spanned.
modification_count int modifications never Entries in modifications.
fixed_charges int charge never Formal charges the INTACT peptide carries before protonation (e.g. trimethyllysine's quaternary ammonium), recovered from each modification's formula-vs-recorded mass deficit in whole electrons. m/z at charge z is (monoisotopic_mass + (z - fixed_charges) * 1.00727646677) / z. Does NOT apply to fragments.
modifications object[] — never {one_based_residue, terminus, id, mass, formal_charge} per modification: one_based_residue is 1-based within the PEPTIDE and null for a terminal modification, which sets terminus 'N' or 'C' instead (terminus is null for a residue modification); id is mzLib's IdWithMotif; mass is its monoisotopic mass in Da (null only if the modification defines none); formal_charge in elementary charges.
fragments object[] — never {product_type, fragment_number, neutral_mass, neutral_loss, residue_position} per ion: product_type e.g. b, y, c, zDot; fragment_number the position in its series; neutral_mass the monoisotopic NEUTRAL mass in Da (not an m/z; no proton added); neutral_loss in Da (0 when none); residue_position 1-based within the peptide.

Errors

Kind pyMzLib raises When
usage UsageError accession missing or blank; UniProt answers 400 or 404 (no such entry); the entry holds no protein sequence; protease not in ProteaseDictionary; dissociation or terminus not an enum name; an integer option that is not an integer
service_unavailable ServiceUnavailableError UniProt unreachable by the bridge's own classification: a timeout (HttpClient 100 s), a socket or TLS failure, a request that never got a response, an HTTP 408, 429 or 5xx, or a body cut off in transit
correctness BridgeError any other UniProt status (e.g. 403); UniProt's ptmlist.txt or PSI-MOD.obo.xml missing from the bridge payload (FileNotFoundException: every protein would otherwise look unmodified or carry wrong charges); mzLib failing to parse the entry or to digest it

Caveats

  • UniProt annotates more than mzLib applies: only 'modified residue' and 'lipid moiety-binding region' features load. Serum albumin: 14 of 38 annotated features applied, the 24 glycosylation-site features dropped on type (mzLib#1112). Read uniprot_features_by_type and unresolved_modifications before trusting a modification count.
  • max-isoforms truncates silently in mzLib (histone H3.1 at four modifications loses about 30% of peptidoforms at 1024). Check peptides_at_isoform_cap before treating the list as exhaustive.
  • Duplicate peptidoforms that mzLib's Digest emits where a chain boundary meets the initiator-Met cleavage site (mzLib#1108, open) are collapsed by the bridge on (start, end, full sequence).
  • Fragment masses are neutral. Converting one to m/z needs the fixed charge within that fragment's span, which the wire does not report; fixed_charges is whole-peptide only.
  • ETD's zDot ions are suppressed N-terminal to proline while the complementary c ions are not, leaving about 4% of the c series unobservable (mzLib#1110).
  • Needs the network: UniProt is queried on every call.

Example

digest = pymzlib.peptidoform.fragments('P02768', max_modifications=1)

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

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.peptidoform.fragments mzlib::peptidoform::fragments_with with FragmentOptions peptidoform_fragments

References

  • doi:10.1093/nar/gkae1010: UniProt, the source of the entry, its sequence and its annotated modifications (UniProt Consortium 2025, NAR)

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.1.0 0.1.0 0.1.0

Not yet verified

  • peptides_at_isoform_cap is computed on the DE-DUPLICATED list, although FragmentsAsync's own comment says it must count the raw digest (a truncated locus deduped below the cap then reads as untruncated); the correctly computed peptidesAtCap local is never used. Confirmed a bridge bug (pyMzLib 005), fixed on pyMzLib main by #67 (unreleased after 0.2.0): the wire then counts the raw digest, as the doc above says. Close this once a release carries #67.
  • The example fixture is hand-trimmed (2 peptides of a max-mods 1 digest), so its peptide_count is not what the live call returns; the envelope keys are the live ones.
  • Integer options are not range-checked by the bridge (negative min-length, max-isoforms 0); the bindings check them. Enum.TryParse also accepts numeric strings, so --dissociation 3 or --terminus 7 pass as undefined members. Behaviour of mzLib on such values is unverified.
  • The wire names max-mods and no-modifications project as max_modifications and modifications (inverted) in every binding; pyMzLib's spec lint will need PYTHON_DEVIATIONS entries for them.
  • modifications[].mass nullability: Modification.MonoisotopicMass is double?; a loaded UniProt modification has not been seen without one.

convert

convert reads no file and makes no network call. Python's source=, target= and mode= are the wire's --from, --to and --mode, and the sequences travel on stdin, one per line. Python always sends all three options, with the wire's own defaults. SequenceConversions.sequences and not_converted regroup the table's rows as ConvertedSequence objects, and outputs is the output column.

Convert full sequences from one notation to another with mzLib's sequence conversion service, one result per input: for example a MetaMorpheus full sequence to Unimod accessions.

Wire verb peptidoform convert · Python pymzlib.peptidoform.convert

Wraps

Parameters

Parameter Type Default Unit Range Meaning
from string mzLib — a registered source format: MassShift, Modomics, ProForma, mzLib (at 0a808fec) The notation the sequences are in, matched case-insensitively against the service's AvailableSourceFormats. Any other name, or the option without a value, is a usage error that lists the registered names.
to string Unimod — a registered target format: Chronologer, Essential, MassShift, ProForma, Unimod, mzLib (at 0a808fec) The notation to write, matched case-insensitively against the service's AvailableTargetFormats. Any other name, or the option without a value, is a usage error that lists the registered names.
mode string ReturnNull — ThrowException \| ReturnNull \| RemoveIncompatibleElements \| UsePrimarySequence mzLib's SequenceConversionHandlingMode, by name, case-insensitive. ReturnNull: an input mzLib cannot convert is a failed row. RemoveIncompatibleElements and UsePrimarySequence: what the target cannot write is dropped and the row is converted_with_warnings. ThrowException: the first input mzLib cannot convert (in input order) fails the whole call as a usage error naming it. A number or any other name is a usage error.
threads int 1 — >= 1, or -1 for every core Sequences converted at once. Rows are identical, in input order, at any value.
sequences string[] required — non-empty Read from stdin (not an option): one full sequence per line, given to mzLib exactly as read. Blank lines are skipped. One row per line, in order, duplicates included. No sequences is a usage error.

Returns

Top-level fields:

Field Type Unit Null? Meaning
source_format string — never --from, spelled as mzLib registered it.
target_format string — never --to, spelled as mzLib registered it.
mode string — never The SequenceConversionHandlingMode used.
source_formats string[] — never Every source format the service has registered, ordinal order.
target_formats string[] — never Every target format the service has registered, ordinal order.
record_count int sequences never Rows: the input sequences.
converted_count int sequences never Rows with status converted.
warned_count int sequences never Rows with status converted_with_warnings.
failed_count int sequences never Rows with status failed.
column_names string[] — never The table's columns in order.
columns table — never Column name to one value per input, in input order.
caveats string[] — never Six static caveats.

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

Field Type Unit Null? Meaning
input string — never The line exactly as read from stdin.
output string — yes: mzLib returned no output for this input (status failed) mzLib's converted sequence.
status string — never converted (an output and ConversionWarnings.IsClean) | converted_with_warnings (an output, but mzLib recorded a warning, error or incompatible item) | failed (no output).
failure_reason string — yes: mzLib recorded no ConversionFailureReason: always for converted rows, and for a row the Unimod target fails under ReturnNull mzLib's ConversionFailureReason: InvalidSequence | IncompatibleModifications | UnsupportedDirection | UnknownFormat.
incompatible_items string[] — never ConversionWarnings.IncompatibleItems: what the target could not write, as mzLib describes it ('Made Up:Not a modification on K @3(K)'). Empty when none.
warnings string[] — never ConversionWarnings.Warnings: mzLib's non-fatal messages for this input.
errors string[] — never ConversionWarnings.Errors: mzLib's error messages for this input.

Errors

Kind pyMzLib raises When
usage UsageError no sequences on stdin; --from or --to not a registered format, or given without a value (the message lists the registered names); --mode not a SequenceConversionHandlingMode name; --threads 0 or below -1
usage UsageError --mode ThrowException and mzLib could not convert an input (the first in input order; the message names it and mzLib's reason)
correctness BridgeError mzLib threw something other than its SequenceConversionException (never seen at 0a808fec)
service_unavailable ServiceUnavailableError never raised by this verb

Caveats

  • ProForma does not resolve UniProt-sourced modifications at 0a808fec: '[UniProt:N-acetylserine on S]SEQK' comes out as '[UniProt:N-acetylserine on S]-SEQK', status converted, not '[UNIMOD:1]-SEQK'. mzLib's ProForma serializer looks modifications up in the MetaMorpheus list only (ProFormaSequenceSerializer.cs:34, MzLibModificationLookup.cs:54); the Unimod target looks them up in every list mzLib loads, UniProt's included (GlobalModificationLookup.cs:23). Convert to Unimod when the sequences carry UniProt modifications. mzLib#1401.
  • ProForma writes a modification it cannot resolve under its mzLib name and the row is still converted, so status converted does not mean every bracket in a ProForma output is a controlled-vocabulary term. Unimod either names a modification by its UNIMOD accession or reports it in incompatible_items.
  • A modification the target cannot write: under ReturnNull the row fails (output null); under RemoveIncompatibleElements and UsePrimarySequence it is dropped from output, named in incompatible_items, and the row is converted_with_warnings; under ThrowException the first such input fails the whole call as a usage error.
  • status is mzLib's verdict read off ConversionWarnings; failure_reason can be null on a failed row (the Unimod target under ReturnNull records only incompatible_items).
  • An ambiguous MetaMorpheus full sequence ('|'-joined candidates) is not refused: mzLib's parser skips each '|' with a warning and joins the candidates into one sequence, status converted_with_warnings. Split ambiguous full sequences before converting them.
  • Each stdin line is one input, given to mzLib exactly as read; blank lines are skipped; rows are in input order at any --threads.

Example

result = pymzlib.peptidoform.convert(['[UniProt:N-acetylserine on S]SEQK', 'PEPK[UniProt:N6,N6-dimethyllysine on K]R', 'PEPM[Common Variable:Oxidation on M]K', 'PEPK[Made Up:Not a modification on K]R'])

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

unimod = pymzlib.peptidoform.convert(psms.columns['full_sequence'])

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

proforma = pymzlib.peptidoform.convert(psms.columns['full_sequence'], target='ProForma')

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

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.peptidoform.convert mzlib::peptidoform::convert_with with ConvertOptions peptidoform_convert

References

Since

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

Not yet verified

  • The ProForma target's UniProt gap is an mzLib defect (the serializer's default lookup), mzLib#1401; close this when a pin carries its fix. A bridge-side substitute (ProFormaSequenceSerializer.WithLookup(GlobalModificationLookup)) composes serializer internals and is deliberately not used.
  • mzLib's MzLibSequenceParser joins '|'-separated ambiguous candidates into one sequence with only a warning; whether it should refuse them (as SpectrumMatchFromTsv.ProFormaFromFullSequence does before calling it) is an mzLib question: mzLib#1405.
  • AutoDetect (SequenceConversionService.ConvertAutoDetect) is not projected: --from is always explicit.
  • Ported, unreleased: mzLibRust #32 and mzLibR #32 (drafts until pyMzLib 0.4.0 publishes the bridge). Set since.mzlibrust / since.mzlibr when they release.