Input / Output#

read_block(path, val_col_name, geometry_col_name='geometry', id_col_name=None, centroid_col_name=None, epsg=None, crs=None, **kwargs)[source]

Function reads block data from files supported by geopandas.

Value column name must be provided. If geometry column has different name than ‘geometry’ then it must be provided too. ID column name is optional, if not given then GeoDataFrame index is treated as an id column. Optional parameters are epsg and crs. If any is set then data is reprojected into a specific crs/epsg.` Function returns GeoDataFrame with columns: [id, value, geometry, centroid].

Parameters:

pathstr: Path to the file with appropriate extension such as .shp, .gpkg, .feather, or .parquet.
val_col_namestr: Name of the value column (header title).
geometry_col_namestr, default=’geometry’: Name of the column with polygons.
id_col_name: str or None, default=None, optional: Name of the colum with unique indexes.
centroid_col_name: str or None, default=None: Name of the column with block centroid. Centroids are calculated from MultiPolygon or Polygon later on but their accuracy may be limited. For most applications it does not matter.
epsgstr or None, default=None: If provided then GeoDataFrame projection is set to it. You should choose if you provide EPSG or CRS.
crsstr or None, default=None: If provided then GeoDataFrame projection is set to it. You should choose if you provide CRS or EPSG.
**kwargsAny: Additional kwargs parameters passed to the geopandas.read_file(), geopandas.read_feather() or geopandas.read_parquet() functions.

Returns:

gpdGeoDataFrame: Returned output has columns: ['id', 'geometry', 'value', 'centroid'].

Raises:

TypeError: EPSG and CRS are provided both (should be only one).
TypeError: Provided column name does not exist in a dataset.

Examples

>>> bblock = 'path_to_the_shapefile.shp'
>>> bdf = read_block(bblock, val_col_name='rate', id_col_name='id')
>>> print(bdf.columns)
Index(['id', 'geometry', 'rate', 'centroid'], dtype='object')

read_csv(path, val_col_name, lat_col_name, lon_col_name, delim=',')[source]

Function reads data from a csv file.

Provided data should include: latitude, longitude, value.

Parameters:

pathstr: Path to the file.
val_col_namestr: Name of the value column (header title).
lat_col_namestr: Name of the latitude column (header title).
lon_col_namestr: Name of the longitude column (header title).
delimstr, default=’,’: Delimiter that separates columns.

Returns:

data_arrnumpy array

Examples

>>> path_to_the_data = 'path_to_the_data.csv'
>>> data = read_csv(path_to_the_data, val_col_name='value', lat_col_name='y', lon_col_name='x')
>>> print(data[:2, :])
[
    [15.11524 52.76515 91.275597]
    [15.11524 52.74279 96.548294]
]

read_txt(path, delim=',', skip_header=True)[source]

Function reads data from a text file.

Provided data format should include: longitude (x), latitude (y), value. Function converts data into numpy array.

Parameters:

pathstr: Path to the file.
delimstr, default=’,’: Delimiter that separates columns.
skip_headerbool, default=True: Skips the first row of a file if set to True.

Returns:

data_arrnumpy array

Examples

>>> path_to_the_data = 'path_to_the_data.txt'
>>> data = read_txt(path_to_the_data, skip_header=False)
>>> print(data[:2, :])
[
    [15.11524 52.76515 91.275597]
    [15.11524 52.74279 96.548294]
]