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:
- Project web UI
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:
Unique sample identifier(required)
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:
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:
- 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:
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
curl --request GET \ --url https://api.gencove.com/api/v2/project-sample-manifests/<project-id> \ --header 'Authorization: Api-Key <api-key>'
curl --request GET \ --url https://api.gencove.com/api/v2/sample-manifests/<manifest-id> \ --header 'Authorization: Api-Key <api-key>'