edisgo.tools.geo
================

.. py:module:: edisgo.tools.geo


Functions
---------

.. autoapisummary::

   edisgo.tools.geo.proj2equidistant
   edisgo.tools.geo.proj2equidistant_reverse
   edisgo.tools.geo.proj_by_srids
   edisgo.tools.geo.calc_geo_lines_in_buffer
   edisgo.tools.geo.calc_geo_dist_vincenty
   edisgo.tools.geo.find_nearest_bus
   edisgo.tools.geo.find_nearest_conn_objects
   edisgo.tools.geo.mv_grid_gdf


Module Contents
---------------

.. py:function:: proj2equidistant(srid)

   Transforms to equidistant projection (epsg:3035).

   :param srid: Spatial reference identifier of geometry to transform.
   :type srid: int

   :rtype: :py:func:`functools.partial`


.. py:function:: proj2equidistant_reverse(srid)

   Transforms back from equidistant projection to given projection.

   :param srid: Spatial reference identifier of geometry to transform.
   :type srid: int

   :rtype: :py:func:`functools.partial`


.. py:function:: proj_by_srids(srid1, srid2)

   Transforms from specified projection to other specified projection.

   :param srid1: Spatial reference identifier of geometry to transform.
   :type srid1: int
   :param srid2: Spatial reference identifier of destination CRS.
   :type srid2: int

   :rtype: :py:func:`functools.partial`

   .. rubric:: Notes

   Projections often used are conformal projection (epsg:4326), equidistant
   projection (epsg:3035) and spherical mercator projection (epsg:3857).


.. py:function:: calc_geo_lines_in_buffer(grid_topology, bus, grid, buffer_radius=2000, buffer_radius_inc=1000)

   Determines lines that are at least partly within buffer around given bus.

   If there are no lines, the buffer specified in `buffer_radius` is
   successively extended by `buffer_radius_inc` until lines are found.

   :param grid_topology:
   :type grid_topology: :class:`~.network.topology.Topology`
   :param bus: Data of origin bus the buffer is created around.
               Series has same rows as columns of
               :attr:`~.network.topology.Topology.buses_df`.
   :type bus: :pandas:`pandas.Series<Series>`
   :param grid: Grid whose lines are searched.
   :type grid: :class:`~.network.grids.Grid`
   :param buffer_radius: Radius in m used to find connection targets. Default: 2000.
   :type buffer_radius: float, optional
   :param buffer_radius_inc: Radius in m which is incrementally added to `buffer_radius` as long as
                             no target is found. Default: 1000.
   :type buffer_radius_inc: float, optional

   :returns: List of lines in buffer (meaning close to the bus) sorted by the
             lines' representatives.
   :rtype: list(str)


.. py:function:: calc_geo_dist_vincenty(grid_topology, bus_source, bus_target, branch_detour_factor=1.3)

   Calculates the geodesic distance between two buses in km.

   The detour factor in config_grid is incorporated in the geodesic distance.

   :param grid_topology:
   :type grid_topology: :class:`~.network.topology.Topology`
   :param bus_source: Name of source bus as in index of
                      :attr:`~.network.topology.Topology.buses_df`.
   :type bus_source: str
   :param bus_target: Name of target bus as in index of
                      :attr:`~.network.topology.Topology.buses_df`.
   :type bus_target: str
   :param branch_detour_factor: Detour factor to consider that two buses can usually not be
                                connected directly. Default: 1.3.
   :type branch_detour_factor: float

   :returns: Distance in km.
   :rtype: float


.. py:function:: find_nearest_bus(point, bus_target)

   Finds the nearest bus in `bus_target` to a given point.

   :param point: Point to find the nearest bus for.
   :type point: :shapely:`shapely.Point<Point>`
   :param bus_target: Dataframe with candidate buses and their positions given in 'x' and 'y'
                      columns. The dataframe has the same format as
                      :attr:`~.network.topology.Topology.buses_df`.
   :type bus_target: :pandas:`pandas.DataFrame<DataFrame>`

   :returns: Tuple that contains the name of the nearest bus and its distance in km.
   :rtype: tuple(str, float)


.. py:function:: find_nearest_conn_objects(grid_topology, bus, lines, conn_diff_tolerance=0.0001)

   Searches all lines for the nearest possible connection object per line.

   It picks out 1 object out of 3 possible objects: 2 line-adjacent buses
   and 1 potentially created branch tee on the line (using perpendicular
   projection). The resulting stack (list) is sorted ascending by distance
   from bus.

   :param grid_topology:
   :type grid_topology: :class:`~.network.topology.Topology`
   :param bus: Data of bus to connect.
               Series has same rows as columns of
               :attr:`~.network.topology.Topology.buses_df`.
   :type bus: :pandas:`pandas.Series<Series>`
   :param lines: List of line representatives from index of
                 :attr:`~.network.topology.Topology.lines_df`.
   :type lines: list(str)
   :param conn_diff_tolerance: Threshold which is used to determine if 2 objects are at the same
                               position. Default: 0.0001.
   :type conn_diff_tolerance: float, optional

   :returns: List of connection objects. Each object is represented by dict with
             representative, shapely object and distance to node.
   :rtype: list(dict)


.. py:function:: mv_grid_gdf(edisgo_obj)