lisc.Words¶

class lisc.Words[source]¶

A class for collecting and analyzing words data for specified terms list(s).

Attributes

labelslist of str: The labels for each term.
has_databool: Indicator for if the object has collected data.
resultslist of Articles: Results of ‘Words’ data collection for each search term.
combined_resultslist of ArticlesAll: Results for each search term combined across individual articles.
meta_dataMetaData: Meta data information about the data collection.

__init__()[source]¶: Initialize LISC Words object.

Methods

`__init__`()	Initialize LISC Words object.
`add_labels`(labels[, directory, ...])	Add the given list of strings as labels for the terms.
`add_results`(new_result)	Add new results for a term to the current object.
`add_terms`(terms[, term_type, directory, ...])	Add terms to the object.
`check_data`()	Prints out the number of articles collected for each term.
`check_terms`([term_type])	Print out the current list of terms.
`copy`()	Return a copy of the current object.
`drop_data`(n_articles)	Drop terms based on number of article results.
`drop_term`(label)	Drop specified term(s) from the object.
`get_index`(label)	Get the index for a specified search term.
`get_term`(label)	Get a search term from the object.
`make_search_term`(label)	Create the combined search term for a selected term.
`process_articles`([process_func])	Process the articles stored in the object.
`process_combined_results`([exclusions])	Process article data to create combined results, across all articles, for each term.
`run_collection`([db, retmax, field, ...])	Collect words data.
`unload_labels`([verbose])	Unload labels from the object.
`unload_terms`([term_type, reset, verbose])	Completely unload terms from the object.

Attributes

`has_data`	Indicator for if the object has collected data.
`has_terms`	Indicator for if the object has terms.
`labels`	The labels for each term.
`n_terms`	How many terms are included in the object.

add_labels(labels, directory=None, check_consistency=True)¶

Add the given list of strings as labels for the terms.

Parameters

labelslist of str or str: Labels for each term to add to the object. If list, is assumed to be labels. If str, is assumed to be a file name to load from.
directorySCDB or str, optional: Folder or database object specifying the file location, if loading from file.
check_consistencybool, optional, default: True: Whether to check the object for consistency after adding labels.

add_results(new_result)[source]¶

Add new results for a term to the current object.

Parameters

new_resultArticles: Object with collected data for a specified term.

add_terms(terms, term_type=None, directory=None, append=False, check_consistency=True)¶

Add terms to the object.

Parameters

termslist or dict or str: Terms to add to the object. If list, assumed to be terms, which can be a list of str or a list of list of str. If dict, each key should reflect a term_type, and values the corresponding terms. If str, assumed to be a file name to load from.
term_type{‘terms’, ‘inclusions’, ‘exclusions’}: Which type of terms to are being added.
directorySCDB or str, optional: Folder or database object specifying the file location, if loading from file.
appendboolean, optional, default: False: Whether to append the new term(s) to any existing terms. If False, any prior terms are cleared prior to adding current term(s).
check_consistencybool, optional, default: True: Whether to check the object for consistency after adding terms.

Examples

Add search terms, from a list:

>>> base = Base()
>>> base.add_terms(['frontal lobe', 'temporal lobe', 'parietal lobe', 'occipital lobe'])

Add inclusion terms, from a list:

>>> base.add_terms([[], ['brain'], [], []], term_type='inclusions')

Add exclusion terms, from a list:

>>> base.add_terms([['prefrontal'], [], [], []], term_type='exclusions')

check_data()[source]¶: Prints out the number of articles collected for each term.

check_terms(term_type='terms')¶

Print out the current list of terms.

Examples

Check added terms:

>>> base = Base()
>>> base.add_terms(['frontal lobe', 'temporal lobe', 'parietal lobe', 'occipital lobe'])
>>> base.check_terms() 
List of terms used:

frontal lobe    : frontal lobe
temporal lobe   : temporal lobe
parietal lobe   : parietal lobe
occipital lobe  : occipital lobe

Attributes

term_type{‘terms’, ‘inclusions’, ‘exclusions’}: Which type of terms to use.

copy()¶: Return a copy of the current object.

drop_data(n_articles)[source]¶

Drop terms based on number of article results.

Parameters

n_articlesint: Minimum number of articles required to keep each term.

Examples

Drop terms with less than 20 articles (assuming words already has data):

>>> words.drop_data(20) 

drop_term(label)¶

Drop specified term(s) from the object.

Parameters

labelstr or int or list: The label of the term to drop. If str, is the label of the term. If int, is used as the index of the term. If list, drops each element of the list.

get_index(label)¶

Get the index for a specified search term.

Parameters

labelstr: The label of the search term.

Returns

indint: The index of the requested search term.

Raises

IndexError: If the requested term label is not found.

get_term(label)¶

Get a search term from the object.

Parameters

labelstr or int: The requested term. If str, is the label of the term. If int, is used as the index of the term.

Returns

termTerm: The full search term definition.

property has_data¶: Indicator for if the object has collected data.

property has_terms¶: Indicator for if the object has terms.

property labels¶: The labels for each term.

make_search_term(label)¶

Create the combined search term for a selected term.

Parameters

labelstr or int: The requested term. If str, is the label of the term. If int, is used as the index of the term.

property n_terms¶: How many terms are included in the object.

process_articles(process_func=None)[source]¶

Process the articles stored in the object.

Parameters

process_funccallable, optional: A function to process article data. Must take as input an Articles object. If not provided, applies the default process_articles function.

process_combined_results(exclusions=None)[source]¶

Process article data to create combined results, across all articles, for each term.

Parameters

exclusionslist of str, optional: Words to exclude from the combined word collections.

Notes

This function will process the article data contained in the object.

run_collection(db='pubmed', retmax=None, field='TIAB', usehistory=False, api_key=None, save_and_clear=False, logging=None, directory=None, verbose=False, **eutils_kwargs)[source]¶

Collect words data.

Parameters

dbstr, optional, default: ‘pubmed’: Which database to access from EUtils.
retmaxint, optional: Maximum number of records to return.
fieldstr, optional, default: ‘TIAB’: Field(s) to search for term. Defaults to ‘TIAB’, which is Title/Abstract.
usehistorybool, optional, default: False: Whether to use EUtils history, storing results on the EUtils server.
api_keystr, optional: An API key for a NCBI account.
save_and_clearbool, optional, default: False: Whether to save words data to disk per term, instead of holding in memory.
logging{None, ‘print’, ‘store’, ‘file’}, optional: What kind of logging, if any, to do for requested URLs.
directorystr or SCDB, optional: Folder or database object specifying the save location for any outputs.
verbosebool, optional, default: False: Whether to print out updates.
**eutils_kwargs: Additional settings for the EUtils API.

Examples

Collect words data for a set of terms, set to collect up to five articles each:

>>> words = Words()
>>> words.add_terms([['brain'], ['body']])
>>> words.run_collection(retmax='5') 

unload_labels(verbose=True)¶: Unload labels from the object.

unload_terms(term_type='terms', reset=True, verbose=True)¶

Completely unload terms from the object.

Examples

Unload added terms:

>>> base = Base()
>>> base.add_terms(['frontal lobe', 'temporal lobe', 'parietal lobe', 'occipital lobe'])
>>> base.unload_terms()
Unloading terms.

Attributes

term_type{‘terms’, ‘inclusions’, ‘exclusions’, ‘labels’, ‘all’}: Which type of terms to unload.
resetbool, optional, default: True: Whether to reset in/exclusions to empty lists.
verbosebool, optional: Whether to be verbose in printing out any changes.

Examples using `lisc.Words`¶

Tutorial 01: Words Collection

Tutorial 02: Words Analysis

Tutorial 06: MetaData

lisc.Words¶

Examples using lisc.Words¶

Examples using `lisc.Words`¶