Configuration Files

The appearance and operation of mapdata can be modified using configuration files. Configurable options include:

• The default type and color of the symbol that used to mark locations.

• The default type and color of the symbol that is used to mark selected locations.

• The font, size, color, and position of the location labels.

• Whether multiple locations may be selected, or only one selected.

• The tile servers that can be used for the basemap.

• The symbols that are available to mark locations.

• Connection settings for a database.

mapdata will automatically read information from up to five configuration files in different locations, if they are present. The five locations are:

• The system-wide application data directory. This is /etc on Linux, and %APPDATA% on Windows.

• The directory where mapdata.py is located.

• The user-specific configuration directory. This is a directory named .config under the user’s home directory on both Linux and Windows.

• The directory where the initial data file is located, if a data file is specified on the command line.

• The user’s current directory.

The name of the configuration file, in all locations, is mapdata.conf.

Configuration data is read from these files in the order listed above. Information in later files may augment or replace information in earlier files. Options and arguments specified on the command line will further augment or override information specified in the configuration files.

In addition, configuration files can be read after the program has started, using an option on the File menu.

Configuration files use the INI file format. Section names are case sensitive and must be all in lowercase. Setting (property) names are not case sensitive. Setting values are read as-is and may or may not be case sensitive, depending on their use. Comments can be included in configuration files; each comment line must start with the “#” character.

The section and setting names that may be used in a configuration file are listed below.

Section basemap_tile_servers

Each setting in this section should be the name of a basemap tile server. These names will appear in the list of options that can be selected via the map interface. Each setting value should be the URL for that tile server. Within that URL, placeholders for the zoom level, x position, and y position should be “{z}”, “{x}”, and “{y}”, respectively.

If the URL must include an API key, the placeholder for the API key should be “<API_KEY>”.

Section api_keys

Each setting in this section should be the name of a basemap tile server that requires an API key. This tile server name must match one of those in the basemap_tile_servers section of this configuration file, or a configuration file that was previously read.

The setting value should be the API key for the corresponding tile server. This value will be substituted in place of the “<API_KEY>” placeholder in the URL for the tile server.

Section map_attributions

Each setting in this section should be the name of a basemap tile server that appears in the basemap_tile_servers section. Each setting value should be a string, or a comma-delimited list of strings, that identify the source(s) of the basemap data. Each source name may be followed by a URL in angle brackets.

If a basemap tile server does not have an associated attribution, it will not be available to be used on the map.

The attribution for the basemap in use will appear at the lower right corner of the map.

Section map_color_adj

Each setting in this section should be the name of a basemap tile server that appears in the basemap_tile_servers section. Each setting value should be a sequence of three floating-point numbers. These numbers represent the adjustment to be made to the color saturation, contrast, and brightness, respectively, of the basemap tiles. The numbers should be separated by commas or spaces. Negative numbers decrease the saturation, contrast, and brightness, and positive numbers increase these values. A value of zero causes no change. Practical limits on these values are -0.5 to 0.5, though there is no limitation on use of values outside this range.

Section symbols

Each setting in this section should be the name of a symbol that is intended to be used to mark locations on the map. The corresponding value should be the filename (with path) of an X bitmap file (.xbm) that describes that symbol.

The built-in symbols are shown on the Symbols page. If a new symbol uses the same name as a built-in symbol, the built-in symbol will be replaced.

Section connect

db_type

The type of DBMS. Valid values are: ‘p’: PostgreSQL, ‘l’: SQLite, ‘k’: DuckDB, ‘m’: MySQL or MariaDB, ‘o’: Oracle, and ‘f’: Firebird.

server

The server name or address for client-server databases.

port

The port for client-server databases. This is only needed if it is different from the default.

database or db

The database name.

file

The file name for file-based databases. If no other database connection information is given, this will be interpreted as the data file to import.

user or username

The user name, for use with client-server databases.

no_password

A True/False value indicating whether mapdata should prompt for a password when a user name is provided for a client-server database. By default, mapdata will prompt for a password, but a value of ‘True’ for this setting will suppress the password prompt.

table

The name of the database table to import.

script

The name (including path if necessary) of a file containing a SQL script that is to be run before importing data from the database table.

Section defaults

basemap

The basemap (tile server) to use for the initial map display. Built-in tile server names are “OpenStreetMap”, “Google streets”, “Google satellite”, “Open topo map”, and “Stamen terrain”. The default is “OpenStreetMap”. Other tile servers can be used if they are specified in the basemap_tile_servers section of a configuration file.

color_column

The name of the column in the data table containing color names that can be used for location markers. The use_data_color setting (and command-line arguments) determine whether these colors will be used.

datafile

The name of a file containing data to import. This may also be interpreted as the name of a file-based database if other database connection information is provided in a configuration file or on the command line.

id_column

The name of the column in the data table that contains identifers that will be used to label each data row on the map.

imagefile

The name of an image file to create containing the map with location markers.

imagewait

The time, in seconds, to wait between importing data and exporting an image of the map.

label_bold

Whether or not to display the label in boldface. Valid values are “Yes” and “No”. The default value is “No”.

label_color

The color of the text label associated with each location on the map. Labels are only shown if a column in the data file is identified as containing labels. The default color is black.

label_font

The name of the font family used to display the label. The default font is a sans-serif font, and is dependent on the fonts that are installed on the system. If a font name is specified that does not exist on the system, it will be replaced by the default font. The Map / Change labeling menu option can be used to view and change the current font.

label_position

Whether to display the label above or below the marker symbol. Valid values are “above” and “below”. The default value is “below”.

label_size

The height of the label, in pixels. The default size is 10.

location_color

The name of the color to be used to mark locations that are in the data file. This color may be overridden by specifications in the data file. Colors that may be specified are shown on the Colors page. The default color is black. The location_color specification is used only when a configuration file is read during startup. If a configuration file is loaded using the File / Read config menu item, location markers that are shown on the map will not be changed.

location_marker

The name of the symbol to be used to mark locations in the data file. This symbol may be overridden by specifications in the data file. The default location marker is an open triangle. The names and appearance of the symbols are shown on the Symbols page. Additional symbols can be used if they are specified in the symbols section of a configuration file.

message

Text that will be used as the map title.

projection

The Coordinate Reference System (CRS) identifier for the latitude and longitude values.

multiselect

Whether or not to initially allow multiple selections in the map or table. Valid values are “Yes” and “No”. The default value is “No”.

select_color

The color of the symbol to be used to mark selected locations on the map. The default color is red.

select_symbol

The name of the symbol to be used to mark selected locations on the map. The default symbol is a wedge (inverted triangle).

sheet

The name of the sheet to import from a spreadsheet file.

show_regression_stats

Whether or not to show regression statistics (slope, intercept, sums of squares) when a least-squares linear regression is added to a scatter plot or a line plot. Valid values are “Yes” and “No”. The default value is “No”. This setting can also be changed interactively with the plot configuration dialog.

symbol_column

The name of the column in the data table containing symbol names that can be used for location markers. The use_data_marker setting (and command-line arguments) determine whether these symbols will be used.

use_data_color

If the input data set contains a column of color names, those marker colors will be used by default for location markers. This setting can be used to suppress the use of these custom marker colors, and to use the default marker color instead. Valid values are “Yes” and “No”. The default value is “Yes”.

use_data_marker

If the input data set contains a column of marker names, and that column name is identified as containing marker symbols when the data set is read, those marker symbols will be used by default to mark the locations. This setting can be used to suppress the use of these custom symbols, and to use the default marker symbol instead. Valid values are “Yes” and “No”. The default value is “Yes”.

wrapwidth

The width at which to wrap tick labels on some types of plots (e.g., box plots). The default value is 20. This setting can also be changed interactively with the plot configuration dialog.

x_column

The name of the column in the data table containing longitude values.

y_column

The name of the column in the data table containing latitude values.

Section misc

The settings in this section affect the operation of mapdata. They do not have any direct effect on the appearance of the map or data table.

editor

The name of an external editor to be used when custom SQL is to be run prior to importing a database table. The editor must accept the name of the file to be edited as a command-line argument.

read_config

The name of another mapdata configuration file to be read. The specified file will be read immediately after the configuration file in which this setting appears, unless it has already been read. If the specified file is already in the list of configuration files but has not yet been read, it will not be read a second time.

temp_dbfile

The name of a SQLite database file to be used for storage of a copy of the data set being explored. This may need to be used if memory is limited, but will lead to lower performance.