.. _examples: Example Queries and Results =========================== The following are examples of valid DSL queries and the type of JSON data they return. See also the :doc:`data-sources` section for examples of how query using relationships between different source documents. .. seealso:: The `Dimensions API Lab on Github `_ contains more tutorials and Jupyter notebooks. Minimal valid query +++++++++++++++++++ .. literalinclude:: examples/minimal/query.dsl :language: none Retrieves the latest scientific research grants. .. literalinclude:: examples/minimal/results.json :language: json Searching records +++++++++++++++++++ .. seealso:: Definitions of :term:`record` and :term:`source` Search terms ************* .. seealso:: Documentation for :ref:`"for" `, Definition of :term:`search term` .. literalinclude:: examples/search-terms/query.dsl :language: none .. literalinclude:: examples/search-title-abstract/query.dsl :language: none Retrieves scholarly publications matching the search term "AIDS". .. literalinclude:: examples/search-terms/results.json :language: json Filters ******* .. seealso:: Documentation for :ref:`"where" ` Simple filters -------------- .. seealso:: Documentation for :ref:`simple filters `, definition of :term:`field` .. literalinclude:: examples/filters-simple/query.dsl :language: none :emphasize-lines: 2 Retrieves the first N publications after restricting the search set to only those records published in 2010 or earlier. .. literalinclude:: examples/filters-simple/results.json :language: json Boolean operators ----------------- .. seealso:: Documentation for :ref:`boolean operators ` in filters .. literalinclude:: examples/filters-complex/query.dsl :language: none :emphasize-lines: 2 Retrieves HIV-related grants from any funder which started after 2010 and no later than 2012 (i.e. started in 2011 or 2012), along with HIV-related grants from any year which were funded by the European Commission. (For display purposes, grant records include only the title, start year, and funding organization name, and are sorted by title in reverse alphabetical order. See :ref:`returning-records` below for explanation of these features.) .. literalinclude:: examples/filters-complex/results.json :language: json Partial-match filters --------------------- .. seealso:: Documentation for :ref:`partial-string-matching` .. literalinclude:: examples/filters-partial/query.dsl :language: none :emphasize-lines: 2 Retrieves research organization of grants, restricted to organizations whose names include the terms "National" and "Blood", in any spacing/order. .. literalinclude:: examples/filters-partial/results.json :language: json Contrast this with the exact-match filter in the query ``search grants where research_org.name="National Blood" return research_orgs:[name]`` (using the ``=`` operator instead of ``~``), which would result in an error because there is no known organization with the exact name "National Blood". .. _range-filters: Ranges ------ .. seealso:: Documentation for :ref:`range and list filters ` .. literalinclude:: examples/filters-range/query.dsl :language: none :emphasize-lines: 2 Retrieves HIV-related publications which were published between the years 2005 and 2015, inclusive. .. literalinclude:: examples/filters-range/results.json :language: json The range filter syntax is a shorthand notation for convenience. The same results could be retrieved using the following equivalent query: .. code-block:: none :emphasize-lines: 2 search publications for "HIV" where year>=2005 and year<=2015 return publications Lists ----- .. seealso:: Documentation for :ref:`range and list filters ` .. literalinclude:: examples/filters-list/query.dsl :language: none :emphasize-lines: 2 Retrieves grants related to water ("H2O") where the language of original publication is either German ("de"), Chinese ("zh"), or French ("fr"). .. literalinclude:: examples/filters-list/results.json :language: json The list syntax is a shorthand notation for convenience. The same results could be retrieved using the following equivalent query: .. code-block:: none search grants for "H2O" where language="de" or language="zh" or language="fr" return grants Entity metadata --------------- .. seealso:: Documentation for :ref:`entity filters `, Definition of :term:`entity` Simple entity filters ~~~~~~~~~~~~~~~~~~~~~ .. literalinclude:: examples/filters-entity/query.dsl :language: none :emphasize-lines: 2 Retrieves grants related to Zika that were funded by the organization(s) whose acronym is "NHLBI", by first searching all the known funders to find the ID number(s) for the organization(s) that have this acronym. In this case, there is only one matching funding organization, the (US) National Heart, Lung, and Blood Institute. .. literalinclude:: examples/filters-entity/results.json :language: json Complex entity filters ~~~~~~~~~~~~~~~~~~~~~~ Like all filters, entity metadata filters may be combined using boolean operators and parentheses, as seen in the following example: .. literalinclude:: examples/filters-entity-complex/query.dsl :language: none :emphasize-lines: 2-3 Retrieves publications related to women that were published between 2000 and 2015 (inclusive) by research organizations in the countries of Senegal or the Gambia. .. literalinclude:: examples/filters-entity-complex/results.json :language: json Both **** .. literalinclude:: examples/terms-filters/query.dsl :language: none .. literalinclude:: examples/terms-filters-reversed/query.dsl :language: none Both queries retrieve publications matching the search term "AIDS", but only those publications published in the year 2010 are included in the set to be ranked against the search term. The two queries are equivalent; the :ref:`for ` and :ref:`where ` phrases are independent, and can occur in either order. .. note:: As noted in the documentation of :ref:`where-filters`, filtering is performed before ranking records by similarity with the :term:`search term`. .. literalinclude:: examples/terms-filters/results.json :language: json .. _returning-records: Returning records +++++++++++++++++++ .. seealso:: Documentation for :ref:`results-phrase`, Definition of :term:`record` Fields ****** .. seealso:: Documentation for :ref:`specifying fields ` Fieldsets --------- .. seealso:: Documentation for :ref:`named fieldsets `, Definition of :term:`fieldset` :ref:`Supported fieldsets ` for each :term:`source` .. _fieldsets-reduced: Basics ~~~~~~ .. literalinclude:: examples/fieldsets-reduced/query.dsl :language: none .. literalinclude:: examples/fieldsets-reduced-default/query.dsl :language: none In both queries, the JSON results will only include a limited, predefined set of fields (the ``basics`` :term:`fieldset`) for each grant (in this case, a single grant specified by ID). These two queries are equivalent, as the language uses ``basics`` as the default fieldset if no fields are specified. .. literalinclude:: examples/fieldsets-reduced/results.json :language: json .. _fieldsets-detailed: Detailed ~~~~~~~~ .. literalinclude:: examples/fieldsets-detailed/query.dsl :language: none In contrast to :ref:`the previous query `, the JSON results include all fields predefined as part of the larger ``detailed`` fieldset. .. literalinclude:: examples/fieldsets-detailed/results.json :language: json Arbitrary fieldlist ------------------- .. seealso:: Documentation for :ref:`specifying arbitrary fields `, Definition of :term:`field` :ref:`Supported fields ` for each :term:`source` .. literalinclude:: examples/fields-brackets/query.dsl :language: none The JSON results for each grant only contain the three specified fields ``id``, ``title``, and ``date``. .. literalinclude:: examples/fields-brackets/results.json :language: json Sorting ******* .. seealso:: Documentation for :ref:`"sort by" `, Definition of :term:`field` :ref:`Supported fields ` for each :term:`source` .. literalinclude:: examples/sorting-works/query.dsl :language: none Returns grants sorted by the value of a :term:`field` on the :term:`record`, in this case the grant ID numbers (in descending order), as opposed to the default date-based sorting. .. note:: At the moment it is not possible to specify the sorting direction (ascending or descending), only the sorting indicator; the direction is always descending for the time being. This will be changed in a future version of the language. .. literalinclude:: examples/sorting-works/results.json :language: json Returning facets ++++++++++++++++ .. seealso:: Documentation for :ref:`results-phrase`, Definition of :term:`facet` :ref:`Supported facetable fields ` for each :term:`source` Simple facets ************* .. literalinclude:: examples/facets-simple/query.dsl :language: none Retrieves grant funders sorted by the number (``count``) of grants each has funded. Does not retrieve any grant records themselves, only the aggregation over the ``funders`` :term:`facet` of the ``grants`` :term:`source`. .. literalinclude:: examples/facets-simple/results.json :language: json Fields (metadata) ***************** .. seealso:: Documentation for :ref:`specifying fields `, Definitions for :term:`entity`, :term:`field`, :term:`fieldset` :ref:`Supported fields/fieldsets ` for each :term:`entity` .. literalinclude:: examples/facets-fields/query.dsl :language: none In addition to computing grant count aggregations for the specified facets, fetches the metadata associated with each entity according to the fields specified, and displays this information alongside the aggregations in the facet results. .. literalinclude:: examples/facets-fields/results.json :language: json Facets and records ******************** .. seealso:: Definitions of :term:`record`, :term:`source`, :term:`facet` .. literalinclude:: examples/facets-works/query.dsl :language: none Retrieves grant documents, as well as funders and research organizations of grants (both sorted by the count of grants funded). .. literalinclude:: examples/facets-works/results.json :language: json Aggregations ************ .. seealso:: Documentation for :ref:`"aggregate" `, Definition of :term:`indicator` :ref:`Supported indicators ` for each :term:`source` Single indicator ------------------ .. literalinclude:: examples/aggr-single/query.dsl :language: none Differs from ``search grants return funders, years`` only in the fact that in addition to tallying the counts of grants for each funder/year, also computes the total funding amount (the sum of grant funding amounts in USD) for each funder/year, and lists this in the results. However, the funders and years are still sorted by count. .. literalinclude:: examples/aggr-single/results.json :language: json .. _aggr-multi: Multiple indicators --------------------- .. literalinclude:: examples/aggr-multi/query.dsl :language: none Returns funders of publications, but in addition to tallying the counts of publications funded by each funder, also computes the average Relative Citation Ratio (RCR) score and median Altmetric Attention Score across all publications funded by that funder, and includes these aggregations in the facet results. However, funders are still sorted by the count of publications funded. .. literalinclude:: examples/aggr-multi/results.json :language: json Sorting ******* .. seealso:: Documentation for :ref:`"sort by" `, Definition of :term:`indicator` :ref:`Supported indicators ` for each :term:`source` .. literalinclude:: examples/sorting-facets/query.dsl :language: none Returns the same results as :ref:`the previous query `, except that now the funders are sorted by their average RCR score (descending) instead of by the default indicator, publication count (though counts are still tallied and included in the results). .. literalinclude:: examples/sorting-facets/results.json :language: json Naming/grouping results +++++++++++++++++++++++ .. _ex-alias: Aliases ******* .. seealso:: Documentation for :ref:`result aliases ` .. literalinclude:: examples/alias/query.dsl :language: none Retrieves the same results as ``search grants return grants return funders``, but the results are listed under the specified aliases of ``"projects"`` and ``"entity_funder"``, respectively, instead of the default names ``"grants"`` and ``"funders"`` . .. literalinclude:: examples/alias/results.json :language: json .. _ex-groups: Groups ****** .. seealso:: Documentation for :ref:`result groups ` .. literalinclude:: examples/group/query.dsl :language: none Retrieves the same results as ``search grants return grants return funders aggregate funding return research_orgs, research_org_countries``, but organizes the results into two groups as specified: the ``docs`` group, containing ``grants``, and the ``facets`` group, containing ``funders``, ``research_orgs``, and ``research_org_countries``. .. literalinclude:: examples/group/results.json :language: json Aliases within Groups ********************* .. literalinclude:: examples/alias-group/query.dsl :language: none Retrieves the same results as ``search grants return grants return funders aggregate funding return research_orgs``, but names and groups the results as specified in the query and illustrated in the results below. .. literalinclude:: examples/alias-group/results.json :language: json Limiting/paging results +++++++++++++++++++++++ .. seealso:: Documentation for :ref:`"limit" and "skip" ` .. _limit: Limit ***** .. literalinclude:: examples/limit/query.dsl :language: none Returns the top 5 grants matching the query, and the top 3 funders for all grants matching the query. .. literalinclude:: examples/limit/results.json :language: json Skip **** .. literalinclude:: examples/paging/query.dsl :language: none Like :ref:`the previous query `, returns 5 grants and 3 grant funders. However, whereas the previous query returned the top 5 grants and top 3 funders, this query returns the grants in 16th-20th position in the search results, and the funders in 10th-12th position. These results might represent page 4 in a series of results pages where 5 grants and 3 funders are listed per page. .. literalinclude:: examples/paging/results.json :language: json Indicators Aggregations ++++++++++++++++++++++++++++ This section provides various examples of how to extract common performance indicators using the Dimensions API. .. note:: In the following examples, publications are aggregated by funder, however this is just for demonstrative purposes. It is also possible to aggregate by any other facet field. For a complete list of fields that support facets, see the :ref:`data-sources`. .. seealso:: Documentation for :ref:`"aggregate" `, Definition of :term:`indicator` :ref:`Supported indicators ` for each :term:`source` Publications Output ******************** Aggregated number of publications per entity .. code-block:: none search publications return funders aggregate count Citations *********** Number of citations per publication .. code-block:: none search publications return publications [doi + times_cited] sort by times_cited **Aggregated** total number of citations .. code-block:: none search publications return funders aggregate citations_total sort by citations_total **Arithmetic mean** number of citations .. code-block:: none search publications return funders aggregate citations_avg sort by citations_avg **Median** number of citations .. code-block:: none search publications return funders aggregate citations_median sort by citations_median **Recent** citations per publication .. code-block:: none search publications return publications [doi + recent_citations] sort by recent_citations .. note:: Recent citation refers to the number of citations accrued in the last two year period. A single value is stored per document and the year window rolls over in July. **Aggregated** number of **recent** citations .. code-block:: none search publications return funders aggregate recent_citations_total sort by recent_citations_total **Relative citation ratio** (RCR) per publication .. code-block:: none search publications return publications [doi + relative_citation_ratio] sort by relative_citation_ratio **Arithmetic mean** of RCR .. code-block:: none search publications return funders aggregate rcr_avg sort by rcr_avg **Field citation ratio** (FCR) per publication .. code-block:: none search publications return publications [doi + field_citation_ratio] sort by field_citation_ratio **Geometric mean** of FCR .. code-block:: none search publications return funders aggregate fcr_gavg sort by fcr_gavg Number of publications with **at least** `n=X` citations, in the example below `n=10` .. code-block:: none search publications where times_cited >= 10 return funders Altmetric ********** **Altmetric Attention Score** per publication .. code-block:: none search publications return publications [doi + altmetric] sort by altmetric **Median** Altmetric Attention Score .. code-block:: none search publications return funders aggregate altmetric_median sort by altmetric_median **Arithmetic mean** Altmetric Attention Score .. code-block:: none search publications return funders aggregate altmetric_avg sort by altmetric_avg Collaboration Indicators ************************** Number of publications with **exactly one** researcher. .. code-block:: none search publications where count(researchers) = 1 return funders Number of publications with **more than one** researcher. .. code-block:: none search publications where count(researchers) > 1 return funders **International** collaborations: number of publications with more than one author and affiliations located in more than one country. .. code-block:: none search publications where count(researchers) > 1 and count(research_org_countries) > 1 return funders **Domestic** collaborations: number of publications with more than one author and more than one affiliation located in exactly one country. .. code-block:: none search publications where count(researchers) > 1 and count(research_org_countries) = 1 return funders **Hyper-authorship**: number of publications with at least `n=X` authors, in the example below the number of authors is `n=25` .. code-block:: none search publications where count(researchers) >= 25 return funders Open Access Indicators *********************** **All OA**: a free version of the publication is available (publication is either Gold, Hybrid, Bronze or Green OA). .. code-block:: none search publications where open_access= "oa_all" return funders **Gold**: publication is published in a fully open access journal (this includes all publications with a Gold OA status in Unpaywall and those on our own fully OA list of journals). .. code-block:: none search publications where open_access= "gold" return funders **Hybrid**: publication freely available under an open licence in a paid-access journal (Unpaywall OA status = Hybrid). .. code-block:: none search publications where open_access= "hybrid" return funders **Bronze**: publication freely available on publisher's website, but without an open licence (Unpaywall OA status = Bronze). .. code-block:: none search publications where open_access= "bronze" return funders **Green**: publication freely available in an OA repository (Unpaywall OA status = Green, or publication type in Dimensions = Preprint). .. code-block:: none search publications where open_access= "green" return funders **Closed**: freely available version has been identified (publication is neither Gold, Hybrid, Bronze nor Green OA). .. code-block:: none search publications where open_access= "closed" return funders Calculating composite indicators ********************************* The following examples showcase how different individual indicators can be combined to obtain further insight into the Dimensions data. .. note:: These examples reflect the data at specific time point. Therefore we would expect the calculated values from the following queries to change over time, as the coverage of Dimensions data increases. Calculating percentage of open access papers for a specific funder ------------------------------------------------------------------------- In this example we first search for all publications funded by the National Cancer Institute (NCI) and filter for a specific type of open access. In this case we are selecting documents that have a version of the record that is free under an open licence from a full OA, also known as Gold Open Access. .. code-block:: none search publications where open_access = "gold" and funders.name="National Cancer Institute" return publications From looking at the stats component of the returned data, we can see that there are 35858 documents that match this query. After that we need to determine what is the total publication output for the funder. .. code-block:: none search publications where funders.name="National Cancer Institute" return publications From the query above we get that there are 531281 publications associated with funding from the NCI. Finally by simply calculating the ratio between open access publications and all publications, we can conclude that 6.75% of the publications funded by the NCI are Gold Open Access. Calculating publications per active grant for specific fields of research --------------------------------------------------------------------------- The ratio of publications to active grants can provide insights across different disciplines and shed light on aspects obscured by funding amounts. To calculate this, it is necessary to perform a couple of queries and then manually calculate the ratio. For the sake of simplicity, let us look into a 3 year funding period (2015-2017) for Monash University in Australia (`grid.1002.3`). Taking advantage of the fields of research categorisation system (FOR) we can line up specific fields of study across both publications and grants. First, we search for all Monash University publications aggregated by field of research and published after the first active year of grant funding: .. code-block:: none search publications where research_orgs.id = "grid.1002.3" and year>=2015 return FOR Next, we can select a couple of categories and store their publication output. After that we perform a similar search on those categories, but this time across grant content. .. code-block:: none search grants where research_orgs.id = "grid.1002.3" and active_year in [2015:2017] and FOR.name="1701 Psychology" return active_year As you can see from the query, we are looking at grants that were active between 2015 and 2017 for the same university in the field of psychology. The same can be done for another research area like pharmacology. .. code-block:: none search grants where research_orgs.id = "grid.1002.3" and active_year in [2015:2017] and FOR.name="1115 Pharmacology and Pharmaceutical Sciences" return active_year Based on these three queries we find that the number of grants for psychology and pharmacology are 193 and 148 respectively. However there is a significant difference in the number of publications, as we get 1896 for psychology and only 277 for pharmacology. Finally by calculating the ratio between grants and publication we can see in this case, that research in psychology produces approximately 5 times as many publications as its pharmacological counterpart.