BBBikeReader.read_shp

BBBikeReader.read_shp(subregion_name, layer_names=None, feature_names=None, data_dir=None, update=False, download=False, 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 | list | None) – name of a .shp layer, e.g. ‘railways’, or names of multiple layers; if None (default), all available layers

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

• data_dir (str | 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 | 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 | collections.OrderedDict | tuple | 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(
...     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(
...     subregion_name=subrgn_name, data_dir=dat_dir, download=True, verbose=True)
Downloading "Birmingham.osm.shp.zip" 100%|██████████| 79.0M/79.0M | 28.5MB/s ...
  Saving "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/" ......
>>> type(bham_shp)
dict
>>> 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.shape
(3994, 5)
>>> 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(
...     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)
dict
>>> list(bham_roads_shp.keys())
['roads']
>>> bham_roads_shp[lyr_name].shape
(170370, 9)
>>> bham_roads_shp[lyr_name].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 = bbr.read_shp(
...     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 shapefile(s) at "./tests/osm_data/birmingham/Birmingham-shp/shape/" ......
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)
dict
>>> 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
9   canal  Birmingham and Fazeley Canal
10  canal      Icknield Port Loop Canal
11  canal     Oozells Street Loop Canal
12  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.