sciencerio / sciencer-toolkit

A smarter way to find articles.

Sciencer Toolkit

A smarter way to find articles.

About - Usage - Roadmap - Contributing

Collectors - Expanders - Filters - Providers

---

About

Sciencer Toolkit enables researchers to programmatically conduct a literature review using an intuitive yet flexible interface.

At its core, Sciencer collects sets of papers. The initial set of papers is created through the use of Collectors (e.g. paper doi, author name). Then, Sciencer iteratively finds new papers using Expanders (e.g. authors, citations, references). Finally, new found papers need to satisfy a series of Filters in order to be accepted into the current set. Being iterative in nature, Sciencer allows you to repeat the above steps has many times as you'd like.

This project was motivated by the absence of tools to automate systematic reviews using clear and well-defined criteria. Still, for literature reviews that do not need to follow specific criteria, there are a several tools that can help to discover new papers.

Usage

# Create the Sciencer Core Component
sciencer = Sciencer()

# Define provider
sciencer.add_provider(SemanticScholarProvider())

# Define collectors
## this collector will gather all known papers authored by "John Doe" into de set
sciencer.add_collector(sciencer.collectors.CollectByAuthorID("John Doe"))
## this collector will collect the paper with DOI "1234567890" into the set
sciencer.add_collector(sciencer.collectors.CollectByDOI("1234567890"))
## this collector will collect the papers with 
sciencer.add_collector(sciencer.collectors.CollectByTerms(["Term 1", "Term 2", "Term 3"]))

# Define expanders
## this expander will gather all known papers written by authors in the current set.
sciencer.add_expander(sciencer.expanders.ExpandByAuthors())
## this expander will gather all the referenced papers
sciencer.add_expander(sciencer.expanders.ExpandByReferences())
## this expander will gather all the cited papers
sciencer.add_expander(sciencer.expanders.ExpandByCitations())

# Define filters
## this filter will reject papers that were published before 2010 and after 2030
sciencer.add_filter(sciencer.filters.FilterByYear(min_year=2010, max_year=2030))
## this filter will reject all the papers that do not have the word social on the abstract
sciencer.add_filter(sciencer.filters.FilterByAbstract("social"))
## this filter will reject all the papers that do not have the field of study Computer Science
sciencer.add_filter(sciencer.filters.FilterByFieldOfStudy("Computer Science"))

# Run one iteration
results = sciencer.iterate()

For more examples on how to use the Sciencer toolkit, please check the directory examples/.

(back to top)

Collectors

Name	Description	Parameters
Author ID	Collects all the papers written by an author	Authors's SemanticScholar ID
Paper DOI	Collects a paper by its DOI	Paper's DOI
Terms	Collects papers by terms	Query Terms Maximum Number of Papers

(back to top)

Expanders

Name	Description
Authors	Expands a paper by its authors
References	Expands a paper by its references
References	Expands a paper by its citations

(back to top)

Filters

Name	Description	Parameters
By Year	Filters a paper by its year	The lowest acceptable year (inclusive) The highest acceptable year (inclusive)
By Abstract Words	Filters a paper by its abstract	The collection of words the abstract should include (at least one)
By Field Of Study	Filters a paper by its field of study	The field of study the paper should have

(back to top)

Providers

Name	Provider	Features
Semantic Scholar	Semantic Scholar Academic Graph API	Search by Author (Name, S2ID) Search By Paper ID (S2ID, DOI, ArXiv, MAG, ACL, PubMed, Corpus)
DBLP	DBLP Search API	Work in Progress

(back to top)

Roadmap

• Create Paper's and Author's Cache
• Add Bulk Expanders (to avoid redundancy)
• Add support for multithreading
• Add Collectors
  • Add Collect by Venue/Proceedings
• Add Expanders
  • Add Expand by Citations
  • Add Expand by References
  • Add Expand by Venue/Proceedings
• Add Filters
  • Add Filter by Number of Citations
  • Add Filter by Topic
  • Add Filter by Keywords
• Add Compound Filters
• Add utility to write results to a *.csv

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Want to add a new provider, filter or expander? Looking to improve the core functionality of sciencer toolkit. We look forward to include your contributions in the toolkit! If you have a suggestion that would improve the toolkit just send us a Pull Request!

If you are looking for an additional collector/filter/expander/provider or just want to report a bug, you can also simply open an issue with the tag "enchament" or "bug", respectively.

(back to top)

sciencer-toolkit's Issues

Consider if `PaperId` should in fact be a class

I was looking into this and was questioning if the class PaperIDs makes sense existing as a separate class, or if we should just move it into the paper itself.

Originally posted by @RicardoEPRodrigues in #23 (comment)

Remove LogCallbacks from core

By default, a new LogCallbacks is added to Sciencer.iteration.
Instead, the developer should decide whether to use it or not.

As such, the LogCallbacks must not be added by default to the iteration's callbacks.

Changing models to dataclasses

Consider changing the Paper and PapersIDs models implementation to dataclasses (ref). Only works on python 3.7 or above.

Implementing these models as dataclasses will remove the complex interfaces they currently have.

Expansion Diagram

One of the motivators that lead to the development of Sciencer was the necessity to formalize the expansion flowchart of a systematic review. Besides the source code used to define an expansion, a visual representation should also be made available.

Preferred Reporting Items for Systematic Reviews and Meta-Analyses (PRISMA) has been widely used to report systematic reviews and meta analyses across several research fields. PRISMA flowchart describes not only the criteria for the systematic review but also the results.

Consider adding a method to generate a flowchart reporting the expansion to Sciencer Toolkit.

Filters too restrict when paper lack some properties

When using Filters to check paper's validity, the developer should define the default validity when the necessary properties are not available.

Consider adding an optional parameter to the constructor of the adequate Filters:
FilterByAbstract(word='keyword', accept_when_empty=True)

Limit S2 query by terms size of requests

While using the /paper/search entrypoint, the sum of the limit and offset must be less than 10000

The sum of offset and limit must be < 10000 (ref)

The semantic scholar provider crashes when the limit + offset are greater than 10000.
Consider (1) adding a stop condition while fetching the papers and (2) constraining the maximum number of papers to 10000.

Update CollectByTerms to reduce requests

Currently the CollectByTerms performs 1 request to the API (get_paper_by_terms), which returns N papers according to the query. Then, it performs N requests to get all the information of each paper (get_paper_by_id). Although there is a parameter to choose the output fields of the first query, there is no way to retrieve the ids of references and citations. I believe that is the reason for having those N extra requests inside the CollectByTerms.

I would like to suggest or discuss the possibility of not doing those N extra requests inside the CollectByTerms and, probably, only perform them in the expanders (where they will be needed?!). I think Sciencer was designed having in mind a pipeline that starts with a small set of papers, then it could be expanded and possibly be filtered. However, another possibility is to start with a huge set of papers and then start filtering and possibly expanding later. In those cases doing so many requests takes a huge time and most of those papers will probably be filtered afterwards, which means wasted time.

[Feature Request] Exporting in known formats (RIS, Bibtex, Endnote)

I would like to see integrated (perhaps in an Utils class) the ability to export the iterations in a format compatible with reference management software, such as RIS, Bibtex, or Endnote.

KeyError: 'data' in semantic_scholar_provider.py line 151

An error was launched when running the examples/example_1_hello_world.py (I provided an API key, IDK if it is relevant). It seems the response did not have a "data" field.

Traceback (most recent call last):
  File "/home/ricardo/Documents/Projects/sciencer-toolkit/./examples/example_1_hello_world.py", line 77, in <module>
    first_batch = s.iterate(
  File "/home/ricardo/Documents/Projects/sciencer-toolkit/venv/lib/python3.9/site-packages/sciencer/core.py", line 249, in iterate
    paper_after_expansion.update(expander.execute(
  File "/home/ricardo/Documents/Projects/sciencer-toolkit/venv/lib/python3.9/site-packages/sciencer/expanders/expand_by_authors.py", line 32, in execute
    author_papers = provider.get_papers_by_author(author_id)
  File "/home/ricardo/Documents/Projects/sciencer-toolkit/venv/lib/python3.9/site-packages/sciencer/providers/semantic_scholar_provider.py", line 151, in get_papers_by_author
    paper_json) for paper_json in response_json["data"]])
KeyError: 'data'