Add genome groups #78

bilalebi · 2025-11-13T16:21:44Z

Description

Added two REST endpoints that will be used by the structural variant page

Related JIRA Issue(s)

Main JIRA ticket: https://embl.atlassian.net/browse/ENSPLAT-269
Sub task: https://embl.atlassian.net/browse/ENSPLAT-271

Review App URL(s)

https://ensembl.github.io/ensembl-web-metadata-api/

⚠️ Won't work until Ensembl/ensembl-metadata-api#172 is merged and deployed

Example(s)

`/api/metadata/genome_groups`

Request:

http://127.0.0.1:8014/api/metadata/genome_groups?group_type=structural_variant

Response:

{
  "genome_groups": [
    {
      "id": "grch38-group",
      "type": "structural_variant",
      "name": null,
      "reference_genome": {
        "genome_id": "a7335667-93e7-11ec-a39d-005056b38ce3",
        "genome_tag": "grch38",
        "common_name": "Human",
        "scientific_name": "Homo sapiens",
        "species_taxonomy_id": "9606",
        "type": null,
        "is_reference": true,
        "assembly": {
          "accession_id": "GCA_000001405.29",
          "name": "GRCh38.p14",
          "url": "https://identifiers.org/insdc.gca/GCA_000001405.29"
        },
        "release": {
          "name": "2025-02",
          "type": "integrated",
          "is_current": true
        }
      }
    },
    {
      "id": "t2t-group",
      "type": "structural_variant",
      "name": null,
      "reference_genome": {
        "genome_id": "4c07817b-c7c5-463f-8624-982286bc4355",
        "genome_tag": "t2t-chm13",
        "common_name": "Human",
        "scientific_name": "Homo sapiens",
        "species_taxonomy_id": "9606",
        "type": null,
        "is_reference": false,
        "assembly": {
          "accession_id": "GCA_009914755.4",
          "name": "T2T-CHM13v2.0",
          "url": "https://identifiers.org/insdc.gca/GCA_009914755.4"
        },
        "release": {
          "name": "2025-02",
          "type": "integrated",
          "is_current": true
        }
      }
    }
  ]
}

`/api/metadata/genome_groups/{group_id}/genomes`

Request:

http://127.0.0.1:8014/api/metadata/genome_groups/grch38-group/genomes

Response:

{
  "genomes": [
    {
      "genomeUuid": "a7335667-93e7-11ec-a39d-005056b38ce3",
      "genome_tag": "grch38",
      "common_name": "Human",
      "scientific_name": "Homo sapiens",
      "species_taxonomy_id": "9606",
      "type": null,
      "is_reference": true,
      "assembly": {
        "accession": "https://identifiers.org/insdc.gca/GCA_000001405.29",
        "name": "GRCh38.p14"
      },
      "release": {
        "releaseLabel": "2025-02",
        "releaseType": "integrated",
        "isCurrent": true
      }
    },
    {
      "genomeUuid": "4c07817b-c7c5-463f-8624-982286bc4355",
      "genome_tag": "t2t-chm13",
      "common_name": "Human",
      "scientific_name": "Homo sapiens",
      "species_taxonomy_id": "9606",
      "type": null,
      "is_reference": false,
      "assembly": {
        "accession": "https://identifiers.org/insdc.gca/GCA_009914755.4",
        "name": "T2T-CHM13v2.0"
      },
      "release": {
        "releaseLabel": "2025-02",
        "releaseType": "integrated",
        "isCurrent": true
      }
    }
  ]
}

Dependencies

⚠️ Don't merge this one until Ensembl/ensembl-metadata-api#172 is!

azangru · 2025-11-14T11:45:49Z

app/api/models/genome.py

+    assembly_name: str = Field(alias="assemblyName")
+    is_reference: bool = Field(alias="isReference", default=False)
+    is_group_reference: bool = Field(alias="isGroupReference", default=False)
+    release: Release = None


I have all sorts of questions about this PR, which arose after trying to understand this Genome model.

Is the /genome_groups endpoint intended to provide data both for this part of the UI:

and for this part of the UI:

I understand that the first image shows "organism groups", and the second one shows "genome groups" — are you planning to keep this distinction, or are you planning to somehow unite both at the level of the json api?

Especially if we expect the two images above to be generated from data from different endpoints, then could you remind me what the reference_genome in the JSON payload was intended for?

Sorry; I realised that I was being stupid and that we are actually talking about the structural variants UI 🤦‍♂️

In that case yes, I remember why we needed the reference genome for group.

But even so:

Will the /genome_groups endpoint also be used to power the search UI?

Shouldn't the reference genome payload resemble the response from the explain endpoint: https://staging-2020.ensembl.org/api/metadata/genome/grcm39/explain? Or actually, the shape of a search match (https://staging-2020.ensembl.org/api/search/genomes?species_taxonomy_id=10090), if we reuse the genomes endpoint for the search UI

Perhaps @EbiArnie should also be among the reviewers then, since there are overlapping concerns.

I'd address search needs in its own PR, this more compact payload is good for SV. I don't think we even need the release info for the genome selection dropdowns.
@azangru do the payload fields here cover the different genome labelling options in the dropdown?

We would need:

- genome_id - genome_tag - common_name - scientific_name - type (a json object) - is_reference - assembly (a json object)

But at that point, adding the release probably shouldn't be a problem.

azangru · 2025-11-14T11:46:16Z

app/api/models/genome.py

+    group_id: str = Field(alias="groupId")
+    group_type: str = Field(alias="groupType")
+    group_name: str | None = Field(alias="groupName", default=None)
+    reference_genome: Genome = Field(alias="referenceGenome")


Doesn't a group also need a count?

I don't think the SV app uses counts anywhere.

app/api/models/genome.py

azangru · 2025-11-14T11:54:59Z

app/api/models/genome.py

+    genome_groups: list[GenomeGroup] = Field(alias="genomeGroups")
+
+class GenomesInGroupResponse(BaseModel):
+    genomes: list[Genome] = Field(alias="genomes")


Genomes in group should match the search results payload, I think. If we want them to populate the table in the same way other search results do:

…fixes

bilalebi · 2025-11-18T15:16:38Z

@azangru I updated the output to use the same model used by /explain (please see the updated output exmaples in the PR description) and removed group_ from GenomeGroup attributes

veidenberg

Looks good for SV app requirements (has genome id, common name, assembly name).

azangru · 2025-11-18T16:39:09Z

app/api/models/genome.py

+    id: str = Field(alias="groupId")
+    type: str = Field(alias="groupType")
+    name: str | None = Field(alias="groupName", default=None)
+    reference_genome: BaseGenomeDetails = Field(alias="referenceGenome")


Just remember that this is a nullable field. We should always have a reference genome for structural variant groups, but not for other groups.

The object name is kinda deceiving at this stage, I think of changing it to SVGenomeGroup because it's SV specific

bilalebi added 2 commits November 13, 2025 16:06

add genomes groups endpoints for SV

c341e0d

attempt to add ReDoc page

4925c9a

bilalebi self-assigned this Nov 13, 2025

trigger github pages

8211cda

bilalebi temporarily deployed to github-pages November 13, 2025 16:26 — with GitHub Pages Inactive

Add ReDoc GitHub Pages deployment for OpenAPI spec

6732b72

bilalebi temporarily deployed to github-pages November 13, 2025 16:41 — with GitHub Actions Inactive

bilalebi temporarily deployed to github-pages November 13, 2025 16:46 — with GitHub Pages Inactive

attempt to fix redoc page

2d06f9f

bilalebi temporarily deployed to github-pages November 13, 2025 16:49 — with GitHub Actions Inactive

bilalebi temporarily deployed to github-pages November 13, 2025 16:49 — with GitHub Pages Inactive

attempt to fix redoc page (2nd attempt)

0e4698e

bilalebi temporarily deployed to github-pages November 13, 2025 16:53 — with GitHub Actions Inactive

bilalebi temporarily deployed to github-pages November 13, 2025 16:53 — with GitHub Pages Inactive

giving up on Redoc and switching to swagger

61e3e4f

bilalebi temporarily deployed to github-pages November 13, 2025 16:55 — with GitHub Actions Inactive

bilalebi temporarily deployed to github-pages November 13, 2025 16:56 — with GitHub Pages Inactive

update readme

fa5b6a7

bilalebi temporarily deployed to github-pages November 13, 2025 17:30 — with GitHub Pages Inactive

bilalebi requested review from azangru, darefalola and veidenberg November 14, 2025 09:35

azangru reviewed Nov 14, 2025

View reviewed changes

app/api/models/genome.py Outdated Show resolved Hide resolved

azangru reviewed Nov 14, 2025

View reviewed changes

darefalola approved these changes Nov 14, 2025

View reviewed changes

DRY the model and use BaseGenomeDetails instead of Genome plus minor …

2d039f3

…fixes

bilalebi temporarily deployed to github-pages November 18, 2025 15:14 — with GitHub Pages Inactive

veidenberg approved these changes Nov 18, 2025

View reviewed changes

azangru reviewed Nov 18, 2025

View reviewed changes

azangru approved these changes Nov 18, 2025

View reviewed changes

bilalebi merged commit ddeea5d into main Nov 20, 2025
3 checks passed

azangru deleted the add-genome-groups branch November 20, 2025 16:39

Add genome groups #78

Add genome groups #78

Uh oh!

Conversation

bilalebi commented Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related JIRA Issue(s)

Review App URL(s)

Example(s)

/api/metadata/genome_groups

/api/metadata/genome_groups/{group_id}/genomes

Dependencies

Uh oh!

azangru Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

azangru Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

veidenberg Nov 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

azangru Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

azangru Nov 14, 2025

Choose a reason for hiding this comment

Uh oh!

veidenberg Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

azangru Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bilalebi commented Nov 18, 2025

Uh oh!

veidenberg left a comment

Choose a reason for hiding this comment

Uh oh!

azangru Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

bilalebi Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

bilalebi commented Nov 13, 2025 •

edited

Loading

`/api/metadata/genome_groups`

`/api/metadata/genome_groups/{group_id}/genomes`

azangru Nov 14, 2025 •

edited

Loading

azangru Nov 14, 2025 •

edited

Loading

veidenberg Nov 18, 2025 •

edited

Loading

azangru Nov 14, 2025 •

edited

Loading

bilalebi Nov 20, 2025 •

edited

Loading