geofileops.join_by_location

geofileops.join_by_location(input1_path: Union[str, os.PathLike[Any]], input2_path: Union[str, os.PathLike[Any]], output_path: Union[str, os.PathLike[Any]], spatial_relations_query: str = 'intersects is True', discard_nonmatching: bool = True, min_area_intersect: Optional[float] = None, area_inters_column_name: Optional[str] = None, input1_layer: Optional[str] = None, input1_columns: Optional[List[str]] = None, input1_columns_prefix: str = 'l1_', input2_layer: Optional[str] = None, input2_columns: Optional[List[str]] = None, input2_columns_prefix: str = 'l2_', output_layer: Optional[str] = None, gridsize: float = 0.0, where_post: Optional[str] = None, nb_parallel: int = -1, batchsize: int = -1, force: bool = False)

Joins all features in input1 with all features in input2.

The output will contain the geometries of input1. The spatial_relations_query and min_area_intersect parameters will determine which geometries of input1 will be matched with input2.

The spatial_relations_query is a filter string where you can use the following “named spatial predicates”: equals, touches, within, overlaps, crosses, intersects, contains, covers, coveredby.

If you want even more control, you can also use “spatial masks” as defined by the DE-9IM model.

Examples for valid spatial_relations_query values:

• “overlaps is True and contains is False”

• “(T*T***T** is True or 1*T***T** is True) and T*****FF* is False”

Alternative names:

• GeoPandas: sjoin

• ArcGIS: spatial join

Parameters:

• input1_path (PathLike) – the 1st input file

• input2_path (PathLike) – the 2nd input file

• output_path (PathLike) – the file to write the result to

• spatial_relations_query (str, optional) – a query that specifies the spatial relations to match between the 2 layers. Defaults to “intersects is True”.

• discard_nonmatching (bool, optional) – True to only keep rows that match with the spatial_relations_query. False to keep rows all rows in the input1_layer (=left outer join). Defaults to True (=inner join).

• min_area_intersect (float, optional) – minimum area of the intersection to match. Defaults to None.

• area_inters_column_name (str, optional) – column name of the intersect area. If None no area column is added. Defaults to None.

• input1_layer (str, optional) – input layer name. Optional if the file only contains one layer. Defaults to None.

• input1_columns (List[str], optional) – list of columns to retain. If None, all standard columns are retained. In addition to standard columns, it is also possible to specify “fid”, a unique index available in all input files. Note that the “fid” will be aliased even if input1_columns_prefix is “”, eg. to “fid_1”. Defaults to None.

• input1_columns_prefix (str, optional) – prefix to use in the column aliases. Defaults to “l1_”.

• input2_layer (str, optional) – input layer name. Optional if the file only contains one layer. Defaults to None.

• input2_columns (List[str], optional) – columns to select. If None is specified, all columns are selected. As explained for input1_columns, it is also possible to specify “fid”. Defaults to None.

• input2_columns_prefix (str, optional) – prefix to use in the column aliases. Defaults to “l2_”.

• output_layer (str, optional) – output layer name. If None, the output_path stem is used. Defaults to None.

• gridsize (float, optional) – the size of the grid the coordinates of the ouput will be rounded to. Eg. 0.001 to keep 3 decimals. Value 0.0 doesn’t change the precision. Defaults to 0.0.

• where_post (str, optional) – SQL filter to apply after all other processing, including e.g. explodecollections. It should be in sqlite syntax and spatialite reference functions can be used. Defaults to None.

• nb_parallel (int, optional) – the number of parallel processes to use. Defaults to -1: use all available CPUs.

• batchsize (int, optional) – indicative number of rows to process per batch. A smaller batch size, possibly in combination with a smaller nb_parallel, will reduce the memory usage. Defaults to -1: (try to) determine optimal size automatically.

• force (bool, optional) – overwrite existing output file(s). Defaults to False.