PyALM Docs

Basic usage
1. Summary level information
2. More detailed source information
Working with data
1. Working with history
2. Working with events

Basic usage

Summary Level Information

After installation (see the README) import the library and call the API give a doi and the information level required (summary, event, history, detail). We are starting with the API call which just gives summary level information.

>>> import pyalm.pyalm as alm

>>> article = alm.get_alm("10.1371/journal.pone.0029797", info="summary")

The returned object provides some basic information:

>>> article
<ArticleALM Ecological Guild Evolution and the Discovery of the World's Smallest Vertebrate, DOI 10.1371/journal.pone.0029797>

We can then start getting some summary information about the returned object. With the summary API call you obtain the basic bibliographic information (title, doi, url, publication_date), the most recent update_date, the identifiers for the paper (doi, pmid, pmcid) alongside summary metrics information (views, shares, bookmarks, citations). In each case the relevant information can be obtained as an attribute of the response:

>>> article.title
u"Ecological Guild Evolution and the Discovery of the World's Smallest Vertebrate"
>>> article.url
u'http://www.plosone.org/article/info%3Adoi%2F10.1371%2Fjournal.pone.0029797'

>>> article.doi
u'10.1371/journal.pone.0029797'
>>> article.pmid
u'22253785'

>>> article.views
30169
>>> article.citations
7

The returned object is always a list of ArticleALM objects. If a single DOI is passed the list will be of length one. Multiple DOIs should be passed to the get method as a list of strings of the form 10.1371/journal.pgen.1004001.

>>> articles = alm.get_alm(
...         ["10.1371/journal.pone.0029797","10.1371/journal.pone.0029798"],
...         info="summary")
>>> len(articles)
2
>>> for article in articles:
...     print article.title,"DOI:", article.doi,
...     print "Views:", article.views
...
Ecological Guild Evolution and the Discovery of the World's Smallest Vertebrate DOI: 10.1371/journal.pone.0029797 Views: 30169
Mitochondrial Electron Transport Is the Cellular Target of the Oncology Drug Elesclomol DOI: 10.1371/journal.pone.0029798 Views: 3527

More Detailed Source Information

To obtain more detailed information on each ALM source from the ALM API a request should be made for from detailed information. The options available are event, history, and detail. More information on the different levels can be found below. For all the info levels a specific set of sources can be specified from one to a list, to all (by omitting the source option). Specific sources are then available via the sources attribute of the returned object.

>>> article = alm.get_alm("10.1371/journal.pone.0029797",
...                       info="event", source="crossref")
>>> article.sources['crossref']
<Source CrossRef:7>

Quantitative information is available for the requested sources divided into the same categories provided by summary level info (views, shares, bookmarks, citations). If a category is not populated, eg shares for the twitter source then it will return None.

>>> article.sources['crossref'].metrics.total
7
>>> article.sources['crossref'].metrics.citations
7
>>> article.sources['crossref'].metrics.shares == None
True

Further information about the source itself and the last time the ALM App instance updated its records are also available from attributes of the source object.

>>> article.sources['crossref'].name
u'crossref'
>>> article.sources['crossref'].display_name
u'CrossRef'
>>> article.sources['crossref'].events_url
>>> article.sources['crossref'].update_date
datetime.datetime(2013, 12, 21, 1, 54, 20)

Working with data

When requesting more detailed data there are two options event and history. The history option provides information on the ALM over a series of timepoints. These timepoints are those when the ALM App polled the data source rather than the date or time of specific events. Finally the detail level provides both event and history data.

Event level data provides information on the specific events contributing to an ALM count. For instance, this will provide information on the individual tweets contributing to the overall count or individual citation events to the article of interest.

Working with histories

History data is parsed from the original JSON to an ordered list of duples where the first element is a datetime.datetime object and the second is the integer total count for that metric. It is obtained from the histories attribute of the source object. The list is ordered from oldest to newest record.

>>> article = alm.get_alm("10.1371/journal.pone.0029797",
...                       info="history", source="crossref")
>>> len(article.sources['crossref'].histories)
135
>>> article.sources['crossref'].histories[-1]
[datetime.datetime(2013, 12, 21, 1, 54, 20), 7]

The number of elements in the histories list reflects the frequency with which the App instance updates the record and is not sensitive to the actual events which cause the count.

Working with events

The event information is available via the events attribute on the source. Event data is not parsed direct from the return JSON object and needs to be handled by the user depending on their needs.

>>> article = alm.get_alm("10.1371/journal.pone.0029797",
...                       info="event", source="crossref")
>>> article.sources['crossref']
<Source CrossRef:7>

>>> article.sources['crossref'].events[0]
{u'event_url': u'http://dx.doi.org/10.1007/s13127-013-0152-4', u'event': {u'journal_abbreviation': u'Org Divers Evol', u'article_title': u'New insights into the systematics and molecular phylogeny of the Malagasy snake genus Liopholidophis suggest at least one rapid reversal of extreme sexual dimorphism in tail length', u'doi': u'10.1007/s13127-013-0152-4', u'contributors': {u'contributor': [{u'first_author': u'true', u'surname': u'Glaw', u'given_name': u'Frank', u'contributor_role': u'author', u'sequence': u'first'}, {u'first_author': u'false', u'surname': u'Kucharzewski', u'given_name': u'Christoph', u'contributor_role': u'author', u'sequence': u'additional'}, {u'first_author': u'false', u'surname': u'Nagy', u'given_name': u'Zolt\xe1n T.', u'contributor_role': u'author', u'sequence': u'additional'}, {u'first_author': u'false', u'surname': u'Hawlitschek', u'given_name': u'Oliver', u'contributor_role': u'author', u'sequence': u'additional'}, {u'first_author': u'false', u'surname': u'Vences', u'given_name': u'Miguel', u'contributor_role': u'author', u'sequence': u'additional'}]}, u'journal_title': u'Organisms Diversity & Evolution', u'fl_count': u'0', u'issn': [u'1439-6092', u'1618-1077'], u'year': u'2013', u'publication_type': u'full_text'}}

The events module provides a set of classes for handling specific types of events.