Docs

dynamic-pdb is the command line client for the registry. Use it to deposit datasets: entries, models, their files, and the metrics measured against them.

Installation

Install the client:

curl -fsSL https://dynamicpdb.com/install.sh | bash

macOS and Linux, amd64 and arm64.

Authentication

Depositing requires an account. Log in with the login command:

dynamic-pdb login

The command prints a URL and a one-time code; enter the code in your browser to authorize the client through GitHub.

To log out:

dynamic-pdb logout

Create a manifest

A manifest describes what to upload: the entries, their models, the artifacts belonging to each, and where metadata and metrics are read from. Generate a draft from a data folder:

dynamic-pdb upload manifest init ./my-dataset

This writes dynamic-pdb.manifest.yaml to the current directory. Use --out to write it elsewhere.

version: 1
data_root: .

filter:
  include:
    - 9ZZZ

entries:
  - pdb_id: "{{ pdb_id }}"
    name: "{{ pdb_id }} room-temperature refinement"
    metadata:
      resolution:
        - source:
            files:
              - metadata/{{ pdb_id }}.json
          extract:
            json:
              field: entry.resolution
    artifacts:
      - id: fasta
        source:
          files:
            - sequences/{{ pdb_id }}.fasta
        level: L0
    models:
      - id: model_1
        name: "{{ pdb_id }} refined model"
        model_type: Single Conformer
        purpose: Refinement
        artifacts:
          - id: coordinates
            source:
              files:
                - models/{{ pdb_id }}_model.pdb
            level: L2
          - id: reflections
            source:
              files:
                - models/{{ pdb_id }}_model.mtz
            level: L1
        metrics:
          r_free:
            - source:
                artifact: coordinates
              extract:
                pdb:
                  field: REMARK 3 FREE R VALUE

Which entries get uploaded

{{ pdb_id }} is a wildcard for a four-character PDB ID. The client walks data_root, and every file that matches becomes an entry:

manifest:  models/{{ pdb_id }}_model.pdb

on disk:   models/5rgd_model.pdb   →  entry 5RGD
           models/6zbx_model.pdb   →  entry 6ZBX

Artifacts

Every artifact needs a source and a level:

artifacts:
  - id: coordinates
    source:
      files:
        - models/{{ pdb_id }}_model.pdb
    level: L2

level is L0 raw source, L1 processed source, L2 structural models or L3 evaluations. Artifacts listed on the entry belong to the dataset; artifacts listed inside a model belong to that model.

Metadata and metrics

From JSON, by dotted path:

metadata:   # title, method, resolution, organism, space_group
  resolution:
    - source:
        files:
          - metadata/{{ pdb_id }}.json
      extract:
        json:
          field: entry.resolution

From a PDB file, by REMARK field:

metrics:   # r_work, r_free, clashscore, ramachandran_outliers
  r_free:
    - source:
        artifact: coordinates   # an artifact declared above, by id
      extract:
        pdb:
          field: REMARK 3 FREE R VALUE

From a CSV or TSV:

extract:
  csv:              # or tsv:
    column: r_free
    where:
      column: pdb_id
      equals: "{{ pdb_id }}"

From an mmCIF tag:

extract:
  mmcif:
    field: _refine.ls_R_factor_R_free

Upload files

Pass the manifest to upload start:

dynamic-pdb upload start dynamic-pdb.manifest.yaml

• --concurrency <n> — entries in parallel. Default 1.
• --upload-part-concurrency <n> — parts per file in parallel. Default 1.
• --include <pdb-id>[,...] — upload only these IDs.
• --skip <pdb-id>[,...] — leave these IDs out.