LitStudy

https://nlesc.github.io/litstudy
Admin
LitStudy is a Python package for analyzing scientific literature and exploring metadata through...
Tokens:27,340
Snippets:306
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Set up Jupyter for LitStudy

Source: https://nlesc.github.io/litstudy/installation.html

Installs Jupyter Notebook and launches it to use LitStudy from a notebook environment.

```bash
pip install notebook
jupyter notebook

```

--------------------------------

### Install litstudy with pip

Source: https://nlesc.github.io/litstudy/installation.html

Installs the litstudy package from PyPI. Requires Python 3.6 or greater.

```bash
pip install litstudy

```

--------------------------------

### Install LitStudy development version

Source: https://nlesc.github.io/litstudy/index.html

Command to install the latest development version of LitStudy directly from the GitHub repository.

```bash
pip install git+https://github.com/NLeSC/litstudy
```

--------------------------------

### Compute year histogram percentages

Source: https://nlesc.github.io/litstudy/example.html

Computes a year histogram table with `litstudy.compute_year_histogram`, then divides by row totals and multiplies by 100 to get percentages. The output shows the percentage of deep learning related documents per year, increasing from 3.4% in 2011 to 13.6% in 2021.

```python
table = litstudy.compute_year_histogram(docs, groups=groups)
table.div(table.sum(axis=1), axis=0) * 100
```

```text
| deep learning related | other  
---|---|---  
2005 | 0.000000 | 100.000000  
2006 | 0.000000 | 100.000000  
2007 | 0.000000 | 100.000000  
2008 | 6.250000 | 93.750000  
2009 | 0.000000 | 100.000000  
2010 | 2.127660 | 97.872340  
2011 | 3.409091 | 96.590909  
2012 | 2.941176 | 97.058824  
2013 | 3.738318 | 96.261682  
2014 | 3.305785 | 96.694215  
2015 | 9.565217 | 90.434783  
2016 | 7.272727 | 92.727273  
2017 | 3.448276 | 96.551724  
2018 | 7.200000 | 92.800000  
2019 | 9.027778 | 90.972222  
2020 | 9.734513 | 90.265487  
2021 | 13.600000 | 86.400000  
2022 | 14.285714 | 85.714286
```

--------------------------------

### Import libraries and configure plotting

Source: https://nlesc.github.io/litstudy/example.html

Sets up the environment for the notebook: imports standard libraries, configures matplotlib and seaborn, and adds the parent directory to sys.path so that the local litstudy package can be imported.

```python
# Import other libraries
import os
import sys
import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
import seaborn as sbs

# Options for plots
plt.rcParams['figure.figsize'] = (10, 6)
sbs.set('paper')

# Import litstudy
path = os.path.abspath(os.path.join('..'))
if path not in sys.path:
    sys.path.append(path)

import litstudy
```

--------------------------------

### litstudy.search_arxiv(query, start=0, max_results=2000, batch_size=100, sort_order='descending', sort_by='submittedDate', sleep_time=3)

Source: https://nlesc.github.io/litstudy/api/sources.html

Searches arXiv and returns a DocumentSet with documents containing title, authors, doi, journal_ref, publication_date, abstract, language, and category.

```APIDOC
## litstudy.search_arxiv(query, start=0, max_results=2000, batch_size=100, sort_order='descending', sort_by='submittedDate', sleep_time=3)

### Description
Search arXiv. Each returned document contains the following attributes: title, authors, doi, journal_ref, publication_date, abstract, language, and category.

### Method
Function

### Signature
`litstudy.search_arxiv(_query_ , _start =0_, _max_results =2000_, _batch_size =100_, _sort_order ='descending'_, _sort_by ='submittedDate'_, _sleep_time =3_) → DocumentSet`

### Parameters
- **query** (str) - Required - The query as described in the arXiv API use manual.
- **start** (int) - Optional - Skip the first `start` documents from the results.
- **max_results** (int) - Optional - The maximum number of results to return.
- **batch_size** (int) - Optional - The number documents to fetch per request.
- **sort_order** (str) - Optional - Sort order for results.
- **sort_by** (str) - Optional - Sort field for results.
- **sleep_time** (float) - Optional - The time to wait in seconds between each HTTP requests.

### Returns
- **DocumentSet** - The search results.
```

--------------------------------

### litstudy.load_ieee_csv(path)

Source: https://nlesc.github.io/litstudy/api/sources.html

Imports a CSV file exported from IEEE Xplore and returns a DocumentSet.

```APIDOC
## litstudy.load_ieee_csv(path)

### Description
Import CSV file exported from IEEE Xplore.

### Method
Function

### Signature
`litstudy.load_ieee_csv(_path : str_) → DocumentSet`

### Parameters
- **path** (str) - Required - Path to the CSV file.

### Returns
- **DocumentSet** - The loaded documents.
```

--------------------------------

### DocumentSet.sample

Source: https://nlesc.github.io/litstudy/api/types.html

Randomly samples documents from the set.

```APIDOC
## sample

### Description
Returns a new set which contains n randomly chosen documents from self.

### Parameters
- **n** (int) - Required - Number of documents to sample.
- **seed** (int) - Optional - Seed for random number generation (default is 0).

### Returns
- **DocumentSet** - The new document set.
```

--------------------------------

### litstudy.load_bibtex(path)

Source: https://nlesc.github.io/litstudy/api/sources.html

Loads a bibtex file at the given path as a DocumentSet.

```APIDOC
## litstudy.load_bibtex(path)

### Description
Load the bibtex file at the given path as a DocumentSet.

### Method
Function

### Signature
`litstudy.load_bibtex(_path : str_) → DocumentSet`

### Parameters
- **path** (str) - Required - Path to the bibtex file.

### Returns
- **DocumentSet** - The loaded documents.
```

--------------------------------

### Load and merge IEEE and Springer CSV files

Source: https://nlesc.github.io/litstudy/example.html

Loads IEEE Xplore CSV files (one per page) and a Springer Link CSV file, then merges them into a single document set using the union operator. The output shows the number of papers loaded from each source and the total.

```python
# Load the CSV files
docs1 = litstudy.load_ieee_csv('data/ieee_1.csv')
docs2 = litstudy.load_ieee_csv('data/ieee_2.csv')
docs3 = litstudy.load_ieee_csv('data/ieee_3.csv')
docs4 = litstudy.load_ieee_csv('data/ieee_4.csv')
docs5 = litstudy.load_ieee_csv('data/ieee_5.csv')
docs_ieee = docs1 | docs2 | docs3 | docs4 | docs5
print(len(docs_ieee), 'papers loaded from IEEE')

docs_springer = litstudy.load_springer_csv('data/springer.csv')
print(len(docs_springer), 'papers loaded from Springer')

# Merge the two document sets
docs_csv = docs_ieee | docs_springer
print(len(docs_csv), 'papers loaded from CSV')
```

```text
441 papers loaded from IEEE
1000 papers loaded from Springer
1441 papers loaded from CSV
```

--------------------------------

### IEEE Xplore

Source: https://nlesc.github.io/litstudy/_sources/api/sources.rst.txt

Function for loading IEEE Xplore CSV data.

```APIDOC
## IEEE Xplore

### Functions
- `load_ieee_csv`
```

--------------------------------

### litstudy.search_dblp(query, limit=None)

Source: https://nlesc.github.io/litstudy/api/sources.html

Performs a query on the DBLP API and returns the results as a DocumentSet.

```APIDOC
## litstudy.search_dblp(query, limit=None)

### Description
Perform the given query on the DBLP API and return the results as a DocumentSet.

### Method
Function

### Signature
`litstudy.search_dblp(_query : str_, _*_ , _limit =None_) → DocumentSet`

### Parameters
- **query** (str) - Required - The query string.
- **limit** (int) - Optional - The maximum number of documents to retrieve.

### Returns
- **DocumentSet** - The search results.
```

--------------------------------

### litstudy hierarchical vs global namespace usage

Source: https://nlesc.github.io/litstudy/_sources/api/index.rst.txt

Shows that functions can be called using their hierarchical module path (e.g., `litstudy.sources.scopus.search_scopus`) or the re-exported global namespace (e.g., `litstudy.search_scopus`). Both forms are equivalent.

```python
docs = litstudy.sources.scopus.search_scopus("example")
litstudy.plot.plot_author_histogram(docs)

# Is equivalent to

docs = litstudy.search_scopus("example")
litstudy.plot_author_histogram(docs)
```

--------------------------------

### litstudy.load_ris_file(path)

Source: https://nlesc.github.io/litstudy/api/sources.html

Loads a RIS file at the given path as a DocumentSet.

```APIDOC
## litstudy.load_ris_file(path)

### Description
Load the RIS file at the given path as a DocumentSet.

### Method
Function

### Signature
`litstudy.load_ris_file(_path : str_) → DocumentSet`

### Parameters
- **path** (str) - Required - Path to the RIS file.

### Returns
- **DocumentSet** - The loaded documents.
```

--------------------------------

### Print top words per topic

Source: https://nlesc.github.io/litstudy/example.html

Prints the top 3 words for each topic from the trained NMF model. The output shows topics like cluster/mpi/node for Topic 1 and mapreduce/big/data for Topic 2.

```python
for i in range(num_topics):
    print(f'Topic {i+1}:', topic_model.best_tokens_for_topic(i))
```

--------------------------------

### DocumentSet.select

Source: https://nlesc.github.io/litstudy/api/types.html

Selects a subset of documents at specified indices.

```APIDOC
## select

### Description
Returns a new set which contains only the documents at the provided indices.

### Parameters
- **indices** (list of int or any accepted by pandas.DataFrame.iloc) - Required - Any input accepted by pandas.DataFrame.iloc such as a list of integer.

### Returns
- **DocumentSet** - The new document set.
```

--------------------------------

### Train NMF topic model

Source: https://nlesc.github.io/litstudy/example.html

Trains an NMF topic model with 15 topics and 250 iterations. The number of topics is manually selected; experimenting with more or fewer topics is recommended.

```python
num_topics = 15
topic_model = litstudy.train_nmf_model(corpus, num_topics, max_iter=250)
```

--------------------------------

### DocumentSet.itertuples

Source: https://nlesc.github.io/litstudy/api/types.html

Iterates over document and property tuples.

```APIDOC
## itertuples

### Description
Returns an iterator over (Document, dict) tuples, where the dict contains the properties of this document.

### Returns
- **iterator** - An iterator over (Document, dict) tuples.
```

--------------------------------

### litstudy.nlp.train_nmf_model()

Source: https://nlesc.github.io/litstudy/api/nlp.html

Trains a topic model using Non-negative Matrix Factorization (NMF).

```APIDOC
## Function: litstudy.nlp.train_nmf_model()

### Description
Train a topic model using NMF.

### Signature
`train_nmf_model(_corpus : Corpus_, _num_topics : int_, _seed =0_, _max_iter =500_) → TopicModel`

### Parameters
- **corpus** (Corpus) - Required - The corpus to train on.
- **num_topics** (int) - Required - The number of topics to train.
- **seed** (int) - Optional - The seed used for random number generation.
- **max_iter** (int) - Optional - The maximum number of iterations to use for training. More iterations mean better results, but longer training times.

### Returns
- **TopicModel** - The trained topic model.
```

--------------------------------

### litstudy.nlp.generate_topic_cloud()

Source: https://nlesc.github.io/litstudy/api/nlp.html

Generates a word cloud for a topic.

```APIDOC
## Function: litstudy.nlp.generate_topic_cloud()

### Description
Generates a word cloud for a topic.

### Signature
`generate_topic_cloud(_topic_model : TopicModel_, _topic_id : int_)`

### Parameters
- **topic_model** (TopicModel) - Required - The topic model.
- **topic_id** (int) - Required - The topic index.

### Returns
- Word cloud object.
```

--------------------------------

### litstudy.load_springer_csv(path)

Source: https://nlesc.github.io/litstudy/api/sources.html

Loads a CSV file exported from Springer Link and returns a DocumentSet.

```APIDOC
## litstudy.load_springer_csv(path)

### Description
Load CSV file exported from Springer Link.

### Method
Function

### Signature
`litstudy.load_springer_csv(_path : str_) → DocumentSet`

### Parameters
- **path** (str) - Required - Path to the CSV file.

### Returns
- **DocumentSet** - The loaded documents.
```

--------------------------------

### litstudy.nlp.build_corpus()

Source: https://nlesc.github.io/litstudy/api/nlp.html

Builds a Corpus object from a DocumentSet by preprocessing tokens from titles/abstracts. Highly customizable with parameters for filtering and n-gram detection.

```APIDOC
## Function: litstudy.nlp.build_corpus()

### Description
Build a Corpus object. This function takes the words from the title/abstract of the given documents, preprocesses the tokens, and returns a corpus consisting of a word frequency vector for each document. This preprocessing stage is highly customizable, thus it is advised to experiment with the many parameters.

### Signature
`build_corpus(_docs : DocumentSet_, *_ , _remove_words =None_, _min_word_length =3_, _min_docs =5_, _max_docs_ratio =0.75_, _max_tokens =5000_, _replace_words =None_, _custom_bigrams =None_, _ngram_threshold =None_) → Corpus`

### Parameters
- **docs** (DocumentSet) - Required - The set of documents to build the corpus from.
- **remove_words** (list) - Optional - List of words that should be ignored while building the word frequency vectors.
- **min_word_length** (int) - Optional - Words shorter than this are ignored.
- **min_docs** (int) - Optional - Words that occur in fewer than this many documents are ignored.
- **max_docs_ratio** (float) - Optional - Words that occur in more than this document are ignored. Should be ratio between 0 and 1.
- **max_tokens** (int) - Optional - Only the top most common tokens are preserved.
- **replace_words** (dict) - Optional - Replace words by other words. Must be a dict containing _original word_ to _replacement word_ pairs.
- **custom_bigrams** (dict) - Optional - Add custom bigrams. Must be a dict where keys are (first, second) tuples and values are replacements. For example, the key can be ("Big", "Data") and the value "BigData".
- **ngram_threshold** (float) - Optional - Threshold used for n-gram detection. Is passed to gensim.models.phrases.Phrases to detect common n-grams.

### Returns
- **Corpus** - A Corpus object.
```

--------------------------------

### Compute most popular publication venues for deep learning

Source: https://nlesc.github.io/litstudy/example.html

Uses pandas to compute a histogram by publication venue, adds a 'total' column, filters out venues with fewer than 5 publications, adds a 'ratio' column, and sorts by ratio descending. The output shows 'Neural Computing and Applications' as the most popular venue.

```python
# Compute histogram by publication venue
table = litstudy.compute_source_histogram(docs, groups=groups)

# Add column 'total'
table['total'] = table['deep learning related'] + table['other']

# Remove rare venues that have less than 5 publications
table = table[table['total'] >= 5]

# Add column 'ratio'
table['ratio'] = table['deep learning related'] / table['total'] * 100

# Sort by ratio in descending order
table.sort_values(by='ratio', ascending=False)
```

--------------------------------

### litstudy.load_csv

Source: https://nlesc.github.io/litstudy/api/sources.html

Loads a CSV file into a DocumentSet, attempting to infer field purposes from column names. Parameter overrides allow explicit field mapping for each document attribute.

```APIDOC
## litstudy.load_csv

### Description
Load an arbitrary CSV file and parse its contents as a DocumentSet on a best effort basis. An attempt is made to guess the purpose of the fields based on their names, but explicit field names can be provided using the dedicated parameters.

### Method
Function (Python)

### Endpoint
litstudy.load_csv(_path_, _dialect=None_, _title_field=None_, _authors_field=None_, _abstract_field=None_, _citation_field=None_, _date_field=None_, _source_field=None_, _doi_field=None_, _filter=None_) -> DocumentSet

### Parameters
- **path** (str) - Required - Name of CSV file.
- **dialect** (Dialect | None) - Optional - Used to read the CSV file.
- **title_field** (str | None) - Optional - Field name for `title`.
- **authors_field** (str | None) - Optional - Field name for `authors`.
- **abstract_field** (str | None) - Optional - Field name for `abstract`.
- **citation_field** (str | None) - Optional - Field name for `citation_count`.
- **date_field** (str | None) - Optional - Field name for `publication_date` or.
- **source_field** (str | None) - Optional - Field name for `source`.
- **doi_field** (str | None) - Optional - Field name for `doi`.
- **filter** (Optional) - Optional - Function applied to each loaded record. Can be used to add or delete fields.

### Example
```
docs = litstudy.load_csv("my_data.csv",
                         title_field="Document Title",
                         date_field="Pub Date")
```
```

--------------------------------

### litstudy.nlp.generate_topic_cloud

Source: https://nlesc.github.io/litstudy/api/nlp.html

Generates a word cloud for a specific topic from a given topic model. Allows customization of colors, font size, and background color.

```APIDOC
## litstudy.nlp.generate_topic_cloud

### Description
Generate a word cloud for the given topic from the given topic model.

### Signature
Function call: `litstudy.nlp.generate_topic_cloud(model: TopicModel, topic_id: int, cmap=None, max_font_size=75, background_color='white') -> WordCloud`

### Parameters
- **model** (TopicModel) - Required - The topic model to generate the cloud from.
- **topic_id** (int) - Required - The ID of the topic to create the cloud for.
- **cmap** (str) - Optional - The color map used to color the words.
- **max_font_size** (int) - Optional - Size of the word that most strongly belongs to the topic; other words are scaled accordingly. Default is 75.
- **background_color** (str) - Optional - Background color. Default is 'white'.

### Returns
- **WordCloud** - The generated word cloud object.
```

--------------------------------

### load_scopus_csv(path)

Source: https://nlesc.github.io/litstudy/api/sources.html

Imports a CSV file exported from Scopus into a DocumentSet.

```APIDOC
## load_scopus_csv(path)

### Description
Import CSV file exported from Scopus.

### Method
Function call

### Signature
`litstudy.load_scopus_csv(path: str) -> DocumentSet`

### Parameters
- **path** (str) - Required - The file path to the CSV file.

### Returns
- **DocumentSet** - The imported document set.
```

--------------------------------

### Plot topic clouds

Source: https://nlesc.github.io/litstudy/example.html

Plots each discovered topic as a word cloud, with word size indicating importance. The figure is 15x5 with 5 columns.

```python
plt.figure(figsize=(15, 5))
litstudy.plot_topic_clouds(topic_model, ncols=5);
```

--------------------------------

### Print top 10 documents for a topic

Source: https://nlesc.github.io/litstudy/example.html

Iterates over the top 10 documents for the given topic ID and prints their titles. The output shows the titles of the top papers, which are indeed about deep learning.

```python
for doc_id in topic_model.best_documents_for_topic(topic_id, limit=10):
    print(docs[int(doc_id)].title)
```

```text
High performance networked computing in media, services and information management
What do Programmers Discuss about Deep Learning Frameworks
Sparse evolutionary deep learning with over one million artificial neurons on commodity hardware
Deep learning for intelligent traffic sensing and prediction: recent advances and future challenges
SOLAR: Services-oriented learning architectures: Deep learning as a service
Reveal training performance mystery between TensorFlow and PyTorch in the single GPU environment
Network Management 2030: Operations and Control of Network 2030 Services
SOLAR: Services-Oriented Deep Learning Architectures-Deep Learning as a Service
DLPlib: A Library for Deep Learning Processor
Machine Learning and Deep Learning frameworks and libraries for large-scale data mining: a survey
```

--------------------------------

### plot_network()

Source: https://nlesc.github.io/litstudy/api/network.html

Plots a networkx.Graph generated by one of the build_X_graph functions in this module. Plotting is done using the pyvis library.

```APIDOC
## plot_network(g, *, height='1000px', smooth_edges=None, max_node_size=100, min_node_size=5, largest_component=True, interactive=True, controls=False, scale=1, iterations=1000, gravity=1, file_name='network.html')

### Description
Plot a networkx.Graph generated by one of the build_X_graph functions in this module. Plotting is done using the pyvis library.

### Parameters
- **height** - Height of the plot.
- **smooth_edges** - Enables curved ('smooth') edges. Looks nice but is heavy on performance.
- **min_node_size** - The radius of the smallest node.
- **max_node_size** - The radius of the largest node.
- **largest_component** - Only plot the largest connected component of the graph.
- **file_name** - The name of the file where the plot will be saved.
```

--------------------------------

### Build corpus with ngram_threshold

Source: https://nlesc.github.io/litstudy/example.html

Builds a corpus from a document set with n-gram threshold 0.8, which adds frequent consecutive words as tokens (e.g., artificial_intelligence).

```python
corpus = litstudy.build_corpus(docs, ngram_threshold=0.8)
```

--------------------------------

### plot_topic_cloud

Source: https://nlesc.github.io/litstudy/api/plot.html

Plots a word cloud for a specific topic in a topic model.

```APIDOC
## plot_topic_cloud(model, topic_id, *, ax=None, **kwargs)

### Description
Plot a word cloud for the given topic from the given topic model.

### Parameters
- **model** (TopicModel) - Required - The topic model to plot.
- **topic_id** (int) - Required - The topic identifier.
- **ax** (Axes) - Optional - The matplotlib Axes instance the plot will be drawn on.
- **kwargs** - Optional - Passed to plot_histogram.
```

--------------------------------

### bibtex

Source: https://nlesc.github.io/litstudy/_sources/api/sources.rst.txt

Function for loading bibtex data.

```APIDOC
## bibtex

### Functions
- `load_bibtex`
```

--------------------------------

### plot_topic_clouds

Source: https://nlesc.github.io/litstudy/api/plot.html

Plots word clouds for each topic in a topic model.

```APIDOC
## plot_topic_clouds(model, *, fig=None, ncols=3, **kwargs)

### Description
Plot word clouds for each of the topics from the given topic model.

### Parameters
- **model** (TopicModel) - Required - The topic model to plot.
- **fig** - Optional - Not described in source.
- **ncols** (int) - Optional - Number of columns for the subplot grid. Default is 3.
- **kwargs** - Optional - Passed to plot_histogram.
```

--------------------------------

### search_scopus(query, *, limit=None)

Source: https://nlesc.github.io/litstudy/api/sources.html

Submits the given query to the Scopus API and returns a DocumentSet of results.

```APIDOC
## search_scopus(query, *, limit=None)

### Description
Submit the given query to the Scopus API.

### Method
Function call

### Signature
`litstudy.search_scopus(query: str, *, limit: int | None = None) -> DocumentSet`

### Parameters
- **query** (str) - Required - The query string to submit to the Scopus API.
- **limit** (int | None) - Optional - Restrict results to the first limit documents.

### Returns
- **DocumentSet** - The set of documents returned by the Scopus API.
```

--------------------------------

### DocumentSet.add_property

Source: https://nlesc.github.io/litstudy/api/types.html

Adds an additional property to the document set, returning a new set.

```APIDOC
## add_property

### Description
Returns a new set which has an additional property added.

### Method
add_property

### Parameters
- **name** (str) - Required - Name of the new property.
- **values** (list) - Required - List of values. Should be the same length as the number of documents in this set.

### Returns
- **DocumentSet** - The new document set.
```

--------------------------------

### CSV

Source: https://nlesc.github.io/litstudy/_sources/api/sources.rst.txt

Function for loading CSV data.

```APIDOC
## CSV

### Functions
- `load_csv`
```

--------------------------------

### litstudy.nlp.train_elda_model()

Source: https://nlesc.github.io/litstudy/api/nlp.html

Trains a topic model using Ensemble Latent Dirichlet Allocation (ELDA).

```APIDOC
## Function: litstudy.nlp.train_elda_model()

### Description
Train a topic model using ELDA.

### Signature
`train_elda_model(_corpus : Corpus_, _num_topics : int_, _seed =0_, _max_iter =500_) → TopicModel`

### Parameters
- **corpus** (Corpus) - Required - The corpus to train on.
- **num_topics** (int) - Required - The number of topics to train.
- **seed** (int) - Optional - The seed used for random number generation.
- **max_iter** (int) - Optional - The maximum number of iterations to use for training. More iterations mean better results, but longer training times.

### Returns
- **TopicModel** - The trained topic model.
```

--------------------------------

### DocumentIdentifier.matches

Source: https://nlesc.github.io/litstudy/api/types.html

Checks if two document identifiers are equivalent. Two documents are equivalent if all identifiers they have in common are equal; if no common identifiers exist, a fuzzy match based on title is performed.

```APIDOC
## matches(other: DocumentIdentifier) -> bool

### Description
Returns True iff these two identifiers are equivalent. Two documents are considered to be equivalent if all identifiers they have in common are equal. For example, if both documents have a DOI then these should be the same. If two documents have not a single identifier in common, a fuzzy match based on the title is performed.

### Method
matches

### Parameters
- **other** (DocumentIdentifier) - Required - The other document identifier to compare with.

### Returns
- **bool** - True if the identifiers are equivalent, False otherwise.
```

--------------------------------

### Plot source histogram with litstudy.plot_source_histogram and mapper

Source: https://nlesc.github.io/litstudy/example.html

Plots a histogram of publication sources, using a mapping to abbreviate long source names. The mapper parameter replaces full names with the provided abbreviations, and limit=15 shows only the top 15 sources.

```python
# This names are long, which is why a short abbreviation is provided.
mapping = {
    "IEEE International parallel and distributed processing symposium IPDPS": "IEEE IPDPS",
    "IEEE International parallel and distributed processing symposium workshops IPDPSW": "IEEE IPDPS Workshops",
}

litstudy.plot_source_histogram(docs, mapper=mapping, limit=15);
```

--------------------------------

### build_citation_network()

Source: https://nlesc.github.io/litstudy/api/network.html

Builds a citation network: a directed graph where each node corresponds to a document and each directed edge indicates that one document cites the other.

```APIDOC
## build_citation_network(docs, **kwargs) -> Graph

### Description
Builds a citation network: a directed graph where each node corresponds to a document and each directed edge indicates that one document cites the other.
```

--------------------------------

### litstudy.nlp.compute_word_distribution()

Source: https://nlesc.github.io/litstudy/api/nlp.html

Computes the word distribution for a corpus.

```APIDOC
## Function: litstudy.nlp.compute_word_distribution()

### Description
Computes the word distribution for a corpus.

### Signature
`compute_word_distribution(_corpus : Corpus_)`

### Parameters
- **corpus** (Corpus) - Required - The corpus to compute the distribution for.

### Returns
- Distribution of words.
```

--------------------------------

### build_cocitation_network()

Source: https://nlesc.github.io/litstudy/api/network.html

Builds a co-citation network: a undirected graph where each node corresponds to a document and the edge weights stores the cocitation strengths (i.e., the number of times two documents have been cited together).

```APIDOC
## build_cocitation_network(docs, *, max_edges=None, **kwargs) -> Graph

### Description
Builds a co-citation network: a undirected graph where each node corresponds to a document and the edge weights stores the cocitation strengths (i.e., the number of times two documents have been cited together).

### Parameters
- **max_edges** - Select only the top edges. This is useful since cocitation networks are often dense and only the strongest edges are usually important.
```

--------------------------------

### Plot source histogram for groups

Source: https://nlesc.github.io/litstudy/example.html

Plots a stacked histogram of publication sources for the two groups using `litstudy.plot_source_histogram` with a limit of 25. The output shows which venues have a strong focus on deep learning.

```python
plt.figure(figsize=(10, 10))
litstudy.plot_source_histogram(docs, groups=groups, limit=25, stacked=True);
```

--------------------------------

### RIS

Source: https://nlesc.github.io/litstudy/_sources/api/sources.rst.txt

Function for loading RIS file data.

```APIDOC
## RIS

### Functions
- `load_ris_file`
```

--------------------------------

### plot_citation_network()

Source: https://nlesc.github.io/litstudy/api/network.html

Plot a citation network. This is a shorthand for plot_network(build_citation_network(docs)).

```APIDOC
## plot_citation_network(docs, **kwargs)

### Description
Plot a citation network. This is a shorthand for plot_network(build_citation_network(docs)).
```

--------------------------------

### litstudy.nlp.train_lda_model()

Source: https://nlesc.github.io/litstudy/api/nlp.html

Trains a topic model using Latent Dirichlet Allocation (LDA).

```APIDOC
## Function: litstudy.nlp.train_lda_model()

### Description
Train a topic model using LDA.

### Signature
`train_lda_model(_corpus : Corpus_, _num_topics : int_, _seed =0_, _max_iter =500_) → TopicModel`

### Parameters
- **corpus** (Corpus) - Required - The corpus to train on.
- **num_topics** (int) - Required - The number of topics to train.
- **seed** (int) - Optional - The seed used for random number generation.
- **max_iter** (int) - Optional - The maximum number of iterations to use for training. More iterations mean better results, but longer training times.

### Returns
- **TopicModel** - The trained topic model.
```

--------------------------------

### plot_cocitation_network()

Source: https://nlesc.github.io/litstudy/api/network.html

Plot a citation network. This is a shorthand for plot_network(build_cocitation_network(docs)).

```APIDOC
## plot_cocitation_network(docs, *, max_edges=None, node_size=10, **kwargs)

### Description
Plot a citation network. This is a shorthand for plot_network(build_cocitation_network(docs)).
```

--------------------------------

### DocumentSet.difference

Source: https://nlesc.github.io/litstudy/api/types.html

Returns a new set containing documents in this set but not in another.

```APIDOC
## difference

### Description
Returns a new set which contains the documents provided in self but not in other. This is also available as the - operator.

### Parameters
- **other** (DocumentSet) - Required - The other document set.

### Returns
- **DocumentSet** - The new document set.
```

--------------------------------

### build_coupling_network()

Source: https://nlesc.github.io/litstudy/api/network.html

Builds a bibligraphic coupling network: an undirected graph where nodes indicate documents and edge weights store the bibliographic coupling strength. This strength measures how similar two documents view related work. It is measured as the number of shared references between two documents.

```APIDOC
## build_coupling_network(docs, max_edges=1000, **kwargs) -> Graph

### Description
Builds a bibligraphic coupling network: an undirected graph where nodes indicate documents and edge weights store the bibliographic coupling strength. This strength measures how similar two documents view related work. It is measured as the number of shared references between two documents.

### Parameters
- **max_edges** - Select only the top edges. This is useful since these networks are often dense and only the strongest edges are usually important.
```

--------------------------------

### plot_coauthor_network()

Source: https://nlesc.github.io/litstudy/api/network.html

Plot a co-author network. This is a shorthand for plot_network(build_coauthor_network(docs)).

```APIDOC
## plot_coauthor_network(docs, *, max_authors=None, **kwargs)

### Description
Plot a co-author network. This is a shorthand for plot_network(build_coauthor_network(docs)).
```

--------------------------------

### Plot co-citation network with litstudy.plot_cocitation_network

Source: https://nlesc.github.io/litstudy/example.html

Plots a co-citation network of the documents, limiting to 500 edges. The output shows progress and timing information from the force-directed layout algorithm.

```python
litstudy.plot_cocitation_network(docs, max_edges=500)
```

```text
100%|██████████| 1000/1000 [00:00<00:00, 1752.38it/s]
```

```text
BarnesHut Approximation  took  0.14  seconds
Repulsion forces  took  0.32  seconds
Gravitational forces  took  0.01  seconds
Attraction forces  took  0.01  seconds
AdjustSpeedAndApplyForces step  took  0.04  seconds
```

--------------------------------

### Document.mentions

Source: https://nlesc.github.io/litstudy/api/types.html

Checks if the document mentions a given term in its title, abstract, or keywords.

```APIDOC
## mentions(term: str) -> bool

### Description
Returns True if this document mentions the given term in the title, abstract, or keywords.

### Method
mentions

### Parameters
- **term** (str) - Required - The term to search for in the document's title, abstract, or keywords.

### Returns
- **bool** - True if the term is mentioned, False otherwise.
```

--------------------------------

### plot_coupling_network()

Source: https://nlesc.github.io/litstudy/api/network.html

Plot a bibliographic coupling network. This is a shorthand for plot_network(build_coupling_network(docs)).

```APIDOC
## plot_coupling_network(docs, *, max_edges=None, node_size=10, **kwargs)

### Description
Plot a bibliographic coupling network. This is a shorthand for plot_network(build_coupling_network(docs)).
```

--------------------------------

### Plot language histogram with litstudy.plot_language_histogram

Source: https://nlesc.github.io/litstudy/example.html

Plots a histogram of languages used in the documents.

```python
litstudy.plot_language_histogram(docs);
```

--------------------------------

### litstudy.nlp.train_elda_model

Source: https://nlesc.github.io/litstudy/api/nlp.html

Trains a topic model using ensemble LDA on the provided corpus. Allows configuration for the number of topics, number of models, seed, and keyword arguments passed to gensim's EnsembleLda.

```APIDOC
## litstudy.nlp.train_elda_model

### Description
Train a topic model using ensemble LDA.

### Signature
Function call: `litstudy.nlp.train_elda_model(corpus: Corpus, num_topics, num_models=4, seed=0, **kwargs) -> TopicModel`

### Parameters
- **corpus** (Corpus) - Required - The corpus to train on.
- **num_topics** (int) - Required - The number of topics to train.
- **num_models** (int) - Optional - The number of models to train. Default is 4.
- **seed** (int) - Optional - The seed used for random number generation.
- **kwargs** (dict) - Optional - Arguments passed to `gensim.models.ensemblelda.EnsembleLda` (gensim4).

### Returns

- **TopicModel** - The trained topic model.
```

--------------------------------

### Plot country histogram with litstudy.plot_country_histogram

Source: https://nlesc.github.io/litstudy/example.html

Plots a histogram of countries, showing only the top 15 countries by frequency.

```python
litstudy.plot_country_histogram(docs, limit=15);
```

--------------------------------

### refine_scopus(docs, *, search_title=True)

Source: https://nlesc.github.io/litstudy/api/sources.html

Attempts to fetch Scopus metadata for each document in the given set. Returns a tuple of two document sets: those found on Scopus and those not found.

```APIDOC
## refine_scopus(docs, *, search_title=True)

### Description
Attempt to fetch Scopus metadata for each document in the given set. Returns a tuple containing two sets: the documents available on Scopus and the remaining documents not found on Scopus. Documents are retrieved based on their identifier (DOI, Pubmed ID, or Scopus ID). Documents without a unique identifier are retrieved by performing a fuzzy search based on their title.

### Method
Function call

### Signature
`litstudy.refine_scopus(docs: DocumentSet, *, search_title=True) -> Tuple[DocumentSet, DocumentSet]`

### Parameters
- **docs** (DocumentSet) - Required - The set of documents to refine.
- **search_title** (bool) - Optional - Flag to toggle searching by title. Defaults to True.

### Returns
- **Tuple[DocumentSet, DocumentSet]** - A tuple containing the documents available on Scopus and the remaining documents not found on Scopus.
```

--------------------------------

### Find topic ID for 'deep_learning'

Source: https://nlesc.github.io/litstudy/example.html

Uses `topic_model.best_topic_for_token('deep_learning')` to retrieve the topic ID that most strongly corresponds to the token 'deep_learning'.

```python
topic_id = topic_model.best_topic_for_token('deep_learning')
```

--------------------------------

### litstudy.fetch_crossref

Source: https://nlesc.github.io/litstudy/api/sources.html

Fetch metadata for a given DOI from CrossRef.

```APIDOC
## litstudy.fetch_crossref

### Description
Fetch the metadata for the given DOI from CrossRef. Returns a Document or None if the DOI was not available.

### Method
Function call

### Endpoint
litstudy.fetch_crossref(doi, *, timeout=0.5, session=None)

### Parameters
- **doi** (str) - Required - The DOI to fetch metadata for.
- **timeout** (float) - Optional - The timeout between each HTTP request in seconds. Default is 0.5.
- **session** (requests.Session) - Optional - The requests.Session to use for HTTP requests.

### Returns
- **Document | None** - The Document for the DOI, or None if the DOI was not available.
```

--------------------------------

### Plot word distribution

Source: https://nlesc.github.io/litstudy/example.html

Visualizes the word distribution from the corpus with a horizontal figure, limiting to top 50 words, vertical bars, and rotated labels.

```python
plt.figure(figsize=(20, 3))
litstudy.plot_word_distribution(corpus, limit=50, title="Top words", vertical=True, label_rotation=45);
```

--------------------------------

### search_semanticscholar

Source: https://nlesc.github.io/litstudy/api/sources.html

Submit the given query to SemanticScholar API and return the results as a DocumentSet. The query is a string containing keywords (see API reference).

```APIDOC
## search_semanticscholar

### Description
Submit the given query to SemanticScholar API and return the results as a DocumentSet. The query is a string containing keywords (see API reference).

### Method
search_semanticscholar

### Endpoint
litstudy.search_semanticscholar(query, *, limit=None, batch_size=100, session=None)

### Parameters
#### Path Parameters
- **query** (str) - Required - The search query to submit.

#### Query Parameters
- **limit** (int | None) - Optional - The maximum number of results to return.
- **batch_size** (int) - Optional - The number of results to retrieve per request. Must be at most 100.
- **session** (requests.Session) - Optional - The requests.Session to use for HTTP requests.

### Returns
- **DocumentSet** - The results as a DocumentSet.

### Example
```python
results = litstudy.search_semanticscholar('machine learning', limit=10)
```
```

--------------------------------

### Annotate documents with 'dl_topic' tag and plot year histogram

Source: https://nlesc.github.io/litstudy/example.html

Sets a threshold of 0.2 to tag documents as 'dl_topic' if their topic weight exceeds it. Defines two groups ('deep learning related' and 'other') and plots a stacked year histogram using `litstudy.plot_year_histogram`.

```python
threshold = 0.2
dl_topic = topic_model.doc2topic[:, topic_id] > threshold

docs = docs.add_property('dl_topic', dl_topic)


groups = {
    'deep learning related': 'dl_topic',
    'other': 'not dl_topic',
}

litstudy.plot_year_histogram(docs, groups=groups, stacked=True);
```

--------------------------------

### build_coauthor_network()

Source: https://nlesc.github.io/litstudy/api/network.html

Builds a co-author network: an undirected graph where nodes indicate authors and edge weight indicate the number of shared publications between two authors.

```APIDOC
## build_coauthor_network(docs, *, max_authors=None) -> Graph

### Description
Builds a co-author network: an undirected graph where nodes indicate authors and edge weight indicate the number of shared publications between two authors.

### Parameters
- **max_authors** - Select only the top X authors.
```

--------------------------------

### dblp

Source: https://nlesc.github.io/litstudy/_sources/api/sources.rst.txt

Function for searching dblp data.

```APIDOC
## dblp

### Functions
- `search_dblp`
```

--------------------------------

### DocumentSet.concat

Source: https://nlesc.github.io/litstudy/api/types.html

Concatenates two document sets without removing duplicates.

```APIDOC
## concat

### Description
Returns a new set which does contain the documents provided in either self and other. Duplicate documents are not removed, see union instead. This is also available as the + operator.

### Parameters
- **other** (DocumentSet) - Required - The other document set.

### Returns
- **DocumentSet** - The new document set.
```

--------------------------------

### CrossRef

Source: https://nlesc.github.io/litstudy/_sources/api/sources.rst.txt

Functions for fetching, refining, and searching CrossRef data.

```APIDOC
## CrossRef

### Functions
- `fetch_crossref`
- `refine_crossref`
- `search_crossref`
```

--------------------------------

### arXiv

Source: https://nlesc.github.io/litstudy/_sources/api/sources.rst.txt

Function for searching arXiv data.

```APIDOC
## arXiv

### Functions
- `search_arxiv`
```

--------------------------------

### Compute word distribution with n-gram filter

Source: https://nlesc.github.io/litstudy/example.html

Computes word distribution across documents, filtering to n-grams (tokens containing underscore) and sorting by index. The output shows counts for bigrams like artificial_intelligence and trade_offs.

```python
litstudy.compute_word_distribution(corpus).filter(like='_', axis=0).sort_index()
```

--------------------------------

### Springer Link

Source: https://nlesc.github.io/litstudy/_sources/api/sources.rst.txt

Function for loading Springer Link CSV data.

```APIDOC
## Springer Link

### Functions
- `load_springer_csv`
```

--------------------------------

### DocumentSet.union

Source: https://nlesc.github.io/litstudy/api/types.html

Returns a new set containing all documents from this set and another, with duplicates discarded.

```APIDOC
## union

### Description
Returns a new set which contains the documents provided in either self and other. Duplicate documents in other that also appear in self are discarded. This is also available as the | operator.

### Parameters
- **other** (DocumentSet) - Required - The other document set.

### Returns
- **DocumentSet** - The new document set.
```
Tokens:
Raw