Package: litspy
LitSpyDESCRIPTIONThis package allows the user to search through all titles and abstracts available in Europe PMC for articles containing
co-occurence of the following:supplied genes and their synonymsan optionally supplied disease and its synonymsan optionally supplied tissue or organ and its synonymsoptionally other supplied keywordsand any other Europe PMC advanced search parameters desiredand produces summaries of the search results in HTML and optionally Excel format.INSTALLATIONThe tool is available from pypi, and can be easily installed and upgraded in the usual way using pip. Just ensure that you have Python3.6 or higher
installed on your machine, and run the commandpip install litspy(or, if your default Python version is Python2, replacepipwithpip3)USAGEGetting startedNote:replacepythonwithpython3in all commands if your default python version is not python3Obtaining usage informationTo read about the different arguments you can supply to LitSpy (such as input files, output files, logging
settings and more), runpython -m litspy -hBasic commands (examples)Unless specified otherwise, LitSpy assumes a UniProt gene ID for a human gene has been entered.
Therefore, a minimal search can simply include a human gene ID and a disease, tissue and/or keyword. For example:python -m litspy -g Cftr -d arthritisThe command can include multiple genes and multiple keywords (separated by spaces), but only one disease and one
tissue/organ. To search for phrases that include spaces, you should use quotes around the phrases:python -m litspy -g APOE APOC1 APOC2 -d "cystic fibrosis" -t liver -k "normal diet" biomarkerTo supply a Uniprot accession number instead of a gene ID, specify the UniProt ID type as accession using-uor--uniprot_id_type, for example:python -m litspy -g P13569 -u accession -d arthritisTo search for non-human genes, specify the appropriate UniProt taxonomy ID usingsor--taxid, for example:python -m litspy -g CFTR -d arthritis -s 10090Using input filesTo supply an input file, use-i(or--infile) followed by the path to the input file, for example:python -m litspy -i /home/myusername/documents/litspy_inputs/input1.xlsxLitSpy will preferentially take an input file over values supplied at the command line. If the following
command was entered, only the input file would be used and an appropriate warning would be loggedpython -m litspy -i path/to/input.xlsx -g CFTR APOEInput files should be spreadsheets in xlsx format, containing the following columns in the following order:UniProtIDIDTypeTaxIDKeywordCFTRgene9606normal diet, biomarkerCFTRgene9606childrenAPOEgene9606normal diet, biomarkerP13569accession9606biomarkerAdditional columns to the right are tolerated, but ignored. (They may be used for notes, for example)LitSpy runs one query per row in the spreadsheet (ignoring the headings).To query for a gene co-occurring with multiple keywords, enter the keywords as a comma-separated list in the 4th column
of the input file (note: quote marks are not needed in input files). To query for a gene that co-occurs withanyof
a list of keywords, you should enter separate rows for each keyword. So, for example, the input file above would return
documents containing CFTR AND normal diet AND biomarker, and also documents containing CFTR AND children.Create an Excel output fileTo get an output file of the results summary and details in Excel format, use-o(or--outfile) followed by
the full path to an output file:python -m litspy -g CFTR -d arthritis -o /home/myusername/documents/litspy_outputs/output1.xlsxIf you provide a path to an existing file, the file will be overwritten. If you provide a path to a new file, the new
file will be created.The Excel output file is createdin additionto the HTML results files, which are always created.Create output charts and top 10 listOutput charts are generated automatically if fewer than 30 genes are supplied. If more than 30 genes are supplied,
charting is turned off to prevent potential creation of 90+ images. To turn charting on or off despite input size, use
the-cor--make-chartsflag, with 'y' or 'n' to turn charting on or off respectively.A list of the ten most common terms (excluding search terms) can be generated for each result set by specifying
the-wor--top-tenflag with 'y'.For example:python -m litspy -i 'path/to/input.xlsx -w y -c ywill create result pages with charts and top ten lists no matter the number of entries in the supplied fileLoggingBy default, LitSpy logs to the console only at the warning level. To change the console logging level, supply a log
level argument by entering-l(or--log-level) followed by a valid logging level, for example:python -m litspy -g CFTR -d arthritis -l infoTo turn on logging to a log file, specify the-f(or--log-file) flag:python -m litspy -g CFTR -d arthritis -l warning -fThe log file is always logged at the info level.MultithreadingSome parts of the tool are able to run in parallel on many threads. You can specify the number of threads to use with
the-mor--multithreadflag, for example:python -m litspy -g CFTR -d arthritis -m 4If you do not specify the number of threads to use, then the tool will automatically determine the number of available
cores and use this as the maximum number of threads to use. It is possible that this will affect performance of
other tasks that the machine is running at the same time.Keyword synonym expansionTo attempt collection of synonyms for supplied keywords, specify the-e(or--expand-keywords) flag in the command:python -m litspy -g CFTR -d arthritis -k biomarker -eThis will return the synonyms from the first node matched (the best match) when searching for the term in the EBI OLS.Warning:It is expected that this generic searching will be far noisier on average than the more specific searches for
disease or tissue synonyms, and thereforethis option should be used cautiously.BACKGROUNDThe aim of this tool is to form part of my PhD project, where it will help to inform target novelty within particular
contexts, and be combined with other tools. However, it can also be useful as a standalone search tool; for example, to
identify articles of interest more comprehensively than by keyword searches that do not use synonym expansion.AUTHORE Croot, 2020,ec339@le.ac.uk, github.com/ec339LICENCEMIT (see LICENCE.txt)CHANGE LOGThere have currently been no major changes to the tool. Seecommits at githubfor information about minor updates.ACKNOWLEDGEMENTSOmixLitMinerAlthough the design and creation of this tool began beforePascal et al's 2020 publication(DOI: 10.3390/ijms21041374, PMID: 32092871), their tool OmixLitMiner provided inspiration for parts of this project;
particularly the use of UniProt to obtain alternative official gene names, and the output charts and styles.Supervision teamMy PhD supervisors, Dr. Thanos Didangelos, Dr. Richard Badge, and Prof. Louise WainOthersThomas Rowlands, co-developer of rtgo (used in LitSpy for multithreading)