Creating annotation stores - AWS HealthOmics
Create an annotation store using the consoleCreate an annotation store using the APICreating new versions of annotation stores

Creating annotation stores

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 topics show how to use the HealthOmics console and AWS CLI to create and manage annotation stores.

Create an annotation store using the console

The following procedure to create annotation stores using the HealthOmics console.

To create an annotation store

  1. Open the HealthOmics console https://console.aws.amazon.com/omics/.

  2. In the left navigation pane, choose Annotation stores.

  3. On the Annotation stores page, choose Create annotation store.

  4. On the Create annotation store page, provide the following information

    • Annotation store name - A unique name for this store.

    • Description (optional) - A description of this reference genome.

    • Data format and schema details - Select data file format and upload the schema definition for this store.

    • Reference genome - The reference genome for this annotation.

    • Data Encryption - Choose whether you want data encryption to be owned and managed by AWS or by yourself.

    • Tags (optional) - Provide up to 50 tags for this annotation store.

  5. Choose Create annotation store.

Create an annotation store using the API

The following example shows how to create an annotation store using the AWS CLI. For all AWS CLI and API operations, you must specify the format of your data. 

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

You receive the following response to confirm the creation of your annotation store.

{
           "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 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 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.

Creating new versions of annotation stores

You can create new versions of annotation stores to collect different versions of your annotation databases. This helps you organize your annotation data, which is updated regularly.

To create a new version of an existing annotation store, use the create-annotation-store-version API as shown in the following example.

aws omics create-annotation-store-version \
     --name my_annotation_store \
     --version-name my_version

You will get the following response with the annotation store version ID, confirming that a new version of your annotation has been created.

{
     "creationTime": "2023-07-21T17:15:49.251040+00:00",
     "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 update the description of an annotation store version, you can use update-annotation-store-version to add updates to an annotation store version. 

aws omics update-annotation-store-version \
    --name my_annotation_store \
    --version-name my_version \
    --description "New Description"

You will receive the following response, confirming that the annotation store version has been updated.

{
     "storeId": "4934045d1c6d",
     "id": "2a3f4a44aa7b",
     "description":"New Description",
     "status": "ACTIVE",
     "name": "my_annotation_store",
     "versionName": "my_version",
     "creation Time": "2023-07-21T17:20:59.380043+00:00",
     "updateTime": "2023-07-21T17:26:17.892034+00:00"
}

To view the details of an annotation store version, use get-annotation-store-version.

aws omics get-annotation-store-version --name my_annotation_store --version-name my_version

You will receive a response with the version name, status, and other details.

{
     "storeId": "4934045d1c6d",
     "id": "2a3f4a44aa7b",
     "status": "ACTIVE",
     "versionArn": "arn:aws:omics:us-west-2:555555555555:annotationStore/my_annotation_store/version/my_version",
     "name": "my_annotation_store",
     "versionName": "my_version",
     "creationTime": "2023-07-21T17:15:49.251040+00:00",
     "updateTime": "2023-07-21T17:15:56.434223+00:00",
     "statusMessage": "",
     "versionSizeBytes": 0
    }

To view all versions of an annotation store, you can use list-annotation-store-versions, as shown in the following example.

aws omics list-annotation-store-versions --name my_annotation_store

You will receive a response with the following information

{
  "annotationStoreVersions": [
    {
     "storeId": "4934045d1c6d",
     "id": "2a3f4a44aa7b",
     "status": "CREATING",
     "versionArn": "arn:aws:omics:us-west-2:555555555555:annotationStore/my_annotation_store/version/my_version_2",
     "name": "my_annotation_store",
     "versionName": "my_version_2",
     "creation Time": "2023-07-21T17:20:59.380043+00:00",
     "versionSizeBytes": 0
    },
    {
     "storeId": "4934045d1c6d",
     "id": "4934045d1c6d",
     "status": "ACTIVE",
     "versionArn": "arn:aws:omics:us-west-2:555555555555:annotationStore/my_annotation_store/version/my_version_1",
     "name": "my_annotation_store",
     "versionName": "my_version_1",
     "creationTime": "2023-07-21T17:15:49.251040+00:00",
     "updateTime": "2023-07-21T17:15:56.434223+00:00",
     "statusMessage": "",
     "versionSizeBytes": 0
    }
}

If you no longer need an annotation store version, you can use delete-annotation-store-versions to delete an annotation store version, as shown in the following example.

aws omics delete-annotation-store-versions --name my_annotation_store --versions my_version

If the store version is deleted without errors, you will receive the following response.

{
  "errors": []
}

If there are errors, you will receive a response with the details of the errors, as shown.

{
  "errors": [
    {
      "versionName": "my_version",
      "message": "Version with versionName: my_version was not found."
    }
  ]
}

If you try to delete an annotation store version that has an active import job, you will receive a response with an error, as shown.

{
  "errors": [
    {
      "versionName": "my_version",
      "message": "version has an inflight import running"
    }
  ]
}

In this case, you can force deletion of the annotation store version, as shown in the following example.

aws omics delete-annotation-store-versions --name my_annotation_store --versions my_version --force