Functions Syntax¶

The DSL contains several functions that can be used to perform non-search operations. For example, functions can be used to check if an object exist, or to automatically extract categories from a piece of text.

Basic functions structure¶

Each function call starts with a function name followed by parenthesis, in between which arguments are placed, separated by commas.

For example, calling function extract_grants looks like this:

extract_grants  ("R01HL117329", fundref="100000050")
-------------------------------------------------------
<function name>:(positional arguments, named arguments)

The DSL supports two types of arguments:

Positional Arguments
These are placed without any name. They are just values. These are completely optional and can be replaced by named arguments. Their purpose is mainly to simplify calling functions with just one or two arguments, by omitting the argument name.

Named Arguments
Named arguments are always put after positional arguments and their order is not important. In the example above, one could also write extract_grants(fundref=”100000050”, grant_number=”R01HL117329”).

Arguments can be of various type, for example string or integer. See below for the full list of supported functions.

Function: check_researcher_ids¶

Checks the status for researcher IDs. Uses researcher IDs as input, in the form of a list of strings, and returns an object with a key researcher_ids. Items provided as a list under this key contain information about each provided ID on the input. They are objects with three keys: They are objects with three keys:

id - is the input researcher ID

obsolete - 0 means that the researcher ID is still active. In this case no additional information is provided. 1 means that the researcher ID is no longer valid, in this case see redirect field for further information.

redirect - if empty, it means that the researcher with this ID was deleted. If it contains a single value, it means that that value is a new researcher ID into which the current one was redirected. If multiple values are available, it means that the original researcher ID was split to these multiple IDs.

Examples
check_researcher_ids(["ur.011301404166.06", "ur.07433432213.73"])

Arguments¶

Argument Name	Argument Type	Optional?
`researcher_ids`	`string_list`

Function: classify¶

This function retrieves suggested codes for any text.

Note

Our classifier is optimised to work with titles and abstracts, that is, fairly short texts. When using it with longer texts, it may produce unexpected or no results.

Warning

When using the API to classify documents, you may sometimes find that the same document will have different categories assigned to it from what is listed in Dimensions (if the document is already indexed in Dimensions). This happens because pre-computed document classifications often derive from multiple data enrichment steps aimed at improving the category precision e.g. by looking at the overall topic area for a journal. As these enrichment steps are not carried out in the API classifications, differences can arise despite both these and Dimensions using the same classification algorithms.

Currently, the following classification systems are supported:

Fields of Research (FOR)

Research, Condition, and Disease Categorization (RCDC)

Health Research Classification System Health Categories (HRCS_HC)

Health Research Classification System Research Activity Classifications (HRCS_RAC)

Health Research Areas (HRA)

Broad Research Areas (BRA)

Examples
classify(
    title="Burnout and intentions to quit the practice among community pediatricians: associations with specific professional activities",
    abstract="BACKGROUND: Burnout is an occupational disease expressed by loss of mental and physical energy due to prolonged and unsuccessful coping with stressors at work. A prior survey among Israeli pediatricians published in 2006 found a correlation between burnout and job structure match, defined as the match between engagement with, and satisfaction from, specific professional activities. The aims of the present study were to characterize the current levels of burnout and its correlates among community pediatricians, to identify changes over time since the prior survey, and to identify professional activities that may reduce burnout. METHODS: A questionnaire was distributed among pediatricians both at a medical conference and by a web-based survey. RESULTS: Of the 518 pediatricians approached, 238 (46%) responded to the questionnaire. High burnout levels were identified in 33% (95% CI:27-39%) of the respondents. Higher burnout prevalence was found among pediatricians who were not board-certified, salaried, younger, and working long hours. The greater the discrepancy between the engagement of the pediatrician and the satisfaction felt in the measured professional activities, the greater was the burnout level (p < 0.01). The following activities were especially associated with burnout: administrative work (frequent engagement, disliked duty) and research and teaching (infrequent engagement, satisfying activities). A comparison of the engagement-satisfaction match between 2006 and 2017 showed that the discrepancy had increased significantly in research (p < 0.001), student tutoring (P < 0.001), continuing medical education and participation in professional conferences (P = 0.0074), management (p = 0.043) and community health promotion (P = 0.006). A significant correlation was found between burnout and thoughts of quitting pediatrics or medicine (p < 0.001). CONCLUSIONS: Healthcare managers should encourage diversification of the pediatrician's job by enabling greater engagement in the identified anti-burnout professional activities, such as: participation in professional consultations, management, tutoring students and conducting research.",
    system="FOR")

Arguments¶

Argument Name	Argument Type	Optional?
`title`	`string`
`abstract`	`string`
`system`	`string`

Function: extract_concepts¶

Extract concepts from any text. Text input is processed and extracted concepts are returned as an array of strings ordered by their relevance.

Examples
extract_concepts("text of abstract")

Arguments¶

Argument Name	Argument Type	Optional?
`text`	`string`

Function: extract_grants¶

Extract grant Dimensions ID from provided parameters. Grant number must be provided with either a fundref or a funder name as an argument. Returns an object with a key grant_id and value of either an identified Dimensions grant ID or null, if no grant was identified.

Examples
extract_grants(grant_number="R01HL117329", fundref="100000050")
extract_grants(grant_number="HL117648", funder_name="NIH")

Arguments¶

Argument Name	Argument Type	Optional?
`grant_number`	`string`
`fundref`	`string`	✓
`funder_name`	`string`	✓