nutstools package

Submodules

nutstools.main module

A tool to convert postal codes to NUTS-values based on the NUTS files distributed by Eurostat.

Usage:

Examples:

Convert a postal code to NUTS:

> postalcode2nuts.exe --postal_code 2612AB

Output of this command is:

2612AB    NL333

Convert the file postal_codes_NL.txt with postal codes to NUTS:

>> postalcode2nuts.exe --input_file_name postal_codes_NL.txt --output_file_name -

gives the following output:

8277AM    NL211
2871KA    NL33B
9408BJ    NL131
3076KA    NL33C
3068LM    NL33C
7543GV    NL213

In case the –output_file_name argument is not given, the codes are written to file with the same name as the input file with a suffix nuts3 (default), where 3 stands for the level of the NUTS output. The level can be altered using the –level option.

Help:

PS>postalcode2nuts.exe --help

usage: postalcode2nuts [-h] [--version] [-p POSTALCODE] [-i INPUT_FILE_NAME]
                       [--nuts_file_name NUTS_INPUT_FILE_NAME] [-o OUTPUT_FILE_NAME] [-v] [-vv] [-l LEVEL]
                       [--year {2021}]
                       [--country {PT,DK,SE,PL,TR,MK,NO,SI,LV,ES,CH,NL,SK,CZ,LI,EL,HR,IS,LT,UK,IT,FI,HU,CY,EE,RS,IE,
                       RO,LU,BE,DE,FR,AT,BG}]
                       [--update_settings] [--force_download] [--directory DIRECTORY]

Converts a postal code to its NUTS code

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  -p POSTALCODE, --postal_code POSTALCODE
                        Postcode
  -i INPUT_FILE_NAME, --input_file_name INPUT_FILE_NAME
                        Input file with Postal codes
  --nuts_file_name NUTS_INPUT_FILE_NAME
                        Overrule input filename with the NUTS translation data
  -o OUTPUT_FILE_NAME, --output_file_name OUTPUT_FILE_NAME
                        Output file with Postal codes and NUTS
  -v, --verbose         set loglevel to INFO
  -vv, --debug          set loglevel to DEBUG
  -l LEVEL, --level LEVEL
                        The level at we want to get the NUTS-code
  --year {2021}         The year of the NUTS files
  --country {PT,DK,SE,PL,TR,MK,NO,SI,LV,ES,CH,NL,SK,CZ,LI,EL,HR,IS,LT,UK,IT,FI,HU,CY,EE,RS,IE,RO,LU,BE,DE,FR,AT,BG}
                        The country code for the NUTS file
  --update_settings     Update the settings file with the new values
  --force_download      Forces to download the datafile again, even if it already exists
  --directory DIRECTORY
                    The location of the the NUTS files. If not given, the default directory will be picked
  --config_show         Show the location of the configuration files and exit

nutstools.main.check_if_valid_nuts_level(value)[source]: check if the argument is a valid nuts level. Must be between 0 and 3

nutstools.main.main(args)[source]

Wrapper allowing postal_code2nuts() to be called with string arguments in a CLI fashion

Instead of returning the value from postal_code2nuts(), it prints the result to the stdout in a nicely formatted message.

Parameters:: args (List[str]) – command line parameters as list of strings (for example ["--verbose", "42"]).

nutstools.main.parse_args(args)[source]

Parse command line parameters

Parameters:: args (List[str]) – command line parameters as list of strings (for example ["--help"]).
Returns:: command line parameters namespace
Return type:: argparse.Namespace

nutstools.main.run()[source]

Calls main() passing the CLI arguments extracted from sys.argv

This function can be used as entry point to create console scripts with setuptools.

nutstools.main.setup_logging(loglevel)[source]

Setup basic logging

Parameters:: loglevel (int) – minimum loglevel for emitting messages

nutstools.nutsdata module

This file contains the global variables used in the code for NutsTools. It stores the default values. The values are stored in the settings file stored in the default location. The second run, the global variables are read from this settings file. You can modify the settings file to your needs.

nutstools.postalnuts module

Class definition for NutsTools. Can be used in your own Python code to retrieve the nuts data from the EU-website and convert postal codes in NUTS codes

Examples

In order to download the EU NUTS data to the default location, use create the NutsData object:

from nutstools.postalnuts import NutsData
nuts_data = NutsData()

In case the NUTS data was downloaded before, only the nuts_data object is created, but the data will not be downloaded again.

As a next step, you can use the NutsPostalCode class to import the NUTS-data and convert postal codes to NUTS:

nuts = NutsPostalCode(nuts_data.nuts_codes_file)

post_code = "2612AB"
nuts_code = nuts.one_postal2nuts(postal_code=post_code)
print(f"Postal code {post_code} has nuts code {nuts_code}")

The returned nuts_code is a string with the NUTS code, so the output looks like:

Postal code 2612AB has nuts code NL333

You can also convert a list or a serie of postal codes like this:

postal_codes = [
    "8277 AM",
    "2871 KA",
]

all_codes = nuts.postal2nuts(postal_codes=postal_codes)
print(all_codes)

The returned all_codes is a Series which looks like:

8277AM    NL211
2871KA    NL33B
9408BJ    NL131
3076KA    NL33C
3068LM    NL33C
7543GV    NL213
4181DG    NL224

Bases: object

Class to hold all the references to NUTS data

Parameters:

year (str, optional) – Year of the NUTS data. Default is 2021.
country (str, optional) – Two-letter code of the country to use for the NUTS data. Defaults to NL.
nuts_file_name (Path|str, optional) – Name of the file of the downloaded nuts data. Default is nutstools_settings.yml.
nuts_code_directory (Path|str, optional) – Name of the directory where the NUTS data is stored. Defaults to None, in which case the NUTS data will be stored to the default location (see directory attribute). If an alternative location is passed to this argument, the directory attributed is set to this location.
update_settings (bool, optional) – If true, the settings file is updated with the new options passed to this class. The defaults can also be altered in the nuts_file_name settings file it self.

directory

Location of the configuration settings file. Default is nutstools in eiter C:\Users\username\AppData\Local (Windows) or /home/username/.local/share (linux)

Type:: Path

cache_directory

directory where downloaded data is stored for reuse. Defaults to Cache relative directory.

Type:: Path

settings_file_name

Name of the settings file to store the default settings. Default is nutstools_settings.yml located in directory. This file is created the first run and read every next run. Altering the values in this file alters the default behaviour. The default behaviour can also be overwritten by using the update_settings command line argument

Type:: Path

url

The URL to the NUTS data at the EU website. Is stored in the settings file and can be altered there.

Type:: str

year

The year for which the NUTS data is retrieved. Default is 2021 (current latest version), but can be altered in the settings file.

Type:: str

country

Two-letter code to set the country for which we want to download the NUTS data. Default is NL. Can be altered using the country command line option combined with update_settings in order to force to rewrite the settings file

Type:: str

nuts_codes_file

The filename to the NUTS data downloaded from the EU website

Type:: Path

nuts_data

The Dataframe where the NUTS data is stored after reading the nuts_codes_file

Type:: DataFrame

download_nuts_codes()[source]

Download the NUTS data from the EU website

Notes

Open a session, either via kerberos and a proxy or via a normal request session

Returns:: True for success, False for failed download.
Return type:: bool

impose_nuts_settings()[source]: Read the settings of the tool from the stored settings file

class nutstools.postalnuts.NutsPostalCode(file_name: Path | str)[source]

Bases: object

Class to hold the postal nuts code

Parameters:: file_name (Path|str) – The nuts input file holding all the nuts codes. Can be either a pathlib Path or a string.

file_name

Path of the file contains the nuts code downloaded from the Eurostat website

Type:: Path|str

nuts_data

All the nuts data loaded from the file

Type:: DataFrame

nuts_key

Name of column containing the NUTS codes. Equal to the first column of the input data file

Type:: str

postal_codes_key

Name of the column containing the postal codes. Equal to the second column of the input data file

Type:: str

one_postal2nuts(postal_code: str, level: int = 3)[source]

Return the NUTS code for a single postal code

Parameters:

postal_code (str) – The postal code to retrieve the data for
level (int, optional) – The nuts level. Default = 3

Returns:

The nuts code belonging to the postal code

Return type:

str

postal2nuts(postal_codes: Series | list, level: int = 3)[source]

Convert the series or list of postal codes to a series of nuts code at level

Parameters:

postal_codes (DataFrame or Series) – Series or list of postal codes to be converted to NUTS codes
level (int, optional) – Level of the nuts codes. Either, 0, 1, 2 or 3. Default is 3

Returns:

The converted NUTS codes. The postal codes are put on the index.

Return type:

Series

Module contents

Basic package definition with version control