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 are comma delimited files that contain a table of information about a sequencing run. They must contain the following columns, with only the Unique sample identifier column requiring values to populated:

  • Plate ID (optional)
  • Well (optional)
  • 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 first. 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.

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

  1. 96-well CSV template
  2. 384-well CSV template
  3. 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)

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 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 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.csv
  • 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>'
Back to top