BBBikeReader.read_shp_zip

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

Read a shapefile of a geographic region.

Parameters

  • subregion_name (str) – name of a geographic 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_confirmation_required (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 tuple or None

Examples:

>>> import os
>>> from pydriosm.reader import BBBikeReader

>>> bbbike_reader = BBBikeReader()

>>> region_name = 'Birmingham'
>>> dat_dir = "tests"

>>> birmingham_shp = bbbike_reader.read_shp_zip(region_name, data_dir=dat_dir,
...                                             verbose=True)
To download .shp.zip data of the following geographic region(s):
    Birmingham
? [No]|Yes: yes
Downloading "Birmingham.osm.shp.zip" to "tests\" ... Done.
Extracting "tests\Birmingham.osm.shp.zip" ...
to "tests\"
Done.
Parsing files at "tests\Birmingham-shp\shape\" ... Done.

>>> list(birmingham_shp.keys())
['buildings',
 'landuse',
 'natural',
 'places',
 'points',
 'pofw',
 'pois',
 'railways']

>>> # Data of 'railways' layer
>>> birmingham_railways_shp = birmingham_shp['railways']

>>> birmingham_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)

>>> layer_name = 'roads'
>>> feat_name = None

>>> birmingham_roads_shp = bbbike_reader.read_shp_zip(region_name, layer_name,
...                                                   feat_name, data_dir=dat_dir,
...                                                   rm_extracts=True,
...                                                   verbose=True)
Parsing "tests\Birmingham-shp\shape\roads.shp" ... Done.
Deleting the extracts "tests\Birmingham-shp\" ... Done.

>>> list(birmingham_roads_shp.keys())
['roads']

>>> birmingham_roads_shp['roads'].head()
   osm_id  ... shape_type
0      37  ...          3
1      38  ...          3
2      41  ...          3
3      42  ...          3
4      45  ...          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 = bbbike_reader.read_shp_zip(region_name, lyr_names, feat_names,
...                                             dat_dir, rm_extracts=True,
...                                             rm_shp_zip=True, verbose=True)
Extracting the following layer(s):
    'railways'
    'waterways'
from "tests\Birmingham.osm.shp.zip" ...
to "tests\"
Done.
Parsing files at "tests\Birmingham-shp\shape\" ... Done.
Deleting the extracts "tests\Birmingham-shp\" ... Done.
Deleting "tests\Birmingham.osm.shp.zip" ... Done.

>>> 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