Return 'valid_AphiaID'

[khiyer]

Hi,

I was wondering if it would be possible for fathomnet-py to also return the valid_AphiaID like pyworms does so that superceded ranks can be flagged/updated. The example below queries the species 'Swiftia pallida' using pyworms and fathomnet-py. The pyworms query shows that the species has been superceded and returns the superceded AphiaID which is called valid_AphiaID.

pyworms

>>>> import pyworms as pw
>>>> print(pw.aphiaRecordsByMatchNames('Swiftia pallida', marine_only=False)[0])

[{'AphiaID': 125401, 'url': 'https://www.marinespecies.org/aphia.php?p=taxdetails&id=125401', 'scientificname': 'Swiftia pallida', 
'authority': 'Madsen, 1970', 'status': 'superseded combination', 'unacceptreason': None, 'taxonRankID': 220, 'rank': 'Species', 
'valid_AphiaID': 1608729, 'valid_name': 'Callistephanus pallida', 'valid_authority': '(Madsen, 1970)', ...}]

fathomnet-py

>>>> from fathomnet.api import worms
>>>> print(worms.get_info('Swiftia pallida'))

WormsNode(name='Swiftia pallida', rank='Species', aphiaId=125401, alternateNames=['Nördliche Seefeder', 'northern sea fan', 
'Northern sea fan coral', 'corail pâle'], children=None)

[hohonuuli]

@khiyer I'll look into adding that to our custom worm server: https://github.com/fathomnet/worms-server

[hohonuuli]

Note to myself. This info is in the taxon.txt file we get from worms. It's in the 3rd column, acceptedNameUsageID

taxonID scientificNameID    acceptedNameUsageID parentNameUsageID   namePublishedInID   scientificName  acceptedNameUsage   parentNameUsage namePublishedIn namePublishedInYear kingdom phylum  class   order   family  genus   subgenus    specificEpithet infraspecificEpithet    taxonRank   scientificNameAuthorship    nomenclaturalCode   taxonomicStatus nomenclaturalStatus modified    bibliographicCitation   references  license rightsHolder    atasetName  institutionCode datasetID
urn:lsid:marinespecies.org:taxname:125401   urn:lsid:marinespecies.org:taxname:125401   urn:lsid:marinespecies.org:taxname:1608729  lsid:marinespecies.org:taxname:125314                 Swiftia pallida     Callistephanus pallida    a         Animalia    Cnidaria    Anthozoa  lacalcyonacea   exauridae   Swiftia     pallida     Species Madsen, 1970    ICZNsuperseded combination      2022-10-29      McFadden, C.S.; Cordeiro, R.; Williams, G.; van Ofwegen, L. (2023). World List of Octocorallia. Swiftia pallida Madsen, 1970. Accessed through: World Register of Marine Species at: https://www.marinespecies.org/aphia.php?p=taxdetails&id=125401 https://www.marinespecies.org/aphia.php?p=taxdetails&id=125401  

[hohonuuli]

@kevinsbarnard I've made the following 3 changes to worms-server:

1. acceptedAphiaId

All taxa nodes now include an acceptedAphiaID. So any endpoint that starts with taxa will return this field. This is the term they use internally, not sure why they use valid_AphiaID in their service. Example https://fathomnet.org/worms/taxa/info/Swiftia%20pallida returns:

{
  "name": "Swiftia pallida",
  "rank": "Species",
  "aphiaId": 125401,
  "acceptedAphiaId": 1608729,
  "alternateNames": [
    "Nördliche Seefeder",
    "northern sea fan",
    "Northern sea fan coral",
    "corail pâle"
    ]
}

2. /names/aphiaid/{aphid}

I've also added a new /names/aphiaid/{aphid} endpoint. This aggregates alternativeNames from any other nodes that use the matched node as their accepted one.

https://fathomnet.org/worms/names/aphiaid/125401

{
    "aphiaId": 125401,
    "name": "Swiftia pallida",
    "acceptedName": "Callistephanus pallida",
    "alternateNames": [
        "Northern sea fan coral",
        "Nördliche Seefeder",
        "corail pâle",
        "northern sea fan"
    ]
}

https://fathomnet.org/worms/names/aphiaid/1608729

{
    "aphiaId": 1608729,
    "name": "Callistephanus pallida",
    "acceptedName": "Callistephanus pallida",
    "alternateNames": [
        "Northern sea fan coral",
        "Nördliche Seefeder",
        "Swiftia pallida",
        "Swiftia rosea pallida",
        "corail pâle",
        "northern sea fan"
    ]
}

3. synonyms has a new behavior

The contract is that the first item in the list is the accepted id. Before it just found a node by its name and used the alternate names attached to the node. Now it find the accepted node and expands the search to find outdated (non-accepted?) nodes.

https://fathomnet.org/worms/synonyms/Swiftia%20pallida

Before

[
  "Swiftia pallida",
  "Northern sea fan coral",
  "Nördliche Seefeder",
  "corail pâle",
  "northern sea fan"
]

Now

[
  "Callistephanus pallida",
  "Northern sea fan coral",
  "Nördliche Seefeder",
  "Swiftia pallida",
  "Swiftia rosea pallida",
  "corail pâle",
  "northern sea fan"
  ]

[kevinsbarnard]

Implemented in v1.3.0. Thanks for the suggestion @khiyer and for the quick implementation server-side @hohonuuli!