geofileops.join_nearest#

geofileops.join_nearest(input1_path: str | os.PathLike[Any], input2_path: str | os.PathLike[Any], output_path: str | os.PathLike[Any], nb_nearest: int, distance: float | None = None, expand: bool | None = None, input1_layer: str | None = None, input1_columns: list[str] | None = None, input1_columns_prefix: str = 'l1_', input2_layer: str | None = None, input2_columns: list[str] | None = None, input2_columns_prefix: str = 'l2_', output_layer: str | None = None, nb_parallel: int | None = None, batchsize: int = -1, force: bool = False) → None#

Joins features of input1 with the nb_nearest ones in input2.

In addition to the columns requested via the input*_columns parameters, the following columns will be in the output file as well:

  • pos (int): relative rank (sorted by distance): the closest item will be #1, the second closest item will be #2 and so on.

  • distance (float): if the dataset is in a planar (= projected) crs, distance will be in the unit defined by the projection (meters, feet, chains etc.). For a geographic dataset (longitude and latitude degrees), distance will be in meters, with the most precise geodetic formulas being applied.

  • distance_crs (float): if the dataset is in a planar (= projected) crs, distance_crs will be in the unit defined by the projection (meters, feet, chains etc.). For a geographic dataset (longitude and latitude degrees), distance_crs will be in angles. Only available with spatialite >= 5.1.

Note: if spatialite version >= 5.1 is used, parameters distance and expand are mandatory.

Parameters:

  • input1_path (PathLike) – the input file to join to nb_nearest features.

  • input2_path (PathLike) – the file where nb_nearest features are looked for.

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

  • nb_nearest (int) – the number of nearest features from input 2 to join to input1.

  • distance (float) – maximum distance to search for the nearest items. If expand is True, this is the initial search distance, which will be gradually expanded (doubled) till nb_nearest are found. For optimal performance, it is important to choose the typical value that will be needed to find nb_nearest items. If distance is too large, performance can be bad. Parameter is only relevant if spatialite version >= 5.1 is used.

  • expand (bool) – True to keep searching till nb_nearest items are found. If False, only items found within distance are returned (False is only supported if spatialite version >= 5.1 is used).

  • input1_layer (str, optional) – 1st input layer name. If None, input1_path should contain only 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) – 2nd input layer name. If None, input2_path should contain only 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.

  • nb_parallel (int | None, optional) – the number of parallel workers to use. If None, the preference set in the nb_parallel configuration option is used, which defaults to the number of CPU cores available. For more information, see options.set_nb_parallel(). Defaults to None.

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

See also