Inconsistencies associated with recent changes to /rest/publication/ -- split into "development" and "evaluation"

[ramiromagno]

One of your latest changes to the REST API was the split of the array of the field associated_pgs_ids (from the /rest/publication/ endpoint) in 2 arrays development and evaluation. I believe this change should be accompanied by other changes to keep things consistent, or alternatively regress a bit here.

Take this example snippet of PGP000013 from a response to https://www.pgscatalog.org/rest/publication/PGP000013:

{
    "id": "PGP000013",
    "title": "Type 1 Diabetes Risk in African-Ancestry Participants and Utility of an Ancestry-Specific Genetic Risk Score.",
    "doi": "10.2337/dc18-1727",
    "PMID": 30659077,
    "journal": "Diabetes Care",
    "firstauthor": "Onengut-Gumuscu S",
    "date_publication": "2019-01-18",
    "authors": "Onengut-Gumuscu S, Chen WM, Robertson CC, Bonnie JK, Farber E, Zhu Z, Oksenberg JR, Brant SR, Bridges SL, Edberg JC, Kimberly RP, Gregersen PK, Rewers MJ, Steck AK, Black MH, Dabelea D, Pihoker C, Atkinson MA, Wagenknecht LE, Divers J, Bell RA, SEARCH for Diabetes in Youth, Type 1 Diabetes Genetics Consortium, Erlich HA, Concannon P, Rich SS.",
    "associated_pgs_ids": {
        "development": [
            "PGS000023"
        ],
        "evaluation": [
            "PGS000021",
            "PGS000023"
        ]
    }
}

Given that PGS000021 is associated with PGP000013, I would expect that querying for score PGS000021 would list also PGP000013 as an associated publication. However the response to https://www.pgscatalog.org/rest/score/PGS000021?format=json only shows PGP000011:

{
  "id": "PGS000021",
  "name": "GRS1",
  "ftp_scoring_file": "http://ftp.ebi.ac.uk/pub/databases/spot/pgs/scores/PGS000021/ScoringFiles/PGS000021.txt.gz",
  "publication": {
    "id": "PGP000011",
    "title": "A Type 1 Diabetes Genetic Risk Score Can Aid Discrimination Between Type 1 and Type 2 Diabetes in Young Adults.",
    "doi": "10.2337/dc15-1111",
    "PMID": 26577414,
    "journal": "Diabetes Care",
    "firstauthor": "Oram RA",
    "date_publication": "2015-11-17"
  },
...

I am guessing that now it would be important to also split the publication field into development and evaluation, and have arrays of publications inside them. Or, in alternative, include a new field in publications, i.e., stage, and simply have an array of publications with this extra variable.

Nevertheless, I had the understanding that the /rest/score endpoints returned information associated only with the development of a PGS, and not its evaluation. So the publications returned in this context would only be related to development. I think that would be a good idea as you already have the PPM concept that lists associations with respective PGSes and whose publications are also listed in the objects returned by /rest/performance/.

So right now, we have a hybrid situation, where PGPs map to "development" and "evaluation" PGS, but PGS only map to "development" PGP. Finally PPM only map to "evaluation" PGP.

[smlmbrt]

I'm not sure this is an issue, the Publication description in the Score endpoint is only to describe the citation of the paper that developed the score (which matches how it is displayed on the website). We'll add some extra description ("Citation for the paper that developed the PGS") to the schema to clarify this.

[ramiromagno]

You are absolutely right! I had misconception before about this.