Skip to content

Commit d98a610

Browse files
author
Gerit Wagner
committed
docs: update functional overview
1 parent 5135408 commit d98a610

File tree

2 files changed

+25
-2
lines changed

2 files changed

+25
-2
lines changed

docs/source/index.rst

Lines changed: 25 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -115,10 +115,33 @@ A Jupyter Notebook demo (hosted on Binder) is available here:
115115
Functional overview
116116
======================
117117

118-
The search-query package supports the entire lifecycle of academic search query management.
119-
Below is a high-level overview of the core functionalities:
118+
*search-query* treats academic search strategies as structured query objects rather than static strings.
119+
Query objects can be created programmatically or derived from search strings or JSON files, and are represented as object-oriented structures that capture Boolean logic, nesting, and field restrictions.
120+
Based on a query object, *search-query* supports the following operations:
121+
122+
- **Load:** *search-query* provides parsing capabilities to ingest search queries from both raw strings and JSON files.
123+
It parses database-specific query strings into internal, object-oriented representations of the search strategy.
124+
This allows the tool to capture complex Boolean logic and field restrictions in a standardized form.
125+
126+
- **Save:** Researchers can serialize the query object back into a standard string or file format for reporting and reuse.
127+
This facilitates transparency and reproducibility by allowing search strategies to be easily reported, shared or deposited.
128+
129+
- **Lint:** *search-query* can apply linters to detect syntactical errors or inconsistencies that might compromise the search.
130+
It can check for issues such as unbalanced parentheses, logical operator misuse, or database-specific syntax errors.
131+
132+
- **Translate:** The library can convert a query from one database syntax into another, enabling cross-platform use of search strategies.
133+
Using a generic query object as an intermediate representation, *search-query* currently supports translations between Web of Science, PubMed, and EBSCOHost.
134+
135+
- **Improve:** Beyond basic syntax checking and translation, *search-query* aims to support query improvement to enhance recall and precision.
136+
As queries are represented as manipulable objects, researchers can programmatically experiment with modifications — for example, adding synonyms or adjusting field scopes — to observe how these changes affect the search results.
137+
138+
- **Automate:** Automation primarily refers to the integration with systematic review management systems, such as `CoLRev <https://github.com/CoLRev-Environment/colrev?tab=readme-ov-file>`_.
139+
The library offers programmatic access via its Python API, which means it can be embedded in scripts and pipelines to run searches automatically.
140+
It also provides a command-line interface and git pre-commit hooks, allowing researchers to incorporate query validation into version control and continuous integration setups.
120141

121142
.. image:: presentation.png
143+
:width: 800 px
144+
:align: center
122145

123146
.. toctree::
124147
:hidden:

docs/source/presentation.png

-492 KB
Loading

0 commit comments

Comments
 (0)