To use apyhgnc in a project:

import apyhgnc

The apyhgnc package mimics the HGNC REST service, so the main types of requests it can handle are info, fetch and search.


From the HGNC REST service documentation:

The info request is used to request information about the service rather than fetching any data from the server. The response from info will contain information such as when the data within the server was last updated (lastModified), the number of documents (numDoc), which fields can be queried using search and fetch (searchableFields) and which fields may be returned by fetch (storedFields).

Available information can be retrieved using the info() function and the related attributes:

from apyhgnc import info

i = info()
i.lastModified      # list of searchable fields
i.numDoc            # list of stored fields
i.searchableFields  # date of last HGNC database modification
i.storedFields      # number of entries in HGNC database

An Info instance can be created using the Info class, and related attributes can be retrieved easily:

from apyhgnc import Info

i = Info()


From the HGNC REST service documentation:

The fetch request is the main request to retrieve particular records for the server that will return back all the fields as seen in the “storedFields” section of the info response. The fetch method requires the user to add the queriable field (as seen in the “searchableFields” section of the info) and the query term to the url.

Fetch queries can be used to retrieve the available information for an entity in HGNC, and can be issued either synchronously, using the fetch() function, or asynchronously, using the afetch() function:

from apyhgnc import fetch, afetch

# synchronous query
f = fetch("symbol", "ZNF3")

# asynchronous query
import asyncio
loop = asyncio.get_event_loop()
loop.run_until_complete(afetch("symbol", "ZNF3"))

Fetch requests can also be issued using the Fetch class and specifying a query field and value:

from apyhgnc import Fetch

f = Fetch("symbol", "ZNF3")

Entries retrieved from HGNC are returned as a dataframe; queries can be launched either synchronously or asynchronously:

f.query()   # synchronous query
f.aquery()  # asynchronous query (will return an asyncio.future)

Common attributes

In addition to the above-mentioned methods and attributes, there are others that are shared among the Info, Fetch and Search classes:

  • the .url attribute returns the URL used to retrieve results from HGNC.