Skip to content

Commit 665bd52

Browse files
domdfcodingdomdfcoding
committed
Update docs
1 parent 20d4355 commit 665bd52

File tree

9 files changed

+91
-12
lines changed

9 files changed

+91
-12
lines changed

‎README.rst‎

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -165,7 +165,23 @@ For each of these hits, the reference data can be obtained as follows:
165165
ref_data = search.get_reference_data(hit.spec_loc)
166166
167167
168-
TODO
169-
-----
168+
Using Multiple Libraries
169+
*************************
170170

171-
1. Write comprehensive tests using pytest
171+
``pyms-nist-search`` can also be configured to search multiple libraries simultaneously,
172+
such as the NIST mainlib and some user libraries.
173+
The libraries to search are specified in a list of ``(<lib_path>, <lib_type>)`` tuples,
174+
where ``lib_path`` is the full path to the library on disk and ``lib_type``
175+
is ``pyms_nist_search.NISTMS_MAIN_LIB``, ``pyms_nist_search.NISTMS_USER_LIB`` or ``pyms_nist_search.NISTMS_REP_LIB``
176+
as applicable.
177+
178+
.. code-block:: python
179+
180+
search = pyms_nist_search.Engine(
181+
[
182+
(FULL_PATH_TO_MAIN_LIBRARY, pyms_nist_search.NISTMS_MAIN_LIB),
183+
(FULL_PATH_TO_REPLICATE_LIBRARY, pyms_nist_search.NISTMS_REP_LIB),
184+
(FULL_PATH_TO_USER_LIBRARY, pyms_nist_search.NISTMS_USER_LIB),
185+
],
186+
work_dir=FULL_PATH_TO_WORK_DIR,
187+
)

‎doc-source/api.rst‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,30 @@ API Reference
66
:no-members:
77

88

9+
:mod:`~pyms_nist_search`
10+
----------------------------------
11+
12+
This module exposes many constants used by ``pyms-nist-search``.
13+
The most notable are detailed below.
14+
15+
.. py:data:: NISTMS_MAIN_LIB
16+
17+
Indicates the NIST/EPA/NIH main library.
18+
19+
.. py:data:: NISTMS_REP_LIB
20+
21+
Indicates the NIST/EPA/NIH replicate spectra library.
22+
23+
.. py:data:: NISTMS_USER_LIB
24+
25+
Indicates a user-created library or simular.
26+
27+
.. py:data:: NISTMS_MAX_LIBS
28+
29+
The maximum number of libraries that may be searched.
30+
31+
.. latex:clearpage::
32+
933
:mod:`~pyms_nist_search.base`
1034
----------------------------------
1135

‎doc-source/conf.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,3 +97,6 @@ def setup(app):
9797
app.add_js_file("twemoji.js")
9898
app.add_css_file("twemoji.css")
9999
app.add_transform(sphinxemoji.EmojiSubstitutions)
100+
101+
102+
nitpicky = True

‎doc-source/usage.rst‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,3 +39,24 @@ For each of these hits, the reference data can be obtained as follows:
3939
4040
for hit in hit_list:
4141
ref_data = search.get_reference_data(hit.spec_loc)
42+
43+
Using Multiple Libraries
44+
===========================
45+
46+
``pyms-nist-search`` can also be configured to search multiple libraries simultaneously,
47+
such as the NIST mainlib and some user libraries.
48+
The libraries to search are specified in a list of ``(<lib_path>, <lib_type>)`` tuples,
49+
where ``lib_path`` is the full path to the library on disk and ``lib_type``
50+
is :data:`pyms_nist_search.NISTMS_MAIN_LIB`, :data:`pyms_nist_search.NISTMS_USER_LIB` or :data:`pyms_nist_search.NISTMS_REP_LIB`
51+
as applicable.
52+
53+
.. code-block:: python
54+
55+
search = pyms_nist_search.Engine(
56+
[
57+
(FULL_PATH_TO_MAIN_LIBRARY, pyms_nist_search.NISTMS_MAIN_LIB),
58+
(FULL_PATH_TO_REPLICATE_LIBRARY, pyms_nist_search.NISTMS_REP_LIB),
59+
(FULL_PATH_TO_USER_LIBRARY, pyms_nist_search.NISTMS_USER_LIB),
60+
],
61+
work_dir=FULL_PATH_TO_WORK_DIR,
62+
)

‎repo_helper.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,3 +95,6 @@ github_ci_requirements:
9595
- pip config set global.prefer-binary true
9696

9797
pre_commit_exclude: "\\.NUM$"
98+
99+
sphinx_conf_epilogue:
100+
- nitpicky = True

‎src/pyms_nist_search/docker_engine.py‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -115,8 +115,9 @@ class Engine:
115115
search.full_spectrum_search(ms, n_hits=5)
116116
117117
.. versionchanged:: 0.6.0 Added context manager support.
118+
.. versionchanged:: 0.8.0 Add support for searching multiple libraries.
118119
119-
:param lib_path: The path to the mass spectral library.
120+
:param lib_path: The path to the mass spectral library, or a list of ``(<lib_path>, <lib_type>)`` tuples giving multiple libraries to search.
120121
:param lib_type: The type of library. One of ``NISTMS_MAIN_LIB``, ``NISTMS_USER_LIB``, ``NISTMS_REP_LIB``.
121122
:param work_dir: The path to the working directory.
122123
@@ -437,6 +438,8 @@ def get_reference_data(self, spec_loc: int) -> ReferenceData:
437438
def get_lib_paths(self) -> List[str]:
438439
"""
439440
Returns the list of library names currently in use.
441+
442+
.. versionadded:: 0.8.0
440443
"""
441444

442445
retry_count = 0
@@ -457,7 +460,9 @@ def get_lib_paths(self) -> List[str]:
457460
@require_init
458461
def get_active_libs(self) -> List[int]:
459462
"""
460-
Returns the active librararies, as their (zero-based) indices in the output of :meth:~.WinEngine.get_lib_names()`.
463+
Returns the active librararies, as their (zero-based) indices in the output of :meth:`~.docker_engine.Engine.get_lib_paths`.
464+
465+
.. versionadded:: 0.8.0
461466
"""
462467

463468
retry_count = 0

‎src/pyms_nist_search/reference_data.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ class ReferenceData(NISTBase):
7373
:param mass_spec: The reference mass spectrum.
7474
:param synonyms: List of synonyms for the compound.
7575
:param exact_mass: Not used.
76-
:param lib_idx: The (zero-based) index of the library the result was found in (see :meth:`~.WinEngine.get_lib_names()`).
76+
:param lib_idx: The (zero-based) index of the library the result was found in (see :meth:`~.win_engine.Engine.get_lib_paths`).
7777
7878
.. latex:vspace:: 100px
7979
"""
@@ -193,7 +193,7 @@ def synonyms(self) -> List[str]:
193193
@property
194194
def lib_idx(self) -> int:
195195
"""
196-
The (zero-based) index of the library the result was found in (see :meth:`~.Engine.get_lib_names()`).
196+
The (zero-based) index of the library the result was found in (see :meth:`~.win_engine.Engine.get_lib_paths`).
197197
"""
198198

199199
return int(self._lib_idx)

‎src/pyms_nist_search/search_result.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ class SearchResult(NISTBase):
5858
:param reverse_match_factor:
5959
:param hit_prob:
6060
:param spec_loc: The location of the reference spectrum in the library.
61-
:param lib_idx: The (zero-based) index of the library the result was found in (see :meth:`~.WinEngine.get_lib_names()`).
61+
:param lib_idx: The (zero-based) index of the library the result was found in (see :meth:`~.win_engine.Engine.get_lib_paths`).
6262
6363
.. latex:vspace:: 20px
6464
"""
@@ -114,7 +114,7 @@ def spec_loc(self) -> int:
114114
"""
115115
The location of the reference spectrum in the library.
116116
117-
This can then be searched using the :meth:`~pynist.win_engine.Engine.get_reference_data` method of the
117+
This can then be searched using the :meth:`~.win_engine.Engine.get_reference_data` method of the
118118
search engine to obtain the reference data.
119119
"""
120120

@@ -123,7 +123,7 @@ def spec_loc(self) -> int:
123123
@property
124124
def lib_idx(self) -> int:
125125
"""
126-
The (zero-based) index of the library the result was found in (see :meth:`~.WinEngine.get_lib_names()`).
126+
The (zero-based) index of the library the result was found in (see :meth:`~.win_engine.Engine.get_lib_paths`).
127127
"""
128128

129129
return int(self._lib_idx)

‎src/pyms_nist_search/win_engine.py‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,10 @@ class Engine:
6060
6161
.. TODO:: Search by Name. See page 13 of the documentation.
6262
63-
:param lib_path: The path to the mass spectral library.
63+
.. versionchanged:: 0.6.0 Added context manager support.
64+
.. versionchanged:: 0.8.0 Add support for searching multiple libraries.
65+
66+
:param lib_path: The path to the mass spectral library, or a list of ``(<lib_path>, <lib_type>)`` tuples giving multiple libraries to search.
6467
:param lib_type: The type of library. One of ``NISTMS_MAIN_LIB``, ``NISTMS_USER_LIB``, ``NISTMS_REP_LIB``.
6568
:param work_dir: The path to the working directory.
6669
"""
@@ -234,6 +237,8 @@ def get_reference_data(spec_loc: int) -> ReferenceData:
234237
def get_lib_paths(self) -> List[str]:
235238
"""
236239
Returns the list of library names currently in use.
240+
241+
.. versionadded:: 0.8.0
237242
"""
238243

239244
return self._lib_paths.rstrip('\x00').split(_core.NISTMS_PATH_SEPARATOR)
@@ -242,7 +247,9 @@ def get_lib_paths(self) -> List[str]:
242247
@staticmethod
243248
def get_active_libs() -> List[int]:
244249
"""
245-
Returns the active librararies, as their (zero-based) indices in the output of :meth:`~.WinEngine.get_lib_names()`.
250+
Returns the active librararies, as their (zero-based) indices in the output of :meth:~.win_engine.Engine.get_lib_paths`.
251+
252+
.. versionadded:: 0.8.0
246253
"""
247254

248255
return _core._get_active_libs()

0 commit comments

Comments
 (0)