Skip to content

pride: wire verbs

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

Python returns the rows, not the envelope. list_files(), list_ftp_files(), search() and download() each return a list: of files, of hits, of written paths. The wire's count fields are that list's len(), and its size totals are total_size_bytes(files) and approximate_total_size_bytes(files). Python also spells three download options differently: destination= for dest, extensions= (a list) for ext, and overwrite=False for no-overwrite. Selecting exact files by name is its own function, download_files().

list_files

List a PRIDE Archive project's files as PRIDE's REST API publishes them, with every page already fetched: name, size, checksum, category and download locations.

Wire verb pride files · Python pymzlib.pride.list_files

Wraps

Parameters

Parameter Type Default Unit Range Meaning
accession string required — — The project accession, e.g. PXD000001. Sent to PRIDE as given: the bridge checks only that it is not blank (the bindings upper-case it and check its shape first, because PRIDE is case-sensitive).
page_size (wire --page-size) int 100 files >= 1 Files requested per underlying API call. Changes how many requests the fetch takes, never what comes back: mzLib pages until the manifest is complete. Leave it at the default; above PRIDE's server-side cap the manifest is complete only while PRIDE reports total_records.

Returns

Top-level fields:

Field Type Unit Null? Meaning
accession string — never The accession, echoed as given.
file_count int files never Entries in files. 0 for an unknown or private accession: PRIDE answers both with an empty manifest, not an error.
total_size_bytes int bytes never Sum of file_size_bytes over files (mzLib TotalSizeBytes). A sum of PRIDE-reported sizes over an incomplete manifest; see caveats.
files object[] — never One entry per file in repository order; fields under result.columns.

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

Field Type Unit Null? Meaning
file_name string — never The file's name as PRIDE lists it, e.g. TMT_Erwinia_1uLSike_Top10HCD_isol2_45stepped_60min_01.raw.
file_size_bytes int bytes never Size as PRIDE reports it. For compressed files PRIDE often reports the DECOMPRESSED size (PXD000001's .mgf.gz: 16448103 reported vs 5984662 transferred).
checksum string — never The repository's checksum; the empty string when PRIDE provides none (never null).
category string — never PRIDE file category value, e.g. RAW, PEAK, SEARCH, RESULT, OTHER.
category_accession string — never The category's PRIDE CV accession, e.g. PRIDE:0000410.
https_url string — yes: the file has no location reachable over HTTPS (for example Aspera-only); pride download cannot fetch it Direct HTTPS URL: the FTP location scheme-upgraded to HTTPS on PRIDE's FTP host.
locations object[] — never Every published location as {accession, name, value} CV terms, e.g. {PRIDE:0000469, FTP Protocol, ftp://...}. May be empty.
submission_date string — never ISO-8601 timestamp with offset (DateTimeOffset), e.g. 2012-03-13T00:00:00+00:00. Never null: a date PRIDE omitted arrives as 0001-01-01T00:00:00+00:00.
publication_date string — never As submission_date.
updated_date string — never As submission_date.

Errors

Kind pyMzLib raises When
usage UsageError accession missing or blank; page-size not an integer
service_unavailable ServiceUnavailableError the bridge's own classification (Program.ClassifyError; since mzLib 1.0.593 (#1350) PRIDE raises every transport failure as an HttpRequestException carrying the cause or the status, and messages name the file and host, never the URL): a timeout or cancellation, a socket failure, an HttpRequestException with no status but an inner cause (refused connection, DNS, TLS), an HTTP 408, 429 or 5xx, or a response body cut off in transit
correctness BridgeError any other HTTP status (e.g. 404), a paging contract violation (MzLibException: an identical page while total_records says more remain), the MaxPages backstop (an HttpRequestException mzLib composes with no status and no inner exception, which ClassifyHttpFailure deliberately does not excuse as an outage), or page-size <= 0 (mzLib's ArgumentOutOfRangeException; the bridge does not check it first)

Caveats

  • This is PRIDE's REST manifest, which is knowingly incomplete: for PXD000001 it lists 8 files while the FTP tree holds 13, omitting the two largest. Use pride ftp-files when completeness or the true project size matters.
  • An unknown accession and a private project both return file_count 0, not an error. The bindings raise their not-found error on an empty manifest; the wire does not.
  • total_size_bytes is not the number of bytes a download transfers: PRIDE reports some compressed files at their decompressed size, and the sum covers only the files the manifest lists. The two errors run in opposite directions and do not cancel.
  • Dates are timestamps with an offset here, unlike pride search, whose dates are bare calendar dates.

Example

files = pymzlib.pride.list_files('PXD000001')

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

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.pride.list_files mzlib::pride::list_files_with with ListOptions pride_list_files

References

  • doi:10.1093/nar/gkae1011: The PRIDE Archive, the repository this verb lists (Perez-Riverol et al., The PRIDE database at 20 years: 2025 update, NAR)

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.1.0 0.1.0 0.1.0

Not yet verified

  • page-size <= 0 crosses as a correctness failure (ArgumentOutOfRangeException) because the bridge, unlike pride search, does not check it before calling mzLib. Every binding rejects it first, so no binding user sees it; the wire should say usage.
  • An absent PRIDE date crosses as 0001-01-01T00:00:00+00:00, not null (PrideArchiveFile's dates are non-nullable DateTimeOffset, and ToWireFile does not map default to null as pride search's ToWireDate does). Not observed on a real manifest; unverified whether PRIDE ever omits one.
  • An option given with no value (e.g. --page-size followed by another option) is parsed as a flag and silently defaulted: OptionalInt does not consult WasProvided.

list_ftp_files

List every file a PRIDE project holds by walking its FTP directory tree, subdirectories included, with approximate sizes.

Wire verb pride ftp-files · Python pymzlib.pride.list_ftp_files

Wraps

Parameters

Parameter Type Default Unit Range Meaning
accession string required — — The project accession, e.g. PXD000001. The bridge checks only that it is not blank. mzLib resolves the project first (for its publication date, which locates the FTP directory), so an unknown accession fails instead of listing nothing.

Returns

Top-level fields:

Field Type Unit Null? Meaning
accession string — never The accession, echoed as given.
file_count int files never Entries in files. 0 only if the resolved project's directory listed nothing (the bindings raise their not-found error on it).
approximate_total_size_bytes int bytes never Sum of approximate_size_bytes (mzLib TotalApproximateSizeBytes): an estimate over the COMPLETE file list. PXD000001 comes to about 1.44 GB.
files object[] — never One entry per file in walk order (each directory's autoindex order, depth first); fields under result.columns.

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

Field Type Unit Null? Meaning
relative_path string — never Path from the project's FTP root, '/'-separated and URL-decoded, e.g. generated/summary.mztab for a file in a subdirectory.
file_name string — never The last segment of relative_path.
url string — never HTTPS URL on ftp.pride.ebi.ac.uk that the file can be fetched from with any HTTP client.
approximate_size_bytes int bytes never PRIDE's autoindex size (e.g. '429M'), expanded with 1024-based multipliers and so rounded to about three significant figures. 0 when the index showed '-' or an unparseable size: 0 means unknown, not empty. For the exact size, HTTP HEAD the url and read Content-Length.

Errors

Kind pyMzLib raises When
usage UsageError accession missing or blank
service_unavailable ServiceUnavailableError the bridge's own classification (Program.ClassifyError; since mzLib 1.0.593 (#1350) PRIDE raises every transport failure as an HttpRequestException carrying the cause or the status, and messages name the file and host, never the URL): a timeout or cancellation, a socket failure, a request that never got a response (refused connection, DNS, TLS), an HTTP 408, 429 or 5xx on the project lookup or on any directory listing, or a body cut off in transit
correctness BridgeError no project has that accession, or it has no publication date to locate its directory (MzLibException; the bindings re-map it to their not-found error); a directory listing answering any other status; nesting deeper than 64 levels (MzLibException: the listing may be cyclic)

Caveats

  • This is the complete file list; pride files (PRIDE's REST manifest) omits files, for PXD000001 five of 13 including the two largest. The price is metadata: no category, checksum or CV locations here.
  • Sizes are approximate (rounded autoindex values), so approximate_total_size_bytes is an estimate, but an estimate over every file, unlike pride files' total_size_bytes.
  • A listing surface only: pride download selects from the REST manifest, so a file that appears only here cannot be fetched by pride download. Fetch it from its url with an ordinary HTTPS client.
  • One HTTP request per directory: the walk's cost grows with the tree, not the file count.

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.pride.list_ftp_files mzlib::pride::list_ftp_files_with pride_list_ftp_files

References

  • doi:10.1093/nar/gkae1011: The PRIDE Archive and its FTP layout (Perez-Riverol et al., The PRIDE database at 20 years: 2025 update, NAR)

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.1.0 0.1.0 0.1.0

Not yet verified

  • No recorded fixture: the verb needs a pride_PXD000001_ftp_files.json recording (live, 13 files) before it can have a checked example, and before the bindings' doctests can drop +SKIP.
  • An unknown accession crosses as correctness (MzLibException), not usage, although it is the caller's mistake. Every binding re-maps it to its not-found error; the wire itself does not say 'not found'.
  • Directory order is whatever PRIDE's Apache autoindex serves; not verified to be stable across requests, so files order is not promised.
  • mzlib::pride::list_ftp_files_with takes the timeout as its second argument rather than an options struct; no Rust options type exists for this verb.

Find PRIDE Archive projects by keyword, with every page fetched and no accession repeated: the discovery step that produces the accessions every other pride verb takes.

Wire verb pride search · Python pymzlib.pride.search

Wraps

Parameters

Parameter Type Default Unit Range Meaning
keyword string required — 1 to 1000 characters What to search for, matched by PRIDE across titles, descriptions, keywords, organisms, references and more. Longer than 1000 characters (mzLib MaxKeywordLength) is a usage error, because PRIDE answers one with HTTP 500, which cannot be told apart from an outage.
page_size (wire --page-size) int 100 projects >= 1 Hits requested per underlying API call. Changes how many requests the fetch takes, never what comes back.

Returns

Top-level fields:

Field Type Unit Null? Meaning
keyword string — never The keyword, echoed.
result_count int projects never Entries in results. 0 is a real answer (no hits), not an error.
results object[] — never One entry per matching project, deduplicated by accession, in PRIDE's ranking order; fields under result.columns.

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

Field Type Unit Null? Meaning
accession string — never The project accession: usually PXD, but also legacy PRD and affinity PAD. Treat it as an opaque key.
title string — never Project title.
project_description string — never Submitter's free-text description.
sample_processing_protocol string — never Free text.
data_processing_protocol string — never Free text.
doi string — never Dataset DOI, or "" when PRIDE has minted none.
submission_type string — never COMPLETE, PARTIAL, AFFINITY or PRIDE (legacy); not a closed set.
sdrf string — never The project's SDRF term VALUES flattened by the search index into one space-joined string. Not a file, name or URL; "" on most hits.
submission_date string — yes: PRIDE reported no date (mzLib's default DateTime) Bare calendar date yyyy-MM-dd: no time, no offset, because none was sent.
publication_date string — yes: PRIDE reported no date As submission_date.
updated_date string — yes: PRIDE reported no date As submission_date.
project_tags string[] — never PRIDE's coarse classification tags. Sparse (2.6% of 1,600 sampled hits).
keywords string[] — never Submitter keywords. May contain empty or whitespace-only strings (about 9% of hits); passed through, not filtered.
submitters string[] — never Display names, flattened from contact objects.
lab_pis string[] — never Display names.
affiliations string[] — never Display strings.
instruments string[] — never Display names only; the CV accessions are not sent by this endpoint.
softwares string[] — never Display names.
quantification_methods string[] — never Display names, e.g. TMT.
sample_attributes string[] — never Sample characteristic VALUES; which characteristic each describes is not recoverable from a hit.
organisms string[] — never Display names, e.g. 'Homo sapiens (human)'.
organism_parts string[] — never Display names.
diseases string[] — never Display names.
references string[] — never Each a pre-formatted citation string; no separate PubMed id or DOI.
experiment_types string[] — never e.g. Data-independent acquisition.
project_file_names string[] — never File names only: not the manifest (no sizes, categories or locations). Use pride files or pride ftp-files to act on files.
other_omics_links string[] — never Links to related datasets in other omics repositories.
highlights map<string,string[]> — never Why the project matched: PRIDE field name -> matched snippets with the terms wrapped in . Keys vary per hit and per query and cross unchanged (not snake_cased).
yearly_downloads object[] — never {year, count}: year a string (e.g. "2025"), count downloads in that year. Empty when not reported.
download_count int downloads never Total downloads. 0 means not reported, never a measured zero.
avg_downloads_per_file float downloads per file never Mean downloads per file. 0 means not reported.
percentile int percentile never Download-popularity percentile within PRIDE. 0 means not reported.
bot_count int downloads never Downloads attributed to crawlers. 0 means not reported (populated on under half of hits).
hub_count int downloads never Downloads attributed to institutional or aggregating hubs. 0 means not reported.
organic_count int downloads never Downloads attributed to ordinary human traffic. 0 means not reported.

Errors

Kind pyMzLib raises When
usage UsageError keyword missing or blank; keyword longer than 1000 characters; page-size not an integer or <= 0 (both checked by the bridge before mzLib)
service_unavailable ServiceUnavailableError the bridge's own classification (Program.ClassifyError; since mzLib 1.0.593 (#1350) PRIDE raises every transport failure as an HttpRequestException carrying the cause or the status, and messages name the file and host, never the URL): a timeout or cancellation, a socket failure, a request that never got a response (refused connection, DNS, TLS), an HTTP 408, 429 or 5xx, or a body cut off in transit
correctness BridgeError any other HTTP status; a paging contract violation (MzLibException: an identical page while total_records says more remain); the page limit (mzLib MaxPages) exceeded

Caveats

  • A hit is NOT a project's metadata: PRIDE serves search from an Elasticsearch projection in which every controlled-vocabulary field is flattened to a display string, contacts to names and references to citation strings. Follow the accession for the vocabulary.
  • A zero or an empty list means 'not reported', never a measured zero. Several fields are genuinely sparse (sampled over 1,600 hits: project_tags 2.6%, sdrf 2.4%, other_omics_links 18%, the bot/hub/organic trio under half).
  • Dates are bare calendar dates, unlike pride files' timestamps with offsets; a binding must not widen them to a midnight timestamp.
  • PRIDE pages a live index with no stable cursor: a project published mid-fetch is deduplicated, but one removed mid-fetch can fall between two pages and be missed. A result set that fits on one page cannot be affected.

Example

hits = pymzlib.pride.search('plasmodium falciparum schizont')

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

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.pride.search mzlib::pride::search_with with SearchOptions pride_search

References

  • doi:10.1093/nar/gkae1011: The PRIDE Archive and its search service (Perez-Riverol et al., The PRIDE database at 20 years: 2025 update, NAR)

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.1.0 0.1.0 0.1.0

Not yet verified

  • Shape difference: mzlib::pride::search / search_with return Vec and R pride_search() returns the hits data.frame, so neither carries the envelope's keyword or result_count (the caller has the keyword; the count is len() / nrow()). pyMzLib returns the hits list likewise. Declare it as a deviation or drop the two fields from the wire?
  • The bindings also refuse a keyword beginning with '-' (it would be parsed as an option); the bridge cannot, since a value starting with '--' reaches it as a flag and the keyword then reads as missing.
  • The ranking order of results is PRIDE's and is not promised stable across calls.

download and download_files

Download a PRIDE project's files, all of them or a selection, into a directory and report the paths written.

Wire verb pride download · Python pymzlib.pride.download

Wraps

Parameters

Parameter Type Default Unit Range Meaning
accession string required — — The project accession, e.g. PXD000001. The bridge checks only that it is not blank.
dest path required — — Directory to write into; created if absent, but only when a file is actually fetched (mzLib creates it after the no-overwrite skip). With zero matches, or every file skipped, no directory is created, yet destination_directory is still reported. Blank is a usage error (it never falls back to the working directory).
category string absent — a PRIDE category value, case-insensitive: RAW, PEAK, SEARCH, RESULT, OTHER, ... Keep only files of this category (mzLib WhereCategory). Absent keeps every category. Given but blank is a usage error, never 'everything'. ANDed with ext.
ext string[] absent — comma-separated; a leading dot is optional Keep only files whose name ends with one of these extensions, case-insensitive (mzLib WhereExtension), e.g. ".raw,.mzML". Absent keeps every type. Given but naming no extension (blank or only commas) is a usage error. A compressed file's extension is .gz.
no_overwrite (wire --no-overwrite) flag false — — Leave a file already present at the destination untouched and make no request for it: a cheap resume. Absent, an existing file is replaced.
names_from_stdin (wire --names-from-stdin) flag false — — Select exact files instead of filtering: stdin carries file names, one per line (newline-delimited; blank lines ignored; each line trimmed; exact, case-sensitive match against the manifest's file_name). Exclusive with category and ext. Stdin rather than argv because argv caps near 32 KB and any other separator could occur in a file name. A name containing a line break cannot be selected (the bindings refuse one; PRIDE has never published one).
stdin string[] absent — >= 1 non-blank line when names-from-stdin is given Read only with names-from-stdin: the file names to fetch, one per line. Every name must be in the project's REST manifest (pride files). A UTF-8 BOM on the first line is stripped (ReadStdinLines) from pyMzLib #67 on; the 0.2.0 bridge keeps it, so that first name fails as not in the project.

Returns

Top-level fields:

Field Type Unit Null? Meaning
accession string — never The accession, echoed as given.
destination_directory string — never dest, made absolute.
downloaded_count int files never Entries in paths: files written PLUS, under no-overwrite, files already present and skipped.
paths string[] — never One path per selected file, in manifest order: mzLib's Path.Combine(dest as given, file_name), so relative when dest was relative (resolve against destination_directory's parent, not this list).

Errors

Kind pyMzLib raises When
usage UsageError accession or dest missing or blank; category given but blank; ext given but naming no extension; names-from-stdin together with category or ext; names-from-stdin with no non-blank line on stdin
usage UsageError names-from-stdin naming a file the project's manifest does not contain (the message lists up to five). Raised AFTER the matching files have been downloaded: they are on disk when the error arrives.
service_unavailable ServiceUnavailableError the bridge's own classification (Program.ClassifyError; since mzLib 1.0.593 (#1350) PRIDE raises every transport failure as an HttpRequestException carrying the cause or the status, and messages name the file and host, never the URL): a timeout, a socket or TLS failure, an HTTP 408, 429 or 5xx on the manifest or a file, a body that delivered nothing for mzLib's BodyStallTimeout (2 min), or a body cut off in transit
correctness BridgeError a selected file has no HTTPS location (NotSupportedException; Aspera-only); a manifest file name that is not a bare leaf name (ArgumentException: refusing to write outside dest); any other HTTP status; a local disk failure while writing (a bare IOException, e.g. a full disk, is deliberately NOT treated as an outage)

Caveats

  • Selects from PRIDE's REST manifest (pride files), which omits some files; a file listed only by pride ftp-files cannot be downloaded by this verb.
  • Files are fetched one at a time, in manifest order. Each streams to '.partial' and is moved into place only when complete, so an interrupted transfer never leaves a truncated file; files finished before a failure stay on disk.
  • A filter that matches nothing, or an unknown accession, succeeds with downloaded_count 0 on the wire. The bindings raise a usage error when a category or ext filter matched nothing.
  • Downloads can be very large (PXD000001's single .raw is about 220 MB); list first and filter or select.

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.pride.download mzlib::pride::download with DownloadOptions pride_download

References

  • doi:10.1093/nar/gkae1011: The PRIDE Archive, the repository files are fetched from (Perez-Riverol et al., The PRIDE database at 20 years: 2025 update, NAR)

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.1.0 0.1.0 0.1.0

Not yet verified

  • No recorded fixture, so no checked example: a replay needs a stub bridge that also fakes the written files. The envelope keys above are from ToWire in PrideDownloadAsync, not from a recording.
  • The unmatched-selection check runs after the download, so a typo in one name still downloads every other selected file before failing. Checking the manifest first would need the bridge to fetch it separately from DownloadProjectFilesAsync.
  • downloaded_count counts skipped files under no-overwrite; the wire has no separate skipped count.
  • 'selection' under bindings names the names-from-stdin projection (download_files in every binding); tools/check_verbs.py does not read it.
  • A zero-match filter is a usage error in the bindings but a success on the wire; whether the wire should raise it (as it does for an unmatched names-from-stdin selection) is undecided.
  • Wire params dest, ext, no-overwrite, names-from-stdin and stdin project as destination, extensions, overwrite (inverted) and download_files(files) in every binding; pyMzLib's spec lint will need PYTHON_DEVIATIONS entries.