Adding sample metadata

Sample metadata (pedigrees, phenotypes, and custom attributes) is added from the storage account's samples page with the Add Metadata dialog. You can upload individual files, or add metadata for many samples at once with a single .zip archive.

Adding metadata requires the Manage Samples capability.

What you can upload

The file's name and extension decide how it's read:

File	Read as
*.ped	A pedigree. See Family Based Analysis with Pedigree Information for the format.
Any other *.json or *.jsonl	A phenopacket (phenotype terms and other clinical metadata).
*.attributes.json	Custom attributes, keyed by sample ID.
*.zip	An archive containing any of the files above.

Click Download Templates in the dialog for example files.

Custom attributes

A custom attributes file maps each sample ID to the attributes you want to store for it. Values can be text, numbers, lists, or nested objects. For example, lab.attributes.json:

{
  "HG002": { "kit_lot": "A7-2291" }
}

The sample must already exist in Workbench. Custom attributes appear on the sample details page.

Uploading overwrites the metadata of every sample named in the file, and replaces its attributes outright: anything you leave out of the file is removed. This can't be undone.

Uploading individual files

1. Click Data in the left navigation and select the storage account.

2. Click Add Metadata in the page header.

3. Select up to 50 .ped, .json, .jsonl or .attributes.json files.

4. Click Next to open the Preview. Step through the files one at a time. Each is marked Valid or Issues Found; a file with issues shows the line number and error in a Validation Issue panel.

5. Click Save. If the upload replaces existing metadata, confirm in the Update Metadata dialog.

6. Review the results and click Close.

Uploading a .zip archive

A .zip archive lets you add metadata for many samples in one step.

1. Click Add Metadata in the samples page header.

2. Select a single .zip file. An archive must be uploaded on its own, not mixed with individual files.

3. Click Upload. Archives skip the preview; each file's result is reported after the upload.

4. Review the results and click Close.

Upload results

When the upload finishes, the Upload complete screen reports how many samples received metadata, for example "Metadata added for 12 samples from 3 files". Any file that needs attention is listed under Needs attention, marked either not added or added, some entries skipped, with the reason for each problem.

Limits

• Up to 50 individual files per upload.

• Each file must be within the per-file size limit (5 MB by default). Files that are too large, of an unsupported type, or beyond the 50-file limit aren't added, and the dialog tells you how many were skipped and why.

• A .zip archive must be uploaded on its own.

You can also upload metadata and manage custom attributes from the command line. See samples metadata upload and samples attributes set.

Maintain patient privacy. Never include identifying information in metadata files.