Installation

The below sections describe how to install both the pycoast python library and additional data files that maybe required to use some features of pycoast.

If you have any trouble with the installation of the package or the data files described below, please file a bug report on GitHub:

https://github.com/pytroll/pycoast/

Package installation

Pycoast can be installed in an existing Python environment via pip or in a conda environment via conda using the conda-forge channel. To use pip:

pip install pycoast

Alternatively, with conda:

conda install -c conda-forge pycoast

Installation of shape files

To use the features of pycoast that draw country or other political borders, rivers, and lakes, shapefiles from the SOEST GSHHG website must be installed. Download the zipped GSHHS and WDBII shapefiles. At the time of writing the current zip file can be found at:

https://www.soest.hawaii.edu/pwessel/gshhg/gshhg-shp-2.3.7.zip

Unzip the files to a data directory (hereafter DB_DATA_ROOT). The absolute path/name of this directory is called db_root_path in the code examples used elsewhere in the documentation.

The structure of DB_DATA_ROOT should now be:

.
├── GSHHS_shp
│   ├── c
│   ├── f
│   ├── h
│   ├── i
│   └── l
└── WDBII_shp
    ├── c
    ├── f
    ├── h
    ├── i
    └── l

Where each dir on the lowest level contains Shapefiles like GSHHS_shp/c/GSHHS_c_L1.shp, WDBII_shp/WDBII_border_c_L1.shp

Installation of city names

To use the features of Pycoast that depend on city locations or names, one or more files from GeoNames must be downloaded and made available in the same DB_DATA_ROOT directory created in the above GSHHG shapefile download. GeoNames releases multiple lists of city information available from their file archive:

https://download.geonames.org/export/dump/

There are files that contain city information for cities with a population larger than 500, 1000, 5000, and 15000. Only one of these files needs to be downloaded depending on your needs. At the time of writing the URLs for these files are:

Once downloaded, extract the single cities .txt file inside and move it to a new DB_DATA_ROOT/CITIES/ directory. Currently, Pycoast requires that the file be named “cities.txt”. The structure of DB_DATA_ROOT should now be:

.
├── GSHHS_shp
│   ├── c
│   ├── f
│   ├── h
│   ├── i
│   └── l
├── WDBII_shp
│   ├── c
│   ├── f
│   ├── h
│   ├── i
│   └── l
└─── CITIES
    └── cities.txt

The PyCoast API documentation explains in detail how to use this city information via the add_cities() method.