[DOC] Improve search documentation #1989

joergi-w · 2020-07-20T08:55:41Z

I fixed some inconsistencies and missing documentation in the search module.

MitraDarja

LGTM, just one question.

MitraDarja · 2020-07-21T09:22:30Z

include/seqan3/search/all.hpp

+ * The k-mer can be either an exact string of length k or it can contain one or more wildcards,
+ * which denote positions of arbitrary characters.


Do we want to give an example of a k-mer with wildcards? Or refer to the documentation where the use of wildcards is explained?

codecov · 2020-07-21T09:32:22Z

Codecov Report

Merging #1989 into master will increase coverage by 0.00%.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #1989   +/-   ##
=======================================
  Coverage   97.88%   97.88%           
=======================================
  Files         261      261           
  Lines        9825     9838   +13     
=======================================
+ Hits         9617     9630   +13     
  Misses        208      208

Impacted Files	Coverage Δ
...an3/search/configuration/default_configuration.hpp	`100.00% <ø> (ø)`
include/seqan3/search/kmer_index/shape.hpp	`100.00% <ø> (ø)`
include/seqan3/range/views/minimiser_hash.hpp	`100.00% <0.00%> (ø)`
include/seqan3/core/algorithm/configuration.hpp	`100.00% <0.00%> (ø)`
include/seqan3/range/views/minimiser.hpp	`99.03% <0.00%> (+0.03%)`	⬆️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 30e8966...1c425de. Read the comment docs.

MitraDarja

Thanks for the addition! :)

joergi-w · 2020-07-21T09:49:20Z

Thanks, that was fast ;)

eseiler

Looks good, but we do not offer a k-mer index implementation

eseiler · 2020-07-21T10:57:49Z

include/seqan3/search/all.hpp

+ * SeqAn currently implements two kinds of indices: FM indices and k-mer indices (also known as q-gram indices).
+ * Generally speaking, k-mer indices support very fast searching of exact k-mers (strings of length k) or k-mers with
+ * predefined wildcard positions, which match with any character.
+ * FM indices on the other hand are more versatile and work
+ * with arbitrary pattern lengths and error numbers or positions.


We do not have a k-mer index implementation

Ah, that's why I couldn't find it! I attempted to write a snippet for it 😅

eseiler · 2020-07-21T10:59:57Z

include/seqan3/search/all.hpp

+ * In the future we plan to improve the optimum search schemes, such that they handle unidirectional indices and
+ * higher error counts.


Suggested change

* In the future we plan to improve the optimum search schemes, such that they handle unidirectional indices and

* higher error counts.

* In the future, we plan to improve the optimum search schemes to handle higher error counts.

Unless I'm mistaken, with unidirectional indices you can only do backtracking, so there is no point for the search schemes.

eseiler · 2020-07-21T11:01:37Z

include/seqan3/search/all.hpp

+ * # K-mer Indices
+ *
+ * A k-mer index can be used to efficiently retrieve all occurrences of a certain k-mer in the text.
+ * The k-mer can be either an exact string of length k or it can contain one or more wildcards,
+ * which denote positions of arbitrary characters.
 *
+ * An exact k-mer is represented as seqan3::ungapped, and wildcards can be defined with seqan3::shape.
+ * Please check the respective documentation for details and examples.


Either we \if the k-mer index stuff, or clearly state that they are not here yet.
For the in-general k-mer description I would add a link to the kmer_hash_view / minimiser_view (maybe via \sa)

eseiler · 2020-07-21T11:03:12Z

include/seqan3/search/kmer_index/all.hpp

+ * \brief Implementation of a k-mer Index.
+ *
+ * \details
+ *
+ * A k-mer index is a data structure that stores all occurrences of k-mers in a text.
+ * A k-mer can be either an exact string of length k or it can contain one or more wildcards,
+ * which denote positions of arbitrary characters.
+ *
+ * The index is very fast for retrieving all occurrences of a k-mer in the underlying text.
+ * Usually the query length (k) is small and the underlying text is very large.
+ * The parameter k and the position(s) of wildcards must be fixed at index creation.


The only thing here is currently the shape :)

joergi-w · 2020-07-22T08:37:21Z

I removed the part in the introduction. Below in the index section I marked it as not implemented, because users may be interested in what's coming. In the k-mer index landing page I phrased it "shapes for a k-mer index".

eseiler · 2020-07-22T12:47:41Z

include/seqan3/search/all.hpp

+ * with arbitrary pattern lengths and error numbers or positions.
+ * \else
+ * SeqAn currently implements only the FM index and a k-mer index is planned. The FM index works
+ * with arbitrary pattern lengths and error numbers or positions.


Suggested change

* with arbitrary pattern lengths and error numbers or positions.

* with arbitrary pattern lengths and error numbers.

The positions probably refers to "you can have an error anywhere in the query" ?
But I think it's rather confusing without additional explanation and would just remove it.

Yes that was my intention...

eseiler · 2020-07-22T12:48:18Z

include/seqan3/search/all.hpp

- * predefined wildcard positions that do not have to match. FM indices on the other hand are more versatile and work
- * with arbitrary pattern lengths and error numbers / positions.
- * \todo k-mer indices are coming soon. Stay tuned!
+ *       Add a description of the DREAM index here.


Suggested change

* Add a description of the DREAM index here.

* \todo Add a description of the DREAM index here.

This is a continuation of the line above and is currently displayed in the same todo box.
Probably you intend to make a new todo item, so I change it :)

eseiler · 2020-07-22T12:48:56Z

include/seqan3/search/all.hpp

- * Latter are currently only available for searches with up to and including three errors using bidirectional indices.
- * The optimum search schemes will be improved in the future to handle unidirectional indices and higher error counts.
+ * The latter are currently only available for searches with up to three errors using bidirectional indices.
+ * In the future we plan to improve the optimum search schemes, to handle


Suggested change

* In the future we plan to improve the optimum search schemes, to handle

* In the future we plan to improve the optimum search schemes to handle

eseiler

Thanks!

(travis is green but did not report back)

[DOC] improve search documentation

aa166bd

joergi-w force-pushed the doc/search branch from 526b462 to aa166bd Compare July 21, 2020 08:57

joergi-w requested a review from MitraDarja July 21, 2020 09:09

joergi-w self-assigned this Jul 21, 2020

MitraDarja requested changes Jul 21, 2020

View reviewed changes

add information on shapes to k-mer index

ad18f1c

MitraDarja approved these changes Jul 21, 2020

View reviewed changes

MitraDarja requested a review from smehringer July 21, 2020 09:48

joergi-w requested review from eseiler and removed request for smehringer July 21, 2020 09:50

eseiler requested changes Jul 21, 2020

View reviewed changes

[DOC] k-mer index is not implemented

db362e3

joergi-w requested a review from eseiler July 22, 2020 08:37

eseiler requested changes Jul 22, 2020

View reviewed changes

[DOC] small documentation fixes

1c425de

joergi-w requested a review from eseiler July 22, 2020 14:58

eseiler approved these changes Jul 22, 2020

View reviewed changes

eseiler merged commit 87cecde into seqan:master Jul 22, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DOC] Improve search documentation #1989

[DOC] Improve search documentation #1989

joergi-w commented Jul 20, 2020

MitraDarja left a comment

MitraDarja Jul 21, 2020

codecov bot commented Jul 21, 2020 •

edited

Loading

MitraDarja left a comment

joergi-w commented Jul 21, 2020

eseiler left a comment

eseiler Jul 21, 2020

joergi-w Jul 22, 2020

eseiler Jul 21, 2020

eseiler Jul 21, 2020

eseiler Jul 21, 2020

joergi-w commented Jul 22, 2020

eseiler Jul 22, 2020

joergi-w Jul 22, 2020

eseiler Jul 22, 2020

joergi-w Jul 22, 2020

eseiler Jul 22, 2020

eseiler left a comment

		* The k-mer can be either an exact string of length k or it can contain one or more wildcards,
		* which denote positions of arbitrary characters.

		* In the future we plan to improve the optimum search schemes, such that they handle unidirectional indices and
		* higher error counts.

	* In the future we plan to improve the optimum search schemes, such that they handle unidirectional indices and
	* higher error counts.
	* In the future, we plan to improve the optimum search schemes to handle higher error counts.

	* with arbitrary pattern lengths and error numbers or positions.
	* with arbitrary pattern lengths and error numbers.

	* Add a description of the DREAM index here.
	* \todo Add a description of the DREAM index here.

[DOC] Improve search documentation #1989

[DOC] Improve search documentation #1989

Conversation

joergi-w commented Jul 20, 2020

MitraDarja left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented Jul 21, 2020 • edited Loading

Codecov Report

MitraDarja left a comment

Choose a reason for hiding this comment

joergi-w commented Jul 21, 2020

eseiler left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joergi-w commented Jul 22, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eseiler left a comment

Choose a reason for hiding this comment

codecov bot commented Jul 21, 2020 •

edited

Loading