Package: nlmunicipality
Guess the Dutch municipality name from user-provided locations.Simple examplefromnlmunicipality.guessimportGuessMunicipalityguesser=GuessMunicipality('../data/config')guesser.guess('Den Boscch')guesser.guess('Sumar')Note that creating aguesserobject can take a minute.See caveats below.How it worksGuessing the municipality may involve the following steps:Check if a result is already available for the input values provided (these are stored in thefound_resultsattribute);Look for exact match in municipality names;Look for exact match in former municipality names (and variants) and return current municipality name;Look for unique exact match in place names and return corresponding municipality name;Look for unique exact match in neighbourhood names and return corresponding municipality name;Look for fuzzy match in municipality names;Look for fuzzy match in former municipality names (and variants) and return current municipality name;Look for unique fuzzy match in place names and return corresponding municipality name;Look for unique fuzzy match in neighbourhood names and return corresponding municipality name.You can use the parameters for theguessmethod to control which steps will be included. For example, by settingcheck_fuzzy=False, you’ll exclude all steps involving looking for a fuzzy match.Creating a guesserMatch yearWhen creating aGuessMunicipalityobject, you can set thematch_yearparameter, which is the year for which a match will be tried to find. For example, with match_year set to 2020, Appingedam will be considered a municipality. If you set it to 2021 or higher, it will be considered a part of Eemsdelta.Custom recoding optionsYou can add options for recoding. For example, if the locations have been provided by foreign language speakers, they may use different spellings for some municipalities. Here’s an example of how you can deal with this:fromnlmunicipality.guessimportGuessMunicipality,RECODE_GEMrecode_gem=RECODE_GEMrecode_gem['haga']="'s-Gravenhage"guesser=GuessMunicipality('../data/config',recode_gem=recode_gem)guesser.guess('HAGA')Storing metadataThe package uses data from Statitics Netherlands (CBS) and from Wikipedia, which will be downloaded when you first create aGuessMunicipalityobject for a specific match year. If you set thepath_configparameter when creating the guesser, this data will be stored so that it won’t be necessary to re-download each time you create a new guesser.Using the guess methodFuzzy matchesUnless you setcheck_fuzzy=False, an attempt will be made to find a fuzzy match when no exact match can be found. Using thethreshold_fuzzyparameter, you can control how strict this will be applied (the parameter must have a value between 0 and 100, with 100 only allowing exact matches). Note that looking for fuzzy matches can take quite long.Thecheck_fuzzyparameter can be set when creating the guesser, or when calling theguessmethod.Former municipality namesUnless you setcheck_history=Falsewhen calling the guess method, an attempt will be made to match the input value with a former municipality and return the municipality that it is now part of. An example of where this might be useful is when you want to analyse geographic patterns in voting over time.Some former municipalities have been split up and divided over multiple municipalities. Using thethreshold_ratioyou can control how to deal with such situations. The default value is 80, which means that municipality A will be considered to be part of municipality B, if at least 80 percent of A’s population have been transferred to B.Using thedateparameter, you can limit the search to former municipalities that existed at that date. Provide the date as for example1950or19500101.Note that it will also be attempted to interpret the input value as anAmsterdamse Codeand return the corresponding current municipality. For now, this only works with Amsterdamse Codes forformermunicipalities.CleanIf you setclean=Truewhen calling the guess method, some cleaning will be applied to input values. For example, area codes will be replaced with the corresponding main place name (e.g.,020withamsterdam. Country names will be ignored.Note that in a previous version, province names would be removed from the input value. This has been dropped, because handling province names is complicated: province names may also be (former) municipality names (Groningen, Utrecht, Zeeland) or be part of municipality names (Súdwest-Fryslân, Midden-Groningen). The best way to handle province names will depend on characteristics of the dataset you’re working with.DelimitersWhen you call the guess method, you can set delimiters. Locations will then be split into substrings using the delimiters and for each substring, it will be tried to find a match. For example, if the place name isDelfshaven, Rotterdam, it will be tried to find a match first fordelfshavenand then forrotterdam.ProvinceIf you know that the location is within a specific province, you can specify this, which may prevent false matches. You could opt to combine this with setting a lower threshold for the quality of matches.fromnlmunicipality.guessimportGuessMunicipalityguesser=GuessMunicipality('../data/config',threshold=80)guesser.guess('Valkenburg',province='Zuid-Holland')Other optionsSeehelp(GuessMunicipality.guess).Check what worksWhat options get the best results will depend on characteristics of the dataset. You may want to try multiple options and compare where the results differ, to get an idea which approach best fits the data you’re working with.For example:guesser=GuessMunicipality('../data/config')df['guess_exact']=[guesser.guess(name,check_fuzzy=False)fornameindf.place_name]df['guess_fuzzy']=df.place_name.apply(guesser.guess)mask=df.guess_exact!=df.guess_fuzzydf[mask].sample(5)You can set thereturn_howparameter to get a hint as to how a match was found.Caveatsnlmunicipality may return incorrect matches or fail to return correct matches. If you run into something that doesn’t work properly, please let me know and I see if I can fix it. Note that there will always be ambiguities such as former municipalities that have been split, or multiple places with the same name.Installationpip install nlmunicipalityTodoConvert coordinates to municipality.