BBBikeReader.read_shp_zip

BBBikeReader.read_shp_zip(subregion_name, layer_names=None, feature_names=None, data_dir=None, update=False, download=True, pickle_it=False, ret_pickle_path=False, rm_extracts=False, rm_shp_zip=False, verbose=False, **kwargs)

Read a shapefile of a geographic (sub)region.

Parameters

  • subregion_name (str) – name of a geographic (sub)region (case-insensitive) that is available on BBBike free download server

  • layer_names (str or list or None) – name of a .shp layer, e.g. ‘railways’, or names of multiple layers; if None (default), all available layers

  • feature_names (str or list or None) – name of a feature, e.g. ‘rail’, or names of multiple features; if None (default), all available features

  • data_dir (str or None) – directory where the .shp.zip data file is located/saved; if None, the default directory

  • update (bool) – whether to check to update pickle backup (if available), defaults to False

  • download (bool) – whether to ask for confirmation before starting to download a file, defaults to True

  • pickle_it (bool) – whether to save the .shp data as a pickle file, defaults to False

  • ret_pickle_path (bool) – (when pickle_it=True) whether to return a path to the saved pickle file

  • rm_extracts (bool) – whether to delete extracted files from the .shp.zip file, defaults to False

  • rm_shp_zip (bool) – whether to delete the downloaded .shp.zip file, defaults to False

  • verbose (bool or int) – whether to print relevant information in console as the function runs, defaults to False

Returns

dictionary of the shapefile data, with keys and values being layer names and tabular data (in the format of geopandas.GeoDataFrame), respectively; when pickle_it=True, return a tuple of the dictionary and a path to the pickle file

Return type

dict or collections.OrderedDict or tuple or None

Examples:

>>> from pydriosm.reader import BBBikeReader
>>> from pyhelpers.dirs import delete_dir
>>> import os

>>> bbr = BBBikeReader()

>>> subrgn_name = 'Birmingham'
>>> dat_dir = "tests\osm_data"

>>> bham_shp = bbr.read_shp_zip(
...     subregion_name=subrgn_name, data_dir=dat_dir, download=False, verbose=True)
The .shp.zip file for "Birmingham" is not found.

>>> # Set `download=True`
>>> bham_shp = bbr.read_shp_zip(
...     subregion_name=subrgn_name, data_dir=dat_dir, download=True, verbose=True)
Downloading "Birmingham.osm.shp.zip"
    to "tests\osm_data\birmingham\" ... Done.
Extracting "tests\osm_data\birmingham\Birmingham.osm.shp.zip"
    to "tests\osm_data\birmingham\" ... Done.
Reading the shapefile(s) at
    "tests\osm_data\birmingham\Birmingham-shp\shape\" ... Done.
>>> type(bham_shp)
collections.OrderedDict
>>> list(bham_shp.keys())
['buildings',
 'landuse',
 'natural',
 'places',
 'points',
 'railways',
 'roads',
 'waterways']

>>> # Data of 'railways' layer
>>> bham_railways_shp = bham_shp['railways']
>>> bham_railways_shp.head()
    osm_id  ... shape_type
0      740  ...          3
1     2148  ...          3
2  2950000  ...          3
3  3491845  ...          3
4  3981454  ...          3
[5 rows x 5 columns]

>>> # Read data of 'road' layer only from the original .shp.zip file
>>> # (and delete all extracts)
>>> lyr_name = 'roads'
>>> bham_roads_shp = bbr.read_shp_zip(
...     subregion_name=subrgn_name, layer_names=lyr_name, data_dir=dat_dir,
...     rm_extracts=True, verbose=True)
Reading "tests\osm_data\birmingham\Birmingham-shp\shape\roads.shp" ... Done.
Deleting the extracts "tests\osm_data\birmingham\Birmingham-shp\"  ... Done.
>>> type(bham_roads_shp)
collections.OrderedDict
>>> list(bham_roads_shp.keys())
['roads']
>>> bham_roads_shp[lyr_name].head()
   osm_id  ... shape_type
0      37  ...          3
1      38  ...          3
2      41  ...          3
3      45  ...          3
4      46  ...          3
[5 rows x 9 columns]

>>> # Read data of multiple layers and features from the original .shp.zip file
>>> # (and delete all extracts)
>>> lyr_names = ['railways', 'waterways']
>>> feat_names = ['rail', 'canal']
>>> bham_rw_rc_shp = bbr.read_shp_zip(
...     subregion_name=subrgn_name, layer_names=lyr_names, feature_names=feat_names,
...     data_dir=dat_dir, rm_extracts=True, rm_shp_zip=True, verbose=True)
Extracting the following layer(s):
    'railways'
    'waterways'
    from "tests\osm_data\birmingham\Birmingham.osm.shp.zip"
      to "tests\osm_data\birmingham\" ... Done.
Reading the data at "tests\osm_data\birmingham\Birmingham-shp\shape\" ... Done.
Deleting the extracts "tests\osm_data\birmingham\Birmingham-shp\"  ... Done.
Deleting "tests\osm_data\birmingham\Birmingham.osm.shp.zip" ... Done.
>>> type(bham_rw_rc_shp)
collections.OrderedDict
>>> list(bham_rw_rc_shp.keys())
['railways', 'waterways']

>>> # Data of the 'railways' layer
>>> bham_rw_rc_shp_railways = bham_rw_rc_shp['railways']
>>> bham_rw_rc_shp_railways[['type', 'name']].head()
   type                                             name
0  rail                                  Cross-City Line
1  rail                                  Cross-City Line
2  rail  Derby to Birmingham (Proof House Junction) Line
3  rail                  Birmingham to Peterborough Line
4  rail          Water Orton to Park Lane Junction Curve

>>> # Data of the 'waterways' layer
>>> bham_rw_rc_shp_waterways = bham_rw_rc_shp['waterways']
>>> bham_rw_rc_shp_waterways[['type', 'name']].head()
     type                                              name
2   canal                      Birmingham and Fazeley Canal
8   canal                      Birmingham and Fazeley Canal
9   canal  Birmingham Old Line Canal Navigations - Rotton P
10  canal                               Oozells Street Loop
11  canal                      Worcester & Birmingham Canal

>>> # Delete the example data and the test data directory
>>> delete_dir(dat_dir, verbose=True)
To delete the directory "tests\osm_data\" (Not empty)
? [No]|Yes: yes
Deleting "tests\osm_data\" ... Done.