OneDep deposition

This integration uses the wwPDB/onedep_lib OneDep Remote API Library to authenticate and submit depositions.

Quick start

Sign in to OneDep with ORCID and generate a refresh token from the Deposition API panel.
Run pipeliner.setup_onedep_credentials and paste the token when prompted.
In an existing Pipeliner project, run pipeliner --default_runjob pipeliner.deposition.onedep and edit the generated job template.
Run the job with Start a OneDep deposition? set to No, inspect the draft, then continue the same job with it set to Yes to submit it.

The sections below describe each step in detail.

Credentials

OneDep credentials are stored in your user-level Pipeliner configuration, not in an individual Pipeliner project. Keep your refresh token private.

You can get your refresh token from the OneDep website by logging in with ORCID, agreeing to the wwPDB privacy policy, and generating the key.

Recommended setup

Sign in to OneDep with ORCID and generate a refresh token from the Deposition API panel. Then run one setup command.

$ pipeliner.setup_onedep_credentials
Paste the OneDep refresh token:

The token is hidden while it is pasted and is not included in the command history. The command stores it in Pipeliner’s config directory: ~/.config/ccpem/pipeliner/onedep/config.toml on Linux (under $XDG_CONFIG_HOME when set) or ~/Library/Application Support/ccpem/pipeliner/onedep/config.toml on macOS. It does not contact OneDep. The directory is mode 700 and the file is mode 600.

The OneDep config TOML path field in Pipeliner and Doppio defaults to this standard config, so no project-specific credential setup is needed.

Do not export ONEDEP_REFRESH_TOKEN or add it to a shell startup file: environment values override credentials subsequently loaded from the config.

Troubleshooting credentials

Credential and connectivity checks run before a deposition is created. If setup or the first authenticated request fails, correct the problem and run the job again:

If the config cannot be found, run pipeliner.setup_onedep_credentials and retry. No deposition has been created. New jobs default to Pipeliner’s standard config directory for your platform.
The config must be valid TOML and readable and writable by the user running Pipeliner.
If the refresh token is missing, expired, revoked, or invalid, generate a new key on the OneDep website and replace the refresh_token value.
If a custom OneDep server cannot be reached, check the network connection and its hostname setting. The production service does not need a hostname setting in the config.
If config changes appear to be ignored, make sure ONEDEP_ACCESS_TOKEN and ONEDEP_REFRESH_TOKEN are not set in the environment, because they override the config file.

No deposition is created when one of these checks fails.

Running a deposition

Run the following commands from the root of an existing Pipeliner project. Start by creating an editable run.job template:

$ pipeliner --default_runjob pipeliner.deposition.onedep

This creates pipeliner_deposition_onedep_run.job. Edit the relevant values; for example:

Main map == PostProcess/job030/postprocess.mrc
Half maps == Refine3D/job028/half1.mrc:::Refine3D/job028/half2.mrc
Entry image for public display == PostProcess/job030/entry.png
Start a OneDep deposition? == No
Depositor email == depositor@example.org
Depositor ORCID ID == 0000-0002-1825-0097
Depositor country == UK
EM subtype == SPA
Primary map contour level == 0.02

A live OneDep submission requires a main map and PNG entry image. The atomic model is optional. SPA, helical, and subtomogram depositions require exactly two half-maps; separate multiple paths in a run.job value with :::. Replace the example paths, identity values, and contour level with values appropriate to the deposition. Leave the default OneDep config TOML path unchanged to use Pipeliner’s standard config directory for your platform.

Prepare and review

Keep Start a OneDep deposition? set to No for the first run. You can inspect the commands and then run the job:

$ pipeliner --print_command pipeliner_deposition_onedep_run.job
$ pipeliner --run_job pipeliner_deposition_onedep_run.job

This prepares the deposition files without creating or uploading a remote deposition. The command prints the new job directory, such as Deposition/job031/. Inspect draft_deposition.mmcif in that directory before submitting.

Submit to OneDep

After reviewing the draft, edit Deposition/jobNNN/continue_job.star and set:

Start a OneDep deposition? == Yes
Run checks without creating/uploading deposition? == No

Then continue the existing job:

$ pipeliner --continue_job Deposition/jobNNN/

The live job checks authentication, calls deposit(), and writes its status, deposition ID, and link to Deposition/jobNNN/onedep_result.json. Details are written to Deposition/jobNNN/run.out; credential values are not written to project files or logs.

After deposit() completes, Pipeliner marks the upload and refuses to run it again. If it fails before completion, the upload can be retried. Check OneDep first because an interrupted response may still have created a deposition.

Prepare local files only

The direct CLI flags prepare a local OneDep deposition file but do not authenticate, create a remote deposition, or upload files. For example:

$ pipeliner --onedep_deposition \
    --primary_map PostProcess/job030/postprocess.mrc \
    --model ServalCat/job031/model.mmcif \
    --halfmaps Refine3D/job028/half1.mrc Refine3D/job028/half2.mrc

Use the pipeliner.deposition.onedep job workflow above when the intention is to submit to OneDep.

Alternative: create the standard config manually

Use this only when the setup command is unavailable. Create the path shown above with the following template and paste a newly generated refresh token.

For the production OneDep service:

[auths.deposit_wwpdb_org]
refresh_token = "<paste production refresh token>"

With the default Linux config location:

$ mkdir -p ~/.config/ccpem/pipeliner/onedep
$ chmod 700 ~/.config/ccpem/pipeliner/onedep
$ chmod 600 ~/.config/ccpem/pipeliner/onedep/config.toml

On macOS, use the corresponding ~/Library/Application Support/ccpem/pipeliner/onedep directory.

On the first authenticated request, onedep_lib exchanges the supplied refresh token and replaces it with the rotated credentials. The file must stay writable. Do not copy the same refresh token into multiple files: only the first copy to refresh remains valid.