Creating and managing annotation store examples

An annotation store is a data store representing an annotation database, such as one from a TSV, VCF, or GFF file. If the same reference genome is specified, annotation stores are mapped to the same coordinate system as variant stores during an import. The following examples show how to use the AWS CLI to create and manage an annotation store.

In the following example, the AWS CLI is used to create an annotation store. For all AWS CLI and API operations, the format of your data must be declared.

aws omics create-annotation-store --name my_annotation_store \
     --store-format VCF \
     --reference referenceArn="arn:aws:omics:us-west-2:555555555555:referenceStore/6505293348/reference/5987565360"
     --version-name new_version

To confirm the creation of your annotation store, you will receive the following response.

{
     "creationTime": "2022-08-24T20:34:19.229500Z",
     "id": "3b93cdef69d2",
     "name": "my_annotation_store",
     "reference": {
         "referenceArn": "arn:aws:omics:us-west-2:555555555555:referenceStore/6505293348/reference/5987565360"
     },
     "status": "CREATING"
     "versionName": "my_version"
 }  

To learn more about an annotation store, use the get-annotation-store API.

aws omics get-annotation-store --name my_annotation_store

You will receive the following response.

{
    "id": "eeb019ac79c2",
    "reference": {
        "referenceArn": "arn:aws:omics:us-west-2:555555555555:referenceStore/5638433913/reference/5871590330“
    },
    "status": "ACTIVE",
    "storeArn": "arn:aws:omics:us-west-2:555555555555:annotationStore/gffstore",
    "name": "my_annotation_store",
    "creationTime": "2022-11-05T00:05:19.136131+00:00",
    "updateTime": "2022-11-05T00:10:36.944839+00:00",
    "tags": {},
    "storeFormat": "GFF",
    "statusMessage": "",
    "storeSizeBytes": 0,
    "numVersions": 1
}   

To view all annotation stores associated with an account, use the list-annotation-stores API operation.

aws omics list-annotation-stores 

You will receive a response that lists all annotation stores, along with their IDs, statuses, and other details, as shown in the following example response.

{
     "annotationStores": [
         {
            "id": "4d8f3eada259",
             "reference":
                 "referenceArn": "arn:aws:omics:us-west-2:555555555555:referenceStore/5638433913/reference/5871590330"
             },
             "status": "CREATING",
             "name": "gffstore",
             "creationTime": "2022-09-27T17:30:52.182990+00:00",
             "updateTime": "2022-09-27T17:30:53.025362+00:00"
         }
     ]
 }   

You can also filter responses based on status or other criteria.

The following example shows how to use the AWS CLI to start an annotation import job.

aws omics start-annotation-import-job \
     --destination-name myannostore \
     --version-name myannostore \
     --role-arn arn:aws:iam::123456789012:role/roleName \
     --items source=s3://my-omics-bucket/sample.vcf.gz
     --annotation-fields '{"VEP": "CSQ"}' 

Annotation stores created before May 15, 2023 return an error message if the annotation-fields is included. They don't return output for any API operations involved with annotation store import jobs.

You can then use the get-annotation-import-job API operation and the job ID parameter to learn more details about the annotation import job.

aws omics get-annotation-import-job --job-id 9e4198fb-fa85-446c-9301-9b823a1a8ba8         

You will receive the following response, including the annotation fields.

{
    "creationTime": "2023-04-11T19:09:25.049767+00:00",
    "destinationName": "parsingannotationstore",
    "versionName": "parsingannotationstore",
    "id": "9e4198fb-fa85-446c-9301-9b823a1a8ba8",
    "items": [
        {
            "jobStatus": "COMPLETED",
            "source": "s3://my-omics-bucket/sample.vep.vcf"
        }
    ],
    "roleArn": "arn:aws:iam::55555555555:role/roleName",
    "runLeftNormalization": false,
    "status": "COMPLETED",
    "updateTime": "2023-04-11T19:13:09.110130+00:00",
    "annotationFields" : {"VEP": "CSQ"}
 }   
   

To view all annotation store import jobs, use list-annotation-import-jobs .

aws omics list-annotation-import-jobs --ids 9e4198fb-fa85-446c-9301-9b823a1a8ba8          

The response includes the details and statuses of your annotation store import jobs.

{
    "annotationImportJobs": [
    {
        "creationTime": "2023-04-11T19:09:25.049767+00:00",
        "destinationName": "parsingannotationstore",
        "versionName": "parsingannotationstore",
        "id": "9e4198fb-fa85-446c-9301-9b823a1a8ba8",
        "roleArn": "arn:aws:iam::55555555555:role/roleName",
        "runLeftNormalization": false,
        "status": "COMPLETED",
        "updateTime": "2023-04-11T19:13:09.110130+00:00",
        "annotationFields" : {"VEP": "CSQ"}
    }
    ]
}