docs/modules/admin_initial_setup/pages/dym_admin.adoc

   1 = Did You Mean?: Search Suggestions Administration
   2 :toc:
   3
   4 indexterm:[Searching,Search Suggestions]
   5
   6 == Introduction
   7
   8 As of 3.7, the work for Did You Mean enables search suggestions for a search comprising a single word within a single search class. For the purposes of suggestions, a search class in Evergreen is a keyword, title, author, series, or subject. Search suggestions are available in the public catalog (both TPAC and Bootstrap versions), the Children's OPAC (KPAC), and the Angular Staff Catalog.
   9
  10 Future iterations of this project are planning to add multi word, cross
  11 class, and other search suggestion mechanisms.
  12
  13 Several search suggestion ordering mechanisms have been added, and are
  14 described below in the Library Settings section. The relative weights of
  15 each suggestion ordering mechanism can be adjusted to prioritize
  16 different suggestion routes. Each Evergreen organization will need to
  17 determine the best configuration of weights and suggestion ordering
  18 settings.
  19
  20 Search suggestions are based on existing bibliographic data, and are
  21 offered for potentially correctable spelling mistakes. A new set of
  22 tables have been added to collect bibliographic data and build an
  23 internal dictionary of potential search suggestions. When a catalog
  24 search meets criteria for offering suggestions, this dictionary is used
  25 to generate the suggestions.
  26
  27 The end user will be shown a configurable number of suggestions,
  28 hyperlinked to execute a new search based on that suggestion. Any search
  29 options such as Format that were initially set will be carried over to
  30 the new search.
  31
  32 Evergreen’s existing use of search term stemming has not been altered as
  33 a consequence of this work.
  34
  35 == Search Results Display
  36
  37 In all cases, search suggestions will be offered for potentially
  38 correctable spelling mistakes if a search retrieves fewer than a
  39 configured number of results; and potential suggested terms appear at
  40 least a configurable number of times within the bibliographic data. Both
  41 of these thresholds are configured via Library Settings described below.
  42
  43 For examples of where suggestions display in various public catalog interfaces, please see the documentation in the  xref:opac:using_the_public_access_catalog.adoc#did_you_mean[Did You Mean?] section of the OPAC documentation.
  44
  45 Search suggestions in the Staff Catalog appear at the bottom of the search area.
  46
  47 image::media/staffcat.png[Search suggestions in the Staff Catalog]
  48
  49 == Administration
  50
  51 === Library Settings
  52
  53 Search suggestions are controlled by several Library Settings. Three
  54 settings set thresholds for spelling suggestions, and three settings
  55 control the weighting of different suggestion mechanisms. A lower number
  56 represents a ‘lighter’ weight. All settings accept a number value as
  57 input. Library settings are inheritable, unless there is an
  58 organizationally closer setting.
  59
  60 * *Maximum search result count at which spelling suggestions may be offered*
  61 ** Default value is 0, which means suggestions will only be offered if
  62 there are no results.
  63 ** If a search has this number or fewer results, and there are correctable
  64 spelling mistakes, a suggested search may be provided.
  65 ** If you want all searches to generate suggestions, you can set this to an
  66 artificially high number, but it’s possible that this will generate
  67 less-useful suggestions.
  68 * *Minimum required uses of a spelling suggestions that may be offered*
  69 ** Default is 1.
  70 ** The number of indexed bibliographic strings in which a spelling
  71 suggestion must appear in order to be offered to a user. Suggestions
  72 must appear in the bib data.
  73 * *Maximum number of spelling suggestions that may be offered*
  74 ** The maximum recommended value for this setting is 3, since suggestions
  75 become rapidly less useful beyond that point.
  76 ** If this is set to 0, no suggestions will be provided.
  77 ** All values other than 0 only provide suggestions that meet the *Minimum
  78 required uses* threshold, and only when the *Maximum search result
  79 count* threshold is not passed.
  80 ** If this is set to -1, the system will provide the best suggestion
  81 (dependent on the weights of various suggestion mechanisms) if and only
  82 if the term is considered misspelled based on the *Minimum required
  83 uses* setting.
  84 ** If this is set to 1 or more, that is the maximum number of suggestions
  85 that will be provided.
  86 * *Pg_trgm score weighting in OPAC spelling suggestions*
  87 ** Defaults to 0 for "off".
  88 ** Controls the relative weight of the scaled pg_trgm component.
  89 ** Input can be any positive or negative whole number, but testing
  90 demonstrates that setting this to 1 can significantly improve
  91 suggestions for most catalogs.
  92 * *Soundex score weighting in OPAC spelling suggestions*
  93 ** Defaults to 0 for "off".
  94 ** Controls the relative weight of the scaled soundex component.
  95 ** Input can be any positive or negative whole number, but testing
  96 demonstrates that setting this to 1 can improve suggestions for catalogs
  97 that are primarily English.
  98 * *QWERTY Keyboard similarity score weighting in OPAC spelling
  99 suggestions*
 100 ** Defaults to 0 for "off".
 101 ** Controls the relative weight of the scaled keyboard distance component.
 102 ** While this option is available, it can have a negative impact on
 103 suggestions and a value greater than 0 is not recommended for most
 104 catalogs.
 105 ** If an administrator decides to use this weighting, it will accept any
 106 positive or negative whole number value.
 107
 108
 109 The three similarity measures, Pg_trgm (Tri-gram), Soundex, and QWERTY
 110 Keyboard similarity, are calculated by comparing the user's search input
 111 to each potential suggestion. The Library Setting numerical values for
 112 Pg_trgm, Soundex, and QWERTY are multipliers for each similarity
 113 measure. For example, setting the Pg_trgm weight to 2 will double the
 114 raw score for that similarity measure.
 115
 116 The final order of a group of potential suggestions is determined first
 117 by the Damerau-Levenshtein edit distance, and then by the summed value
 118 of the weighting measures, each multiplied by its score weight. If
 119 suggestions coming from a particular corpus are shown to benefit from
 120 giving additional consideration to one or more of the measures, their
 121 weighting score can be increased.
 122
 123 Empirical testing and existing research shows that increasing the weight
 124 of any similarity measure beyond 1 is not useful in a reasonable,
 125 representative set of bibliographic records, and that a multiplier of 1
 126 for Pg_trgm and Soundex is ideal for primarily-English catalogs, but all
 127 data sets vary.
 128
 129 === Internal flags
 130
 131 The suggestion mechanism primarily uses a SymSpell implementation in
 132 Evergreen’s Postgres database. The SymSpell edit distance and prefix key
 133 length are controlled by two internal global flags,
 134 *symspell.prefix_length* and *symspell.max_edit_distance*. A full
 135 dictionary rebuild is required if either of these flags are changed.
 136
 137 The SymSpell algorithm mandates the use of the Damerau-Levenshtein
 138 algorithm which includes insertion, deletion, substitution, and
 139 transposition cost calculations. While the original plan was to make use
 140 of the built-in Postgres implementation of the Levenshtein edit distance
 141 algorithm, results of partner testing led us to replace the built-in
 142 option with an external Damerau-Levenshtein implementation.
 143
 144 A recommended set of values for the SymSpell settings is *6* for
 145 *symspell.prefix_length* and *3* for *symspell.max_edit_distance*.
 146
 147 This set of values is known to provide a very good balance between
 148 accuracy and resource consumption based on empirical testing of the
 149 algorithm and analysis of English language texts. For further
 150 explanation of why these settings are recommended, please see
 151 https://medium.com/@wolfgarbe/1000x-faster-spelling-correction-algorithm-2012-8701fcd87a5f[this article] and the embedded links to benchmarks and later improvements.