Skip to content

Project sample manifests

Projects can optionally have sample manifest files attached to them, which will restrict which sample identifiers ("client IDs") can be added to the respective project. This feature is primarily used to constrain a project in order to prevent adding misnamed samples. The feature is only enabled if sample manifest files are uploaded to a project, otherwise client IDs are subject to Gencove's standard naming practices.

Once sample manifests are attached to a project, any samples attempted to be added to the project will be first validated against the manifest. In the event of a sample identifier mismatch, the sample will not be created, and an error will be raised.

Sample manifests can be attached to a project through several routes:

  1. Project web UI
  2. API
  3. CLI

Defining a sample manifest

Sample manifests can either be supplied as comma delimited files (CSV), or Excel files (XLSX). When submitting Excel files, multiple sheets can be used, each of which are subject to validation.

Sample manifest sheets must contain a table of information about a sequencing run. They must contain the following columns, with only the Unique sample identifier and Well columns requiring values to be populated:

  • Plate ID (optional)
  • Well (required)
  • Unique sample identifier (required)
  • Buffer (optional)
  • Concentration (optional)
  • Species (optional)
  • Coverage (optional)

Example CSV contents:

Plate ID,Well,Unique sample identifier,Buffer,Concentration if known (ng/ul),Species,Coverage
Tube,A1,sample-1,Water,30,Human,1x
Tube,B1,sample-2,Water,30,Human,1x
Tube,C1,sample-3,Water,30,Human,1x
Tube,D1,sample-4,Water,30,Human,1x
...

In the above example, only samples with identifiers listed under the Unique sample identifier column will be allowed to be added to the project.

Note that the items under the "Well" column are in ascending order alphabetically. This order is enforced when uploading a manifest, e.g. A1, B1, C1 is acceptable, but A1, A2, A3 is not. We support 3 different manifest formats 1) 96-well, 2) 384-well, 3) tube. When using the tube format, any number of rows can be populated.

We strongly recommend using one of the provided templates to populate your manifest. We support multiple manifest formats, which can be downloaded here:

  1. 3-plate XLSX template
    • This template can be extended to include any number of sheets, with any of the supported well configurations per-sheet
  2. 96-well CSV template
  3. 384-well CSV template
  4. Tube CSV template

Note that the Unique sample identifier column values must meet the following criteria to be valid:

  • Unique in sample manifest (no duplicates). The following special values are exempted from this check: Control, Negative Control, NTC, NC
  • Contain only alphanumeric characters (- character also allowed)

When submitting an Excel manifest, all of the above rules apply to each individual sheet. However, note that the Unique sample identifier duplicate check is done against the combination of all sample identifiers across all sheets.

Adding a sample manifest through the web UI

Under the project detail page, users can click the "Manage sample manifests" section to view the manifest management page.

From the manifest management page, new sample manifests can be uploaded via the "Upload sample manifest" button. This will open a dialog where the user is prompted to upload a manifest CSV or XLSX file.

Once a manifest has been added, it is validated before being registered in the project. If there are any errors with the manifest, they will be listed and the upload will be prevented.

Once a sample manifests have been uploaded, they can be viewed and downloaded at any time from the sample manifests management page.

Managing manifests using the CLI

Project sample manifests can be retrieved or uploaded via the CLI. The following commands can be used:

  • gencove projects create-sample-manifest <project_id> <sample_manifest_path>
    • Upload a sample manifest CSV or XLSX to a target project ID
  • gencove projects get-sample-manifests <project_id> <destination>
    • Download all sample manifests for a project ID to the supplied destination directory
  • gencove sample-manifests get-sample-manifest <manifest_id> <destination>
    • Download a specific sample manifest by ID to the supplied destination directory

Managing manifests using the API

Sample manifests can be viewed or uploaded via the API. The following endpoints are available:

  • POST /api/v2/project-sample-manifests/<project-id>
curl --request POST \
  --url https://api.gencove.com/api/v2/project-sample-manifests/<project-id> \
  --header 'Authorization: Api-Key <api-key>' \
  --header 'Content-Type: multipart/form-data' \
  --header 'accept: application/json' \
  --form sample_manifest=@/Users/example/sample_manifest.xlsx
  • GET /api/v2/project-sample-manifests/<project-id>
curl --request GET \
  --url https://api.gencove.com/api/v2/project-sample-manifests/<project-id> \
  --header 'Authorization: Api-Key <api-key>'
  • GET /api/v2/sample-manifests/<manifest-id>
curl --request GET \
  --url https://api.gencove.com/api/v2/sample-manifests/<manifest-id> \
  --header 'Authorization: Api-Key <api-key>'