Multi Tagger API Documentation

Overview

The Muti Tagger (taggerapi.php) provides a RESTful interface for submitting publication data to the Arrowsmith server for Publication Type model scoring or score retrieval. Currently, predictions are generated with models developed within this project: Fifty Ways to Tag your Pubtypes: Multi-Tagger, a Set of Probabilistic Publication Type and Study Design Taggers to Support Biomedical Indexing and Evidence-Based Medicine

For any questions, problems or comments, please contact Neil Smalheiser neils@uic.edu.

Quick links: Curl Examples   Python Examples   Responses    Supported Models

Endpoint URL

The base URL for all API requests is:

https://arrowsmith.psych.uic.edu/cgi-bin/arrowsmith_uic/Multi_Tagger/taggerapi.php

Content-Type

All requests to taggerapi.php should be made with the Content-Type set to multipart/form-data due to the nature of the operations, which may include file uploads.

POST Method

Requests are submitted to the endpoint using the POST method. File uploads are currently limited to 50M.

Parameters

• mode (required, string): Specifies the operation mode. Accepted values are pmid, ris, json, status, results.
• pmidlist (required if mode=pmid): A comma-separated list of PMIDs (PubMed ID numbers).
• file (required if mode=ris): A file containing document data for processing. See RIS File Details for more information.
• documentjson (required if mode=json): A JSON string containing documents for scoring. See JSON Details for more information.
• jobid (required if mode=status,results): A number for the job id

Processing Time

Jobs for score lookup by PubMed's PMID (mode='pmid') usually complete within 10 seconds depending on the list size and server load. Jobs for scoring of .ris files or JSON lists (mode='ris' or 'json') take a minimum of 15 minutes to process for small files and during light server load.

Request Examples - CURL

Here is an example of a CURL command to make a request for PubMed PMIDs to this endpoint:

curl -X POST https://arrowsmith.psych.uic.edu/cgi-bin/arrowsmith_uic/Multi_Tagger/taggerapi.php \
-F 'mode=pmid' \
-F 'pmidlist=17047312,22152914'

Here is an example of a CURL command to make a request with a RIS file to this endpoint:

curl -X POST https://arrowsmith.psych.uic.edu/cgi-bin/arrowsmith_uic/Multi_Tagger/taggerapi.php \
-F 'mode=ris' \
-F 'file=@path_to_file/document.ris'

Note about Certificate Authority
Some operating systems may not include InCommon.org in the default CA bundle. If SSL verification fails, the InCommon certificate (currently here) may be specified:

curl -X POST https://arrowsmith.psych.uic.edu/cgi-bin/arrowsmith_uic/Multi_Tagger/taggerapi.php --cacert incommon-rsa-ca2.pem \
-F 'mode=pmid' \
-F 'pmidlist=17047312,22152914'

Alternatively, certificate verification can be suppressed entirely with the -k option

curl -X POST https://arrowsmith.psych.uic.edu/cgi-bin/arrowsmith_uic/Multi_Tagger/taggerapi.php -k \
-F 'mode=pmid' \
-F 'pmidlist=17047312,22152914'

Here is an example of a CURL commands to poll the status of a job or retrieve results:

curl -X POST https://arrowsmith.psych.uic.edu/cgi-bin/arrowsmith_uic/Multi_Tagger/taggerapi.php \
-F 'mode=status' \
-F 'jobid=123'

curl -X POST https://arrowsmith.psych.uic.edu/cgi-bin/arrowsmith_uic/Multi_Tagger/taggerapi.php \
-F 'mode=results' \
-F 'jobid=123'

Request Examples - Python

Here is an example of a Python script to make a request for PubMed PMIDs to this endpoint:

import requests

# URL to send the data
url = "https://arrowsmith.psych.uic.edu/cgi-bin/arrowsmith_uic/Multi_Tagger/taggerapi.php"

# Data to be sent to the api
data = {
    'mode': 'pmid',
    'pmidlist': '17047312,22152914' #pmidlist should be a string with comma-separated values
}

# Make the POST request
response = requests.post(url, data=data)

if response.status_code == 200:
    results_dictionary = response.json()
    print(results_dictionary['status'],results_dictionary['jobid'])

#if InCommon CA is not in your CA bundle and the above requests.post fails, add the CA to your python environment:
import certifi
certifi.where()
#add the contents of incommon-rsa-ca2.pem to the end of the cacert.pem identified by certifi.where()
#restart the python kernel

#alternatively, verification can be suppressed by:
response = requests.post(url, data=data, verify=False)

Here is an example of a Python script to make a request for a RIS file to this endpoint:

import requests

# URL to send the data
url = "https://arrowsmith.psych.uic.edu/cgi-bin/arrowsmith_uic/Multi_Tagger/taggerapi.php"

# File to be uploaded
files = {'file': open('document.ris', 'rb')}

# Data to be sent along with file
data = {
    'mode': 'ris'
}

# Make the POST request
response = requests.post(url, files=files, data=data)

if response.status_code == 200:
    results_dictionary = response.json()
    print(results_dictionary['status'],results_dictionary['jobid'])

# Close the file
files['file'].close()

Here is an example of a Python script to make a request for a JSON to this endpoint:

import requests
import json

# article dictionary
articledata = {
    "myArticle1":
    {
        "TI" : "Mammalian microRNAs derived from genomic repeats" 
        ,
        "AB" : "In this article, we show that a subset of conventional mammalian \"microRNAs\" is derived from LINE-2 transposable elements and other genome repeats. These repeat-derived microRNAs arise from conventional precursor hairpins and are distinct from the rasiRNAs, which appear to be processed from long double-stranded RNA precursors. The insertion of transposable elements into new genomic sites appears to be one of the driving-forces that create new microRNAs during mammalian evolution. Two of the LINE-2-derived microRNAs exhibit perfect complementarity to a large family of mRNA and EST transcripts that contain portions of MIR and other LINE-2 elements in their 3'-untranslated regions." 
    }
    ,
    "myArticle2" : 
    {
        "TI" : "Dicer and eIF2c are enriched at postsynaptic densities in adult mouse brain and are modified by neuronal activity in a calpain‐dependent manner"
        ,
        "AB" : "We have hypothesized that small RNAs may participate in learning and memory mechanisms. Because dendritic spines are important in synaptic plasticity and learning, we asked whether dicer, the rate-limiting enzyme in the formation of small RNAs, is enriched within dendritic spines. In adult mouse brain, dicer and the RNA-induced silencing complex (RISC) component eIF2c were expressed in the somatodendritic compartment of principal neurons and some interneurons in many regions, and dicer was enriched in dendritic spines and postsynaptic densities (PSDs). A portion of dicer and eIF2c were associated with each other and with fragile X mental retardation protein (FMRP), as assessed by co-immunoprecipitation. Calpain I treatment of recombinant dicer or immunopurified brain dicer caused a marked increase in RNAse III activity. Purified PSDs did not exhibit RNAse III activity, but calpain caused release of dicer from PSDs in an enzymatically active form, together with eIF2c. NMDA stimulation of hippocampal slices, or calcium treatment of synaptoneurosomes, caused a 75 kDa dicer fragment to appear in a calpain-dependent manner. The findings support a model whereby acute neuronal stimulation at excitatory synapses increases intracellular calcium, which activates calpain, which liberates dicer and eIF2c bound to PSDs. This supports the hypothesis that dicer could be involved in synaptic plasticity."
    }
}

# URL to send the data
url = "https://arrowsmith.psych.uic.edu/cgi-bin/arrowsmith_uic/Multi_Tagger/taggerapi.php"

# Data to be sent along with the article data
data = {
    'mode': 'json',
    'documentjson': json.dumps(articledata) #pass article data as a form field with json string
}

# Make the POST request
response = requests.post(url, data=data)

# Results
print(response.json())

Here is an example of a Python script to poll for the status of a job or retrieve results:

import requests

# URL to send the data
url = "https://arrowsmith.psych.uic.edu/cgi-bin/arrowsmith_uic/Multi_Tagger/taggerapi.php"

# Data to be sent along with file
data = {
    'mode': 'status',
    'jobid': '123'
}

# Make the POST request
response = requests.post(url, data=data)

if response.status_code == 200:
    results_dictionary = response.json()
    print(results_dictionary['status'])

if results_dictionary['status']=='completed':
    data = {'mode': 'results','jobid': '123'}
    response = requests.post(url, data=data)
    results_dictionary = response.json()
    print(results_dictionary['results'])

Responses

The response will be a JSON containing the results or a status message.

Response Example For Mode = pmid or custom

{
  "success": true,
  "status": "job started",
  "jobid": "123",
  "message": "job created"
}

Response Example For Mode = status

{
  "success": true,
  "status": "processing",
  "jobid": "123",
  "message": "applying models"
}

Response Example For Mode = results

{
  "success": true,
  "status": "completed",
  "jobid": "123",
  "message": "model application complete",
  "results": {result json: an array with keys for each document and PT with [score,indicator of positive]}
  
results example:
    {"17047312": {"Autobiography": [0.00002566,0],"Bibliography": [0,0],"Biography": [0.00018406,0],...}

    see model details for a list of publication type models provided and more information about the output.
    

Response Example (Error)

{
  "status": "error"
  "message": "No valid PMIDs found."
}

Model Details

Result Output

The results object returned is a JSON dictionary with keys being the supplied document id's as a string. These will be pmids (as string) for mode=pmid or the supplied document identifier for mode=custom. See RIS Details for more information of supplying an identifer for scoring RIS files.
Each document id key yields a dictionary with 49 keys for each publication type model. The value of each key is a list containing [raw model score, indicator of positive]. The raw model scores range from 0 to 1, inclusive. The indicator is either 0 or 1, with 1 indicating the model score is greater than or equal to the model thresholds below.

Currently Supported Models

Model Name	Threshold for Positive Prediction
Autobiography	0.3738
Bibliography	1
Biography	0.5
Case-Control Studies	0.2928
Case Reports	0.4913
Clinical Studies as Topic	0.834
Clinical Study	0.363478
Cohort Studies	0.2347
Comment	0.4912
Congress	0.3895
Consensus Development Conference	0.2526
Cross-Cultural Comparison	0.3317
Cross-Over Studies	0.3667
Cross-Sectional Studies	0.3968
Diagnostic Test Accuracy	0.086
Double-Blind Method	0.4148
Editorial	0.1364
Evaluation Studies as Topic	0.1
Evaluation Study	0.1946
Feasibility Studies	0.3972
Focus Groups	0.4634
Follow-Up Studies	0.268
Genome-Wide Association Study	0.311
Historical Article	0.488
Human Experimentation	0.122
interview	0.3333
Interviews as Topic	0.2684
Lecture	0.2927
Legal Case	0.3571
Letter	0.1667
Longitudinal Studies	0.3005
Matched-Pair Analysis	0.3333
Meta-analysis	0.3935
Multicenter Study	0.3333
News	0.4545
Personal Narrative	0.875
Portrait	0.2985
Practice Guideline	0.2609
Predictive Value of Tests	0.2269
Prospective Studies	0.4063
Random Allocation	0.1339
Randomized Controlled Trial	0.2197
Reproducibility of Results	0.2767
Retrospective Studies	0.3971
Review	0.4624
Systematic Reviews as Topic	0.0622
Systematic Review	0.9406
Twin Study	0.4
Validation Study	0.3276

Error Handling

The API uses conventional HTTP response codes to indicate the success or failure of request communication.

• 200 OK: The request was successful.
• 400 Bad Request: The server could not understand the request due to invalid syntax.
• 500 Internal Server Error: The server encountered an unexpected condition.

A successful request communication that failed due to content error will return status="error". The nature of the error is described in the message element of the returned JSON.

RIS File Details

An RIS file is a bibliographic citation file saved in a format developed by Research Information Systems (RIS). It contains a series of two-letter tags and citation information associated with those tags. For more information about the .ris file specification see the Wikipedia page.
The following ris tags must be present for application of the models:

TY  - JOUR doesn't not need to be JOUR, but this tag must start an article entry
AN  - this will be used as the article id.  If these tags are omitted or if they are not unique within the uploaded file, the article ids will be assigned a sequential number starting with 1.
TI  - the title of the article
AB  - abstract for the article.  Do not include new line characters within the abstract.  Only text up to the first new line with be retained.
AU  - author, repeat for each author.  Optional
ER  - necessary tag to end an article entry

Here is an example of properly defined ris file with 2 articles for model scoring:

TY  - JOUR
TI  - Mammalian microRNAs derived from genomic repeats
AN  - myArticle1
AU  - Smalheiser, Neil R
AU  - Torvik VI
JO  - TRENDS in Genetics
VL  - 21
IS  - 6
SP  - 322
EP  - 326
SN  - 0168-9525
Y1  - 2005
PB  - Elsevier
AB  - In this article, we show that a subset of conventional mammalian microRNAs is derived from LINE-2 transposable elements and other genome repeats. These repeat-derived microRNAs arise from conventional precursor hairpins and are distinct from the rasiRNAs, which appear to be processed from long double-stranded RNA precursors. The insertion of transposable elements into new genomic sites appears to be one of the driving-forces that create new microRNAs during mammalian evolution. Two of the LINE-2-derived microRNAs exhibit perfect complementarity to a large family of mRNA and EST transcripts that contain portions of MIR and other LINE-2 elements in their 3'-untranslated regions.
ER  - 

TY  - JOUR
AN  - myArticle2
TI  - Dicer and eIF2c are enriched at postsynaptic densities in adult mouse brain and are modified by neuronal activity in a calpain‐dependent manner
JO  - Journal of neurochemistry
VL  - 94
IS  - 4
SP  - 896
EP  - 905
AB  - We have hypothesized that small RNAs may participate in learning and memory mechanisms. Because dendritic spines are important in synaptic plasticity and learning, we asked whether dicer, the rate-limiting enzyme in the formation of small RNAs, is enriched within dendritic spines. In adult mouse brain, dicer and the RNA-induced silencing complex (RISC) component eIF2c were expressed in the somatodendritic compartment of principal neurons and some interneurons in many regions, and dicer was enriched in dendritic spines and postsynaptic densities (PSDs). A portion of dicer and eIF2c were associated with each other and with fragile X mental retardation protein (FMRP), as assessed by co-immunoprecipitation. Calpain I treatment of recombinant dicer or immunopurified brain dicer caused a marked increase in RNAse III activity. Purified PSDs did not exhibit RNAse III activity, but calpain caused release of dicer from PSDs in an enzymatically active form, together with eIF2c. NMDA stimulation of hippocampal slices, or calcium treatment of synaptoneurosomes, caused a 75 kDa dicer fragment to appear in a calpain-dependent manner. The findings support a model whereby acute neuronal stimulation at excitatory synapses increases intracellular calcium, which activates calpain, which liberates dicer and eIF2c bound to PSDs. This supports the hypothesis that dicer could be involved in synaptic plasticity.
SN  - 0022-3042
Y1  - 2005
PB  - Wiley Online Library
ER  - 

JSON Format Details

A JSON string containing articles may be submitted for model application. The top level of the JSON structure must be a set of key:value pairs where the key being the article identifier and the value being another object containing, at a minimum, the following key:value pairs:

{"article1":
    { 
        "T1": "article title" 
        , 
        "AB": "article abstract"
    }
}

Double quotes appearing in the title or abstract must be escaped with \"
Here is an example of properly defined JSON string with 2 articles for model scoring:

{
    "myArticle1":
    {
        "TI" : "Mammalian microRNAs derived from genomic repeats" 
        ,
        "AB" : "In this article, we show that a subset of conventional mammalian \"microRNAs\" is derived from LINE-2 transposable elements and other genome repeats. These repeat-derived microRNAs arise from conventional precursor hairpins and are distinct from the rasiRNAs, which appear to be processed from long double-stranded RNA precursors. The insertion of transposable elements into new genomic sites appears to be one of the driving-forces that create new microRNAs during mammalian evolution. Two of the LINE-2-derived microRNAs exhibit perfect complementarity to a large family of mRNA and EST transcripts that contain portions of MIR and other LINE-2 elements in their 3'-untranslated regions." 
    }
    ,
    "myArticle2" : 
    {
        "T1" : "Dicer and eIF2c are enriched at postsynaptic densities in adult mouse brain and are modified by neuronal activity in a calpain‐dependent manner"
        ,
        "AB" : "We have hypothesized that small RNAs may participate in learning and memory mechanisms. Because dendritic spines are important in synaptic plasticity and learning, we asked whether dicer, the rate-limiting enzyme in the formation of small RNAs, is enriched within dendritic spines. In adult mouse brain, dicer and the RNA-induced silencing complex (RISC) component eIF2c were expressed in the somatodendritic compartment of principal neurons and some interneurons in many regions, and dicer was enriched in dendritic spines and postsynaptic densities (PSDs). A portion of dicer and eIF2c were associated with each other and with fragile X mental retardation protein (FMRP), as assessed by co-immunoprecipitation. Calpain I treatment of recombinant dicer or immunopurified brain dicer caused a marked increase in RNAse III activity. Purified PSDs did not exhibit RNAse III activity, but calpain caused release of dicer from PSDs in an enzymatically active form, together with eIF2c. NMDA stimulation of hippocampal slices, or calcium treatment of synaptoneurosomes, caused a 75 kDa dicer fragment to appear in a calpain-dependent manner. The findings support a model whereby acute neuronal stimulation at excitatory synapses increases intracellular calcium, which activates calpain, which liberates dicer and eIF2c bound to PSDs. This supports the hypothesis that dicer could be involved in synaptic plasticity."
    }
}