Skip to content

Commit

Permalink
docs: move README examples to new docs
Browse files Browse the repository at this point in the history 
Resolves: #69
  • Loading branch information
@danielnsilva
danielnsilva committed Dec 29, 2024
1 parent c293692 commit 0f984f3
Showing 1 changed file with 96 additions and 85 deletions.
181 changes: 96 additions & 85 deletions docs/source/usage.rst
View file
Original file line number Diff line number Diff line change
@@ -1,23 +1,63 @@
:tocdepth: 4

=====
Usage
-----
=====

Basics
^^^^^^
======

Paginated results
~~~~~~~~~~~~~~~~~
-----------------

Methods that return lists of items, such as papers or authors, will paginate through results, returning the list of papers or authors up to the bound limit (default value is 100). To retrieve additional pages, you can fetch them one by one or iterate through all results.

For example, iterating over all results for a paper search:

.. code-block:: python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
results = sch.search_paper('Computing Machinery and Intelligence')
all_results = [item for item in results]
Pagination is handled automatically when iterating, retrieving all available items. However, if only the first batch of results is needed, you can access them directly using the `items` property of the result object, avoiding extra API calls:

.. code-block:: python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
results = sch.search_paper('Computing Machinery and Intelligence')
first_page = results.items
To fetch the next page of results, use the `next_page()` method. This method appends the next batch of items to the current list, as shown in the example below:

.. code-block:: python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
results = sch.search_paper('Computing Machinery and Intelligence')
results.next_page()
first_two_pages = results.items
Asynchronous requests
~~~~~~~~~~~~~~~~~~~~~
---------------------

Authenticated requests
~~~~~~~~~~~~~~~~~~~~~~
----------------------

If you have an API key, you can pass it as an argument to the main class. This will allow you to make authenticated requests.

.. code-block:: python
from semanticscholar import SemanticScholar
sch = SemanticScholar(api_key='your_api_key_here')
Paper and Author
^^^^^^^^^^^^^^^^
================

Paper
~~~~~
-----

To access paper data:

Expand All @@ -26,16 +66,9 @@ To access paper data:
from semanticscholar import SemanticScholar
sch = SemanticScholar()
paper = sch.get_paper('10.1093/mind/lix.236.433')
print(paper.title)
Output:

.. code-block:: bash
Computing Machinery and Intelligence
Author
~~~~~~
------

To access author data:

Expand All @@ -44,16 +77,9 @@ To access author data:
from semanticscholar import SemanticScholar
sch = SemanticScholar()
author = sch.get_author(2262347)
print(author.name)
Output:

.. code-block:: bash
Alan M. Turing
Retrieve multiple items at once
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------------

You can fetch up to 1000 distinct papers or authors in one API call. To do that, provide a list of IDs (array of strings).

Expand All @@ -69,16 +95,6 @@ Get details for multiple papers:
'0f40b1f08821e22e859c6050916cec3667778613'
]
results = sch.get_papers(list_of_paper_ids)
for item in results:
print(item.title)
Output:

.. code-block:: bash
Improving Third-Party Audits and Regulatory Compliance in India
How Much Should We Trust Differences-in-Differences Estimates?
The Miracle of Microfinance? Evidence from a Randomized Evaluation
Get details for multiple authors:

Expand All @@ -88,19 +104,9 @@ Get details for multiple authors:
sch = SemanticScholar()
list_of_author_ids = ['3234559', '1726629', '1711844']
results = sch.get_authors(list_of_author_ids)
for item in results:
print(item.name)
Output:

.. code-block:: bash
E. Dijkstra
D. Parnas
I. Sommerville
Search by keyword
~~~~~~~~~~~~~~~~~
-----------------

To search for papers by keyword:

Expand All @@ -109,13 +115,6 @@ To search for papers by keyword:
from semanticscholar import SemanticScholar
sch = SemanticScholar()
results = sch.search_paper('Computing Machinery and Intelligence')
print(f'{results.total} results.', f'First occurrence: {results[0].title}.')
Output:

.. code-block:: bash
492 results. First occurrence: Computing Machinery and Intelligence.
.. warning::

Expand All @@ -128,38 +127,42 @@ To search for authors by name:
from semanticscholar import SemanticScholar
sch = SemanticScholar()
results = sch.search_author('Alan M. Turing')
print(f'{results.total} results.', f'First occurrence: {results[0].name}.')
Output:
Query parameters for search papers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: bash
``year: str``
"""""""""""""

4 results. First occurrence: A. Turing.
Restrict results to a specific publication year or a given range, following the patterns '{year}' or '{start}-{end}'. Also you can omit the start or the end. Examples: '2000', '1991-2000', '1991-', '-2000'.

Recommended papers
^^^^^^^^^^^^^^^^^^
.. code-block:: python
To get recommended papers for a given paper:
from semanticscholar import SemanticScholar
sch = SemanticScholar()
results = sch.search_paper('software engineering', year=2000)
``fields_of_study: list``
"""""""""""""""""""""""""

Restrict results to a given list of fields of study. Check `official documentation <https://api.semanticscholar.org/api-docs/graph#tag/Paper-Data/operation/get_graph_paper_relevance_search>`_ for a list of available fields.

.. code-block:: python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
results = sch.get_recommended_papers('10.2139/ssrn.2250500')
for item in results:
print(item.title)
results = sch.search_paper('software engineering', fields_of_study=['Computer Science','Education'])
Output:
Recommended papers
==================

.. code-block:: bash
To get recommended papers for a given paper:

Microcredit: Impacts and promising innovations
MIT Open Access
The Econmics of Badmouthing: Libel Law and the Underworld of the Financial Press in France before World War I
Give Biden a 6-Point
Getting more value from Australian Intergenerational Reports
...
Structural Change and Economic Dynamics
.. code-block:: python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
results = sch.get_recommended_papers('10.2139/ssrn.2250500')
To get recommended papers based on a list of positive and negative paper examples:

Expand All @@ -170,25 +173,33 @@ To get recommended papers based on a list of positive and negative paper example
positive_paper_ids = ['10.1145/3544585.3544600']
negative_paper_ids = ['10.1145/301250.301271']
results = sch.get_recommended_papers_from_lists(positive_paper_ids, negative_paper_ids)
for item in results:
print(item.title)
Output:
You can also omit the list of negative paper IDs; in which case, the API will return recommended papers based on the list of positive paper IDs only.

.. code-block:: bash
Common query parameters
=======================

BUILDING MINIMUM SPANNING TREES BY LIMITED NUMBER OF NODES OVER TRIANGULATED SET OF INITIAL NODES
Recognition of chordal graphs and cographs which are Cover-Incomparability graphs
Minimizing Maximum Unmet Demand by Transportations Between Adjacent Nodes Characterized by Supplies and Demands
Optimal Near-Linear Space Heaviest Induced Ancestors
Diameter-2-critical graphs with at most 13 nodes
...
Advanced Heuristic and Approximation Algorithms (M2)
``fields: list``
----------------

You can also omit the list of negative paper IDs; in which case, the API will return recommended papers based on the list of positive paper IDs only.
The list of the fields to be returned. By default, the response includes all fields. As explained in `official documentation <https://api.semanticscholar.org/api-docs/graph>`_, fields like `papers` (author lookup and search) may result in responses bigger than the usual size and affect performance. Consider reducing the list. Check `official documentation <https://api.semanticscholar.org/api-docs/graph>`_ for a list of available fields.

Common query parameters
^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
results = sch.search_paper('software engineering', fields=['title','year'])
``limit: int``
--------------

This parameter represents the maximum number of results to return on each call to API. According to `official documentation <https://api.semanticscholar.org/api-docs/graph>`_, setting a smaller limit reduces output size and latency. The default value is 100.

.. code-block:: python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
results = sch.search_paper('software engineering', limit=5)
Troubleshooting
^^^^^^^^^^^^^^^
===============

0 comments on commit 0f984f3

Please sign in to comment.