docs/develop/ICU-Tokenizer-Modules.md

   1 # Writing custom sanitizer and token analysis modules for the ICU tokenizer
   2
   3 The [ICU tokenizer](../customize/Tokenizers.md#icu-tokenizer) provides a
   4 highly customizable method to pre-process and normalize the name information
   5 of the input data before it is added to the search index. It comes with a
   6 selection of sanitizers and token analyzers which you can use to adapt your
   7 installation to your needs. If the provided modules are not enough, you can
   8 also provide your own implementations. This section describes the API
   9 of sanitizers and token analysis.
  10
  11 !!! warning
  12     This API is currently in early alpha status. While this API is meant to
  13     be a public API on which other sanitizers and token analyzers may be
  14     implemented, it is not guaranteed to be stable at the moment.
  15
  16
  17 ## Using non-standard sanitizers and token analyzers
  18
  19 Sanitizer names (in the `step` property) and token analysis names (in the
  20 `analyzer`) may refer to externally supplied modules. There are two ways
  21 to include external modules: through a library or from the project directory.
  22
  23 To include a module from a library, use the absolute import path as name and
  24 make sure the library can be found in your PYTHONPATH.
  25
  26 To use a custom module without creating a library, you can put the module
  27 somewhere in your project directory and then use the relative path to the
  28 file. Include the whole name of the file including the `.py` ending.
  29
  30 ## Custom sanitizer modules
  31
  32 A sanitizer module must export a single factory function `create` with the
  33 following signature:
  34
  35 ``` python
  36 def create(config: SanitizerConfig) -> Callable[[ProcessInfo], None]
  37 ```
  38
  39 The function receives the custom configuration for the sanitizer and must
  40 return a callable (function or class) that transforms the name and address
  41 terms of a place. When a place is processed, then a `ProcessInfo` object
  42 is created from the information that was queried from the database. This
  43 object is sequentially handed to each configured sanitizer, so that each
  44 sanitizer receives the result of processing from the previous sanitizer.
  45 After the last sanitizer is finished, the resulting name and address lists
  46 are forwarded to the token analysis module.
  47
  48 Sanitizer functions are instantiated once and then called for each place
  49 that is imported or updated. They don't need to be thread-safe.
  50 If multi-threading is used, each thread creates their own instance of
  51 the function.
  52
  53 ### Sanitizer configuration
  54
  55 ::: nominatim_db.tokenizer.sanitizers.config.SanitizerConfig
  56     options:
  57         heading_level: 6
  58
  59 ### The main filter function of the sanitizer
  60
  61 The filter function receives a single object of type `ProcessInfo`
  62 which has with three members:
  63
  64  * `place: PlaceInfo`: read-only information about the place being processed.
  65    See PlaceInfo below.
  66  * `names: List[PlaceName]`: The current list of names for the place.
  67  * `address: List[PlaceName]`: The current list of address names for the place.
  68
  69 While the `place` member is provided for information only, the `names` and
  70 `address` lists are meant to be manipulated by the sanitizer. It may add and
  71 remove entries, change information within a single entry (for example by
  72 adding extra attributes) or completely replace the list with a different one.
  73
  74 #### PlaceInfo - information about the place
  75
  76 ::: nominatim_db.data.place_info.PlaceInfo
  77     options:
  78         heading_level: 6
  79
  80
  81 #### PlaceName - extended naming information
  82
  83 ::: nominatim_db.data.place_name.PlaceName
  84     options:
  85         heading_level: 6
  86
  87
  88 ### Example: Filter for US street prefixes
  89
  90 The following sanitizer removes the directional prefixes from street names
  91 in the US:
  92
  93 ``` python
  94 import re
  95
  96 def _filter_function(obj):
  97     if obj.place.country_code == 'us' \
  98        and obj.place.rank_address >= 26 and obj.place.rank_address <= 27:
  99         for name in obj.names:
 100             name.name = re.sub(r'^(north|south|west|east) ',
 101                                '',
 102                                name.name,
 103                                flags=re.IGNORECASE)
 104
 105 def create(config):
 106     return _filter_function
 107 ```
 108
 109 This is the most simple form of a sanitizer module. If defines a single
 110 filter function and implements the required `create()` function by returning
 111 the filter.
 112
 113 The filter function first checks if the object is interesting for the
 114 sanitizer. Namely it checks if the place is in the US (through `country_code`)
 115 and it the place is a street (a `rank_address` of 26 or 27). If the
 116 conditions are met, then it goes through all available names and
 117 removes any leading directional prefix using a simple regular expression.
 118
 119 Save the source code in a file in your project directory, for example as
 120 `us_streets.py`. Then you can use the sanitizer in your `icu_tokenizer.yaml`:
 121
 122 ``` yaml
 123 ...
 124 sanitizers:
 125     - step: us_streets.py
 126 ...
 127 ```
 128
 129 !!! warning
 130     This example is just a simplified show case on how to create a sanitizer.
 131     It is not really read for real-world use: while the sanitizer would
 132     correctly transform `West 5th Street` into `5th Street`. it would also
 133     shorten a simple `North Street` to `Street`.
 134
 135 For more sanitizer examples, have a look at the sanitizers provided by Nominatim.
 136 They can be found in the directory
 137 [`nominatim/tokenizer/sanitizers`](https://github.com/osm-search/Nominatim/tree/master/nominatim/tokenizer/sanitizers).
 138
 139
 140 ## Custom token analysis module
 141
 142 ::: nominatim_db.tokenizer.token_analysis.base.AnalysisModule
 143     options:
 144         heading_level: 6
 145
 146
 147 ::: nominatim_db.tokenizer.token_analysis.base.Analyzer
 148     options:
 149         heading_level: 6
 150
 151 ### Example: Creating acronym variants for long names
 152
 153 The following example of a token analysis module creates acronyms from
 154 very long names and adds them as a variant:
 155
 156 ``` python
 157 class AcronymMaker:
 158     """ This class is the actual analyzer.
 159     """
 160     def __init__(self, norm, trans):
 161         self.norm = norm
 162         self.trans = trans
 163
 164
 165     def get_canonical_id(self, name):
 166         # In simple cases, the normalized name can be used as a canonical id.
 167         return self.norm.transliterate(name.name).strip()
 168
 169
 170     def compute_variants(self, name):
 171         # The transliterated form of the name always makes up a variant.
 172         variants = [self.trans.transliterate(name)]
 173
 174         # Only create acronyms from very long words.
 175         if len(name) > 20:
 176             # Take the first letter from each word to form the acronym.
 177             acronym = ''.join(w[0] for w in name.split())
 178             # If that leds to an acronym with at least three letters,
 179             # add the resulting acronym as a variant.
 180             if len(acronym) > 2:
 181                 # Never forget to transliterate the variants before returning them.
 182                 variants.append(self.trans.transliterate(acronym))
 183
 184         return variants
 185
 186 # The following two functions are the module interface.
 187
 188 def configure(rules, normalizer, transliterator):
 189     # There is no configuration to parse and no data to set up.
 190     # Just return an empty configuration.
 191     return None
 192
 193
 194 def create(normalizer, transliterator, config):
 195     # Return a new instance of our token analysis class above.
 196     return AcronymMaker(normalizer, transliterator)
 197 ```
 198
 199 Given the name `Trans-Siberian Railway`, the code above would return the full
 200 name `Trans-Siberian Railway` and the acronym `TSR` as variant, so that
 201 searching would work for both.
 202
 203 ## Sanitizers vs. Token analysis - what to use for variants?
 204
 205 It is not always clear when to implement variations in the sanitizer and
 206 when to write a token analysis module. Just take the acronym example
 207 above: it would also have been possible to write a sanitizer which adds the
 208 acronym as an additional name to the name list. The result would have been
 209 similar. So which should be used when?
 210
 211 The most important thing to keep in mind is that variants created by the
 212 token analysis are only saved in the word lookup table. They do not need
 213 extra space in the search index. If there are many spelling variations, this
 214 can mean quite a significant amount of space is saved.
 215
 216 When creating additional names with a sanitizer, these names are completely
 217 independent. In particular, they can be fed into different token analysis
 218 modules. This gives a much greater flexibility but at the price that the
 219 additional names increase the size of the search index.
 220