API

The ProMis engine for solving constrained navigation tasks using hybrid probabilistic logic.

class promis.promis.ProMis(star_map: StaRMap)

Bases: object

The ProMis engine to create Probabilistic Mission Landscapes.

adaptive_solve(initial_evaluation_points, candidate_sampler, logic, number_of_iterations: int, number_of_improvement_points: int, n_jobs: int | None = None, batch_size: int = 10, scaler: float = 10.0, interpolation_method: str = 'linear', acquisition_method: str = 'entropy')

Automatically add support points at locations where the uncertainty is high.

Parameters:

• number_of_random_maps – How often to sample from map data in order to compute statistics of spatial relations

• number_of_improvement_points – How many points to add to improve the map

• relations – The spatial relations to compute

• location_types – The location types to compute

• interpolation_method – The interpolation method used to get from StaR Map known values to evluation points

• acquisition_method – The method to inform the adaptive solving process, one of {entropy, gaussian_process}

solve(evaluation_points: CartesianCollection, logic: str, n_jobs: int | None = None, batch_size: int = 10, show_progress: bool = False, print_first: bool = False, interpolation_method: str = 'linear') → None

Solve the given ProMis problem.

It searches the provided logic for the used relations and location types and only encodes the necessary information for the inference. It can further parallelize the inference process over multiple workers and batch into fewer solver invocations to speed up computations.

Parameters:

• support – The points to compute exactly, with the output being interpolated to the same target as the employed StaRMap

• logic – The constraints of the landscape(X) predicate, including its definition

• n_jobs – How many workers to use in parallel

• batch_size – How many pixels to infer at once

• show_progress – Whether to show a progress bar

• print_first – Whether to print the first program to stdout

• interpolation_method – The interpolation method used to get from StaR Map known values to evluation points

This module contains a class for handling probabilistic, semantic and geospatial data.

class promis.star_map.StaRMap(uam: CartesianMap)

Bases: object

A Statistical Relational Map.

This map holds all information about spatial relations between an agent’s state space and features on a map. It can be used to compute parameters for these relations on a set of support points, and provides an interface to query these parameters for arbitrary locations.

Parameters:

uam – The uncertainty annotated map in Cartesian space.

adaptive_sample(candidate_sampler: Callable[[int], ndarray[tuple[int, ...], dtype[_ScalarType_co]]], number_of_random_maps: int, number_of_iterations: int, number_of_improvement_points: int, what: dict[str, Iterable[str | None]] | None = None, scaler: float = 10.0, value_index: int = 0, acquisition_method: str = 'entropy')

Automatically add support points at locations where the uncertainty is high.

Parameters:

• candidate_sampler – The sampler that provides a candidate Collection that may be used for computing relation parameters

• number_of_random_maps – How often to sample from map data in order to compute statistics of spatial relations

• number_of_iterations – How many iterations of improvements to run

• number_of_improvement_points – How many points to add to improve the map at each iteration.

• what – The spatial relations to compute, as a mapping of relation names to location types

• scaler – How much to weigh the employed scoring method over the distance score

• value_index – Which value column of the relation’s parameters to use for improvement

• acquisition_method – Which improvement method to use, one of {entropy, gaussian_process}

get(relation: str, location_type: str) → Relation

Get the computed data for a relation to a location type.

Parameters:

• relation – The relation to return.

• location_type – The location type to relate to.

Returns:

A deepcopy of the relation object for the given relation and location type.

get_all(logic: str | None = None) → dict[str, dict[str, Relation]]

Get all or a subset of relations for each location type.

If a logic program is provided, only the relations mentioned in it are returned. Otherwise, all computed relations are returned.

Parameters:

logic – An optional logic program to filter the relations.

Returns:

A nested dictionary of all requested relations, mapping relation type to location type to the Relation object.

initialize(evaluation_points: CartesianCollection, number_of_random_maps: int, logic: str)

Setup the StaRMap for a given set of support points, number of samples and logic.

Parameters:

• evaluation_points – The points to initialize the StaR Map on.

• number_of_random_maps – The number of samples to be used per support point.

• logic – The set of constraints deciding which relations are computed.

static load(path: str) → StaRMap

Load a StaRMap from a file.

Parameters:

path – The path to the file.

Returns:

The loaded StaRMap object.

property location_types: set[str]

Get all unique location types present in the map.

property relation_and_location_types: dict[str, set[str]]

Get all relation and location type combinations in the map.

property relation_arities: dict[str, int]

Get the arity for each relation type.

static relation_name_to_class(relation: str) → Relation

Get the class for a given relation name.

Parameters:

relation – The name of the relation.

Returns:

The class corresponding to the relation name.

Raises:

NotImplementedError – If the relation name is unknown.

property relation_types: set[str]

Get the names of all relation types in the map.

sample(evaluation_points: CartesianCollection, number_of_random_maps: int, what: dict[str, Iterable[str | None]] | None = None)

Compute and store spatial relation parameters.

For a given set of evaluation points, this method computes the parameters of spatial relations by sampling the underlying uncertainty-annotated map.

Parameters:

• evaluation_points – The collection of points for which the spatial relations will be computed.

• number_of_random_maps – How often to sample from map data in order to compute statistics of spatial relations.

• what – The spatial relations to compute, as a mapping of relation names to location types. If None, all relations with already present location types are computed.

save(path: str) → None

Save the StaRMap to a file.

Parameters:

path – The path to the file.

Geo

The ProMis geo package represents spatial data in Cartesian and polar coordinates.

class promis.geo.CartesianCollection(origin: PolarLocation, number_of_values: int = 1)

Bases: Collection

property dimensions: tuple[float, float]

Get the dimensions of this Collection in meters.

Returns:

The dimensions of this Collection in meters as (width, height).

get_interpolator(interpolation_method: str = 'linear') → Any

Get an interpolator for the data.

Parameters:

interpolation_method – The interpolation method to use, one of {linear, nearest, hybrid, gaussian_process, clough-tocher}.

Returns:

A callable interpolator function.

into(other: Collection, interpolation_method: str = 'linear', in_place: bool = True) → Collection

Interpolates the values of this collection onto the coordinates of another collection.

This method takes the spatial data from the current collection and uses an interpolation strategy to estimate the values at the coordinate locations of the other collection. The other collection’s values are then updated with these interpolated values.

Parameters:

• other – The target collection whose coordinates will be used for interpolation and whose values will be updated.

• interpolation_method – The interpolation method to use. Supported methods are “linear”, “nearest”, “hybrid”, “gaussian_process”, and “clough-tocher”.

• in_place – If True, the other collection is modified directly. If False, a deep copy of other is created and modified instead.

Returns:

The modified collection (either other itself or a copy) with interpolated values.

classmethod make_latin_hypercube(origin: PolarLocation, width: float, height: float, number_of_samples: int, number_of_values: int = 1, include_corners: bool = False) → CartesianCollection

Creates a collection by sampling points from a Latin Hypercube design.

prune(threshold: float)

Reduces the number of points in the collection by clustering nearby points.

This method uses Agglomerative Clustering to group points. For each cluster, only one representative point (the first one encountered in the cluster) is kept. This is useful for simplifying dense point clouds.

Parameters:

threshold – The maximum distance between points to be considered in the same cluster.

to_cartesian_locations() → list[CartesianLocation]

Converts the collection’s coordinates to a list of CartesianLocation objects.

Returns:

A list of CartesianLocation objects.

to_polar() → PolarCollection

Converts this CartesianCollection to a PolarCollection.

The coordinates are projected from the local Cartesian plane back to polar (WGS84) coordinates using the collection’s origin.

Returns:

A new PolarCollection with the data from this collection.

class promis.geo.CartesianLocation(east: float, north: float, location_type: str | None = None, name: str | None = None, identifier: int | None = None, covariance: ndarray | None = None, origin: PolarLocation | None = None)

Bases: Location

A point in the cartesian plane based on local coordinates with an optional global reference.

Parameters:

• east – The easting of the location in meters

• north – The northing of the location in meters

• up – The altitude of the location in meters

• origin – A reference that can be used to project this cartesian representation (back) into a polar one

• location_type – The type of this polygon

• name – An optional name of this polygon

• identifier – An optional unique identifier for this object, in \([0, 2**63)\)

• uncertainty – An optional value representing the variance of this location’s east and north coordinates respectively

distance(other: Any) → float

property east: float

property north: float

send_to_gui(url='http://localhost:8000/add_geojson', timeout=1)

Send an HTTP POST-request to the GUI backend.

Parameters:

• url – url of the backend

• timeout – request timeout in second

Raises:

• HTTPError – When the HTTP request returned an unsuccessful status code

• ConnectionError – If the request fails due to connection issues

to_polar(origin: PolarLocation | None = None) → PolarLocation

Computes the polar representation of this point.

Parameters:

origin – The global reference to be used for back-projection, must be set if and only if origin is None

Returns:

The global, polar representation of this point

class promis.geo.CartesianMap(origin: PolarLocation, features: list[CartesianLocation | CartesianMap | CartesianPolygon | CartesianPolyLine] | None = None)

Bases: Map

A map containing geospatial objects based on local coordinates with a global reference point.

Parameters:

• origin – The origin point of this map

• features – A list of features that should be contained by this map

to_polar() → PolarMap

Projects this map to a polar representation according to the map’s global reference.

Returns:

The cartesian representation of this map with the given reference point being the same

class promis.geo.CartesianPolyLine(locations: list[CartesianLocation], location_type: str | None = None, name: str | None = None, identifier: int | None = None, covariance: ndarray | None = None, origin: PolarLocation | None = None)

Bases: PolyLine

A Cartesian polyline (line string) in local coordinates.

Parameters:

• locations – The list of two or more locations that this shape consists of; see locations

• location_type – The type of this polyline

• name – The name of this polyline

• identifier – The polyline’s optional unique identifier, in \([0, 2**63)\)

• origin – A reference that can be used to project this cartesian representation (back) into a polar one

• covariance – An optional value representing the variance of this polyline’s east and north coordinates respectively

distance(other: Any) → float

classmethod from_numpy(data: ndarray, *args, **kwargs) → CartesianPolyLine

Create a Cartesian polyline from a numpy representation.

Parameters:

• data – An array with shape (number of locations, 2), where each location is represented by a pair of (east, north), each in degrees.

• *args – Positional arguments to be passed to CartesianPolyLine

• **kwargs – Keyword arguments to be passed to CartesianPolyLine

Returns:

The polar polyline created from the given coordinates an other parameters

Raises:

AssertionError – If the shape of array is invalid

See also

to_numpy()

send_to_gui(url='http://localhost:8000/add_geojson', timeout=1)

Send an HTTP POST-request to the GUI backend.

Parameters:

• url – url of the backend

• timeout – request timeout in second

Raises:

• HTTPError – When the HTTP request returned an unsuccessful status code

• ConnectionError – If the request fails due to connection issues

to_polar(origin: PolarLocation | None = None) → PolarPolyLine

Computes the polar representation of this polyline.

Parameters:

origin – The global reference to be used for back-projection, must be set if and only if origin is None

Returns:

The global, polar representation of this polyline

class promis.geo.CartesianPolygon(locations: list[CartesianLocation], holes: list[list[CartesianLocation]] | None = None, location_type: str | None = None, name: str | None = None, identifier: int | None = None, covariance: ndarray | None = None, origin: PolarLocation | None = None)

Bases: Polygon

A cartesian polygon based on local coordinates with an optional global reference.

Examples

Lets first create the perimeter of the polygon as a list of CartesianLocation objects.

>>> locations = [CartesianLocation(-1.0, 1.0), CartesianLocation(1.0, 1.0),
...  CartesianLocation(1.0, -1.0), CartesianLocation(-1.0, -1.0)]

Now, we can build a polygon from these locations like so:

>>> polygon = CartesianPolygon(locations)

Given another list of locations, e.g.,

>>> holes = [[CartesianLocation(-0.5, 0.5), CartesianLocation(0.5, 0.5),
...  CartesianLocation(0.5, -0.5), CartesianLocation(-0.5, -0.5)]]

we can also build a polygon that contains holes:

>>> polygon = CartesianPolygon(locations, holes)

Given a covariance of this polygons translation, random samples can be drawn.

>>> from numpy import eye
>>> polygon = CartesianPolygon(locations, covariance=eye(2))
>>> random_samples = polygon.sample(10)

CartesianPolygons can also be created from numpy data.

>>> from numpy import array
>>> locations = array([[-1.0, 1.0, 1.0, -1.0], [1.0, 1.0, -1.0, -1.0]])
>>> polygon = CartesianPolygon.from_numpy(locations)

Finally, a CartesianPolygon can be turned into a PolarPolygon given a reference origin in polar coordinates.

>>> origin = PolarLocation(49.873163174, 8.653830718)
>>> polar_polygon = polygon.to_polar(origin)

Parameters:

• locations – The list of locations that this shape consists of; see locations

• holes – The points that make up holes in this polygon

• location_type – The type of this polygon

• name – The name of this polygon

• identifier – The polygon’s optional unique identifier, in \([0, 2**63)\)

• covariance – An optional matrix representing the variance of this polygon’s latitude and longitude respectively

• origin – A reference that can be used to project this cartesian representation (back) into a polar one

distance(other: Any) → float

classmethod from_numpy(data: ndarray, *args, **kwargs) → CartesianPolygon

Create a polygon from a numpy representation.

Parameters:

• data – An array with shape (2, number_of_locations)

• args – Positional arguments to be passed to the new polygon

• kwargs – Keyword arguments to be passed to the new polygon

Returns:

The polygon created from the given coordinates and other parameters

Raises:

AssertionError – If the shape or content of data is invalid

See also

to_numpy()

classmethod make_centered_box(width: float, height: float, offset: CartesianLocation = CartesianLocation(east=0.0, north=0.0, identifier=2382130182820868996), **kwargs) → CartesianPolygon

Generates a box centered around a given offset.

Parameters:

• width – The width of the map in meters

• height – The height of the map in meters

• kwargs – Additional keyword arguments to pass to the polygon, such as an origin

Returns:

The box as a polygon

plot(axis, **kwargs) → None

Plots this polygon using Matplotlib.

Parameters:

• axis – The axis object to use for plotting

• kwargs – Keyword arguments to pass to Matplotlib

send_to_gui(url='http://localhost:8000/add_geojson', timeout=1)

Send an HTTP POST-request to the GUI backend.

Parameters:

• url – url of the backend

• timeout – request timeout in second

Raises:

• HTTPError – When the HTTP request returned an unsuccessful status code

• ConnectionError – If the request fails due to connection issues

to_polar(origin: PolarLocation | None = None) → PolarPolygon

Computes the polar representation of this shape.

Parameters:

origin – The global reference to be used for back-projection, must be set if and only if origin is None

Returns:

The global, polar representation of this geometry

class promis.geo.CartesianRasterBand(origin: PolarLocation, resolution: tuple[int, int], width: float, height: float, number_of_values: int = 1)

Bases: RasterBand, CartesianCollection

A raster-band of Cartesian referenced data.

Parameters:

• origin – The polar coordinates of this raster-band’s center

• resolution – The number of horizontal and vertical pixels

• width – The width the raster band stretches over in meters

• height – The height the raster band stretches over in meters

• number_of_values – How many values are stored per location

class promis.geo.Collection(columns: list[str], origin: PolarLocation, number_of_values: int = 1)

Bases: ABC

An abstract base class for a collection of spatially referenced data points.

This class provides a common interface for managing data points that have associated spatial coordinates and values. It uses a pandas DataFrame for internal storage. Subclasses implement specific coordinate systems, such as Cartesian or Polar.

Parameters:

• columns – The names of the columns for the internal DataFrame. The first two columns are expected to be coordinates, followed by value columns.

• origin – The polar coordinates of this collection’s reference frame’s center.

• number_of_values – The number of value columns to associate with each location.

append(coordinates: ndarray[tuple[int, ...], dtype[Any]] | list[PolarLocation | CartesianLocation], values: ndarray[tuple[int, ...], dtype[Any]])

Append location and associated value vectors to collection.

Parameters:

• coordinates – A list of locations to append or matrix of coordinates.

• values – The associated values as 2D matrix, each row belongs to a single location.

append_with_default(coordinates: ndarray[tuple[int, ...], dtype[Any]] | list[PolarLocation | CartesianLocation], value: ndarray[tuple[int, ...], dtype[Any]])

Append location with a default value.

Parameters:

• coordinates – A list of locations or a matrix of coordinates to append.

• value – The default value to assign to all new locations.

clear()

Empties out the kept data.

coordinates() → ndarray[tuple[int, ...], dtype[Any]]

Unpack the location coordinates as numpy array.

Returns:

The values of this Collection as numpy array.

abstract property dimensions: tuple[float, float]

Get the dimensions of this Collection in meters.

Returns:

The dimensions of this Collection in meters as (width, height).

extent() → tuple[float, float, float, float]

Get the extent of this collection, i.e., the min and max coordinates.

Returns:

The minimum and maximum coordinates in order west, east, south, north.

get_basemap(zoom=16)

Obtain the OSM basemap image of the collection’s area.

Parameters:

zoom – The zoom level requested from OSM.

Returns:

The basemap image.

get_distance_to(other: Collection) → ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Computes the minimum distance from each point in another collection to this collection.

For each point in the other collection, this method finds the distance to the closest point in the current (self) collection.

Parameters:

other – The other collection.

Returns:

A numpy array where the i-th element is the minimum distance from the i-th point in other to any point in this collection.

get_entropy(number_of_neighbours: int = 4, number_of_bins: int = 10, value_index: int = 0) → ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Compute the local entropy in the collection.

Parameters:

• number_of_neighbours – The number of neighbours of a point to take into account.

• number_of_bins – The number of bins to be used for the histogram.

• value_index – Decides which value of the collection the entropy is computed from.

Returns:

The local entropy for each point.

get_nearest_coordinate(point: ndarray[tuple[int, ...], dtype[_ScalarType_co]]) → ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Get the closest coordinate in this collection relative to a given point.

Parameters:

point – The point to find the nearest coordinate to.

Returns:

The coordinate that is closest to the given point.

improve(candidate_sampler: Callable, value_function: Callable, number_of_iterations: int, number_of_improvement_points: int, scaler: float, value_index: int = 0, acquisition_method: str = 'entropy') → None

Improves the collection by adding new, informative points.

This method uses an active learning approach to iteratively add points to the collection. At each iteration, it samples candidate points, scores them based on an acquisition function, and adds the highest-scoring points to the collection.

Parameters:

• candidate_sampler – A function that, when called, returns a Collection of candidate points.

• value_function – A function that computes the value(s) for a given set of new point coordinates.

• number_of_iterations – The number of improvement iterations to run.

• number_of_improvement_points – The number of new points to add at each iteration.

• scaler – A factor to scale the contribution of entropy or standard deviation in the acquisition score, relative to the distance.

• value_index – The index of the value column to use for acquisition methods like ‘entropy’ or ‘gaussian_process’.

• acquisition_method – The scoring method to use for selecting new points. Supported methods are “entropy” and “gaussian_process”.

static load(path) → Collection

Load a collection from a pickle file.

Parameters:

path – The path to the file.

Returns:

The loaded Collection instance.

save(path: str)

Save the collection to a pickle file.

Parameters:

path – The path to the file, including its name and file extension.

scatter(value_index: int = 0, plot_basemap=True, ax=None, zoom=16, **kwargs)

Create a scatterplot of this Collection.

Parameters:

• value_index – Which value of the collection to plot.

• plot_basemap – Whether an OpenStreetMap tile shall be rendered below.

• ax – The axis to plot to, default pyplot context if None.

• zoom – The zoom level of the OSM basemap, default 16.

• **kwargs – Args passed to the matplotlib scatter function.

to_csv(path: str, mode: str = 'w')

Saves the collection as comma-separated values file.

Parameters:

• path – The path with filename to write to.

• mode – The writing mode, one of {w, x, a}.

values() → ndarray[tuple[int, ...], dtype[Any]]

Unpack the location values as numpy array.

Returns:

The values of this Collection as numpy array.

class promis.geo.Direction(value)

Bases: float, Enum

A simple collection of named “compass” bearings in degrees for self-documenting code.

EAST = 90.0

NORTH = 0.0

SOUTH = 180.0

WEST = 270.0

class promis.geo.Geospatial(location_type: str | None, name: str | None, identifier: int | None)

Bases: ABC

The common abstract base class for both polar and cartesian geospatial objects.

See to_geo_json() on how this class can be used for visualizing geometries.

Parameters:

• location_type – The type of this polygon

• name – An optional name of this polygon

• identifier – A unique identifier for this object, in \([0, 2^{63})\), i.e. 64 signed bits

property identifier: int | None

The numerical identifier of this object.

Must be None or in \([0, 2^{63})\), i.e. 64 signed bits.

send_to_gui(url: str = 'http://localhost:8000/add_geojson', timeout: int = 1)

Send an HTTP POST-request to the GUI backend.

Parameters:

• url – url of the backend

• timeout – request timeout in second

Raises:

• HTTPError – When the HTTP request returned an unsuccessful status code

• ConnectionError – If the request fails due to connection issues

to_geo_json(indent: int | str | None = None, properties: dict | None = None, **kwargs) → str

Returns the GeoJSON representation of the geometry embedded into a feature.

Parameters:

• indent – The number of levels to indent or None (see json.dumps())

• kwargs – Much like indent, any keyword argument that can be passed to json.dumps(), like allow_nan, sort_keys, and more

Returns:

The GeoJSON representation as a string

Examples

GeoJSON is a widely used format that can be interpreted by a variety of GIS programs (geo information systems). Among them are for example the very simple website geojson.io. However, sometimes the geometries are too large to be handled by the web browser. Then there are other programs available, like the free open-source tool QGIS (Desktop). Its even available in the usual Ubuntu repositories, so just run [sudo] apt install qgis. Later, you can simply copy-pasta it into the tool.

The geojson representation can be obtained like this (using a PolarLocation just as an example):

>>> from promis.geo.location import PolarLocation
>>> darmstadt = PolarLocation(latitude=49.878091, longitude=8.654052, identifier=0)
>>> print(darmstadt.to_geo_json(indent=4))
{
    "type": "Feature",
    "id": 0,
    "geometry": {
        "type": "Point",
        "coordinates": [
            8.654052,
            49.878091
        ]
    },
    "properties": {
        "location_type": "UNKNOWN"
    }
}

See also

• GeoJSON on Wikipedia

• geojson.io

• QGIS (Desktop)

class promis.geo.Location(x: float, y: float, location_type: str | None = None, name: str | None = None, identifier: int | None = None, covariance: ndarray | None = None)

Bases: Geospatial

property covariance: ndarray | None

classmethod from_numpy(data: ndarray, *args, **kwargs) → DerivedLocation

Create a location from a numpy representation.

Parameters:

• data – An array with shape (2, 1)

• args – Positional arguments to be passed to the new location

• kwargs – Keyword arguments to be passed to the new location

Returns:

The location created from the given coordinates and other parameters

Raises:

AssertionError – If the shape of array is invalid

See also

to_numpy()

sample(number_of_samples: int = 1) → list[DerivedLocation]

Sample locations given this location’s distribution.

Parameters:

number_of_samples – How many samples to draw

Returns:

The set of sampled locations with identical name, identifier etc.

to_numpy() → ndarray

Converts the coordinates defining this location into a numpy.ndarray.

Returns:

A column vector with shape (2, 1) containing this locations longitude and latitude in degrees.

See also

from_numpy()

class promis.geo.Map(origin: PolarLocation, features: list[CartesianLocation | CartesianMap | CartesianPolygon | CartesianPolyLine | PolarLocation | PolarMap | PolarPolygon | PolarPolyLine] | None = None)

Bases: ABC

A base class for maps.

Parameters:

• origin – The origin point of this map

• features – A list of features that should be contained by this map

property all_location_types: set[str]

Get all location types contained in this map.

Returns:

A set of all location types contained in this map

apply_covariance(covariance: ndarray | dict | None)

Set the covariance matrix of all features.

Parameters:

covariance – The covariance matrix to set for all featuers or a dictionary mapping location_type to covariance matrix

filter(location_type: str) → DerivedMap

Get a map with only features of the given type.

Parameters:

location_type – The type of locations to filter for

Returns:

A map that only contains features of the given type

is_valid() → bool

Whether this map contains only valid polygonal shapes according to shapely.

Quite expensive, not cached. Invalid features might cross themselves or have zero area. Other tools might still refuse it, like GEOS.

static load(path) → Map

location_types() → list[str]

Get all location types contained in this map.

Returns:

A list of all location types contained in this map

sample(number_of_samples: int = 1) → list[DerivedMap]

Sample random maps given this maps’s feature’s uncertainty.

Parameters:

number_of_samples – How many samples to draw

Returns:

The set of sampled maps with the individual features being sampled according to their uncertainties and underlying sample methods

save(path)

to_geo_json(location_type: str | None = None, indent: int | str | None = None, **kwargs) → str

Constructs the GeoJSON string representing this map as a FeatureCollection.

For more information on GeoJSON, see promis.geo.geospatial.Geospatial.to_geo_json().

to_rtree() → STRtree | None

Convert this map into a Shapely STRtree for efficient spatial queries.

Returns:

The Shapely STRtree containing this map’s features

class promis.geo.PolarCollection(origin: PolarLocation, number_of_values: int = 1)

Bases: Collection

property dimensions: tuple[float, float]

Get the dimensions of this Collection in meters.

Returns:

The dimensions of this Collection in meters as (width, height).

to_cartesian() → CartesianCollection

Converts this PolarCollection to a CartesianCollection.

The polar (WGS84) coordinates are projected onto a local Cartesian plane centered at the collection’s origin.

Returns:

A new CartesianCollection with the data from this collection.

to_polar_locations() → list[PolarLocation]

Converts the collection’s coordinates to a list of PolarLocation objects.

Returns:

A list of PolarLocation objects.

class promis.geo.PolarLocation(longitude: float, latitude: float, location_type: str | None = None, name: str | None = None, identifier: int | None = None, covariance: ndarray | None = None)

Bases: Location

A geospatial location representing a spatial object on earth.

See here for a nice collection of formulas and explanations on geographic transformations and calculations. This is the Rome for geographic calculation questions on Stack Overflow: All roads seem to eventually lead here.

Parameters:

• longitude – The longitude in degrees within \([-180, +180)\)

• latitude – The latitude in degrees within \([-90, +90]\)

• location_type – The type of this polygon

• name – An optional name of this polygon

• identifier – An optional unique identifier for this object, in \([0, 2**63)\)

• uncertainty – An optional value representing the variance of this location’s latitude and longitude respectively

distance(other: PolarLocation, approximate: bool = False) → float

Calculate the horizontal geodesic distance to another location in meters.

This assumes an ellipsoidal earth and converges for any pair of points on earth. It is accurate to round-off and uses geographiclib (https://pypi.org/project/geographiclib/) via geopy (https://pypi.org/project/geopy/).

The faster great-circle distance can also be used by setting approximate=True. It assumes only a spherical earth and is guaranteed to give a result for any pair of points. It is wrong by up to 0.5% and based on geopy. It is advised to use the exact solution unless you know what you are doing.

See also

• https://en.wikipedia.org/wiki/Geodesics_on_an_ellipsoid

• https://en.wikipedia.org/wiki/Great-circle_distance

• https://en.wikipedia.org/wiki/Geographical_distance

Parameters:

• other – The location to measure the distance to in degrees

• approximate – Whether to use a faster approximation or not (default: False)

Returns:

The distance to the other point in meters

property latitude: float

property longitude: float

property projection: Proj

Derive a pyproj.Proj instance for projecting points.

This instance is cached for performance reasons, since its creation is relatively time consuming.

to_cartesian(origin: PolarLocation | None = None) → CartesianLocation

Projects this point to a Cartesian one according to the given global reference.

Parameters:

origin – The reference by which to project onto the local tangent plane

Returns:

The cartesian representation of this point with the given reference point being set

class promis.geo.PolarMap(origin: PolarLocation, features: list[PolarLocation | PolarMap | PolarPolygon | PolarPolyLine] | None = None)

Bases: Map

A map containing geospatial objects based on WGS84 coordinates.

Parameters:

• origin – The origin point of this map

• features – A list of features that should be contained by this map

send_to_gui(url: str = 'http://localhost:8000/add_geojson_map', timeout: int = 10)

Send an HTTP POST-request to the GUI backend to add all feature in the map to gui.

Parameters:

• url – url of the backend

• timeout – request timeout in second

Raises:

• HTTPError – When the HTTP request returned an unsuccessful status code

• ConnectionError – If the request fails due to connection issues

to_cartesian() → CartesianMap

Projects this map to a cartesian representation according to its global reference.

Returns:

The cartesian representation of this map with the given reference point being the same

class promis.geo.PolarPolyLine(locations: list[PolarLocation], location_type: str | None = None, name: str | None = None, identifier: int | None = None, covariance: ndarray | None = None)

Bases: PolyLine

A polyline (line string) based on WGS84 coordinates.

Note

This class does not yet support simplification as it was not required so far.

Parameters:

• locations – The two or more points that make up this polyline; see locations

• location_type – The type of this polygon

• name – An optional name of this polygon

• identifier – The polyline’s optional unique identifier, in \([0, 2**63)\)

• uncertainty – An optional value representing the variance of this polyline’s latitudes and longitudes respectively

classmethod from_numpy(data: ndarray, *args, **kwargs) → PolarPolyLine

Create a polar polyline from a numpy representation.

Parameters:

• data – An array with shape (number of locations, 2), where each location

• `` (is represented by a pair of)

• *args – Positional arguments to be passed to PolarPolyLine

• **kwargs – Keyword arguments to be passed to PolarPolyLine

Returns:

The polar polyline created from the given coordinates an other parameters

Raises:

AssertionError – If the shape of array is invalid

See also

to_numpy()

to_cartesian(origin: PolarLocation) → CartesianPolyLine

Projects this polyline to a Cartesian one according to the given global reference.

Parameters:

origin – The reference by which to project onto the local tangent plane

Returns:

The cartesian representation of this polyline with the given reference point being set

class promis.geo.PolarPolygon(locations: list[PolarLocation], holes: list[list[PolarLocation]] | None = None, location_type: str | None = None, name: str | None = None, identifier: int | None = None, covariance: ndarray | None = None)

Bases: Polygon

A polygon based on WGS84 coordinates.

An object with only a single point may be represented by a polygon with three times the same location.

Examples

Lets first create the perimeter of the polygon as a list of PolarLocation objects.

>>> locations = [PolarLocation(-1.0, 1.0), PolarLocation(1.0, 1.0),
...  PolarLocation(1.0, -1.0), PolarLocation(-1.0, -1.0)]

Now, we can build a polygon from these locations like so:

>>> polygon = PolarPolygon(locations)

Given another list of locations, e.g.,

>>> holes = [[PolarLocation(-0.5, 0.5), PolarLocation(0.5, 0.5),
...  PolarLocation(0.5, -0.5), PolarLocation(-0.5, -0.5)]]

we can also build a polygon that contains holes:

>>> polygon = PolarPolygon(locations, holes)

Given a covariance of this polygons translation, random samples can be drawn.

>>> from numpy import eye
>>> polygon = PolarPolygon(locations, covariance=eye(2))
>>> random_samples = polygon.sample(10)

PolarPolygons can also be created from numpy data.

>>> from numpy import array
>>> locations = array([[-1.0, 1.0, 1.0, -1.0], [1.0, 1.0, -1.0, -1.0]])
>>> polygon = PolarPolygon.from_numpy(locations)

Finally, a PolarPolygon can be turned into a CartesianPolygon given a reference origin in polar coordinates.

>>> origin = PolarLocation(0.0, 0.0)
>>> cartesian_polygon = polygon.to_cartesian(origin)

Parameters:

• locations – The points that make up this polygon; see locations

• holes – The points that make up holes in this polygon

• location_type – The type of this polygon

• name – An optional name of this polygon

• identifier – The polygon’s optional unique identifier, in \([0, 2**63)\)

• covariance – An optional matrix representing the variance of this polygon’s latitude and longitude respectively

classmethod from_numpy(data: ndarray, *args, **kwargs) → PolarPolygon

Create a polygon from a numpy representation.

Parameters:

• data – An array with shape (2, number_of_locations)

• args – Positional arguments to be passed to the new polygon

• kwargs – Keyword arguments to be passed to the new polygon

Returns:

The polygon created from the given coordinates and other parameters

Raises:

AssertionError – If the shape or content of data is invalid

See also

to_numpy()

to_cartesian(origin: PolarLocation) → CartesianPolygon

Projects the polygon to a Cartesian one according to a given global reference.

Parameters:

origin – The reference point by which to project onto the local tangent plane

Returns:

The cartesian representation of this polygon with the given reference point being set

class promis.geo.PolarRasterBand(origin: PolarLocation, resolution: tuple[int, int], width: float, height: float, number_of_values: int = 1)

Bases: RasterBand, PolarCollection

A raster-band of Polar referenced data.

Parameters:

• origin – The polar coordinates of this raster-band’s center

• resolution – The number of horizontal and vertical pixels

• width – The width the raster band stretches over in meters

• height – The height the raster band stretches over in meters

• number_of_values – How many values are stored per location

as_image(value_index: int = 0) → array

Convert the RasterBand data into a 2D array for use as image.

Parameters:

value_index – Which value to put into the image

Returns:

The RasterBand data as 2D array

class promis.geo.PolyLine(locations: list[PolarLocation | CartesianLocation], location_type: str | None = None, name: str | None = None, identifier: int | None = None, covariance: ndarray | None = None)

Bases: Geospatial

property covariance: ndarray

sample(number_of_samples: int = 1) → list[DerivedPolyLine]

Sample PolyLines given this PolyLine’s uncertainty.

Parameters:

number_of_samples – How many samples to draw

Returns:

The set of sampled PolyLines, each with same name, identifier etc.

to_numpy() → ndarray

Converts the coordinates defining this polyline into a numpy.ndarray.

Returns:

An array with shape (number of locations, 2), where each location is represented by a pair of (longitude, latitude), each in degrees.

See also

from_numpy()

class promis.geo.RasterBand(resolution: tuple[int, int], width: float, height: float)

Bases: ABC

A raster-band of spatially referenced data on a regular grid.

Parameters:

• resolution – The number of horizontal and vertical pixels

• width – The width the raster band stretches over in meters

• height – The height the raster band stretches over in meters

append(location: CartesianLocation | PolarLocation, values: list[float]) → NoReturn

search_path(start: tuple[float, float], goal: tuple[float, float], graph: ~networkx.classes.graph.Graph | None = None, cost_model: ~collections.abc.Callable[[float], float] = <function RasterBand.<lambda>>, value_filter: ~collections.abc.Callable[[float], float] = <function RasterBand.<lambda>>, min_cost: float = 0.3) → ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Search the shortest path through this RasterBand using A*.

Note

To perform efficient path planning, assumes that all costs are bounded by 0 < min_cost < 1 and 1. This permits defining an admissible heuristic for A* that is a lower bound on the cost of the path.

Parameters:

• start – The starting location (clipped to the nearest RasterBand pixel)

• goal – The goal location (clipped to the nearest RasterBand pixel)

• cost_model – A function that maps RasterBand values to edge weights

• value_filter – A function that is applied to RasterBand values to decide if they should become edges in the graph

Returns:

The shortest path from start to goal given the costs induced by the given models and RasterBand values

static stack_graphs(graphs: dict[tuple[Any], Graph], vertical_weight: float = 0.0) → Graph

Create a new graph containing the data of the old ones with ‘vertical’ connections.

Parameters:

• graphs – A dictionary of graphs to be stacked, where the keys are the labels and the values are the graphs themselves. The new nodes will be tuples of the form (x, y, *label) with weight vertical_weight.

• vertical_weight – The weight of the vertical edges between the graphs. For simplicity, this is currently assumed to be the same for all graphs.

to_graph(cost_model: ~collections.abc.Callable[[tuple[~typing.Any], tuple[~typing.Any], float, float], float] = <function RasterBand.<lambda>>, value_filter: ~collections.abc.Callable[[tuple[~typing.Any], float], bool] = <function RasterBand.<lambda>>) → Graph

Convert a RasterBand into a NetworkX Graph for path planning.

Parameters:

• cost_model – A function that maps (source_node, target_node, source_value, dest_value) to edge weights

• value_filter – A function that is applied to (node, value) to decide if they should become nodes in the graph

Returns:

The corresponding graph where the cost of visiting a node is determined by the RasterBand’s values and cost_model

Loaders

The ProMis loaders package provides data loading for various sources.

class promis.loaders.NauticalLoader(chart_root: Path, origin: PolarLocation, dimensions: tuple[float, float])

Bases: SpatialLoader

load(feature_description=None, n_jobs: int | None = None) → None

Populates features with from a source.

Parameters:

feature_description – A mapping of location types to loader specific descriptions. Passing None can be valid for loaders with a fixed set of features.

class promis.loaders.OsmLoader(origin: PolarLocation, dimensions: tuple[float, float], feature_description: dict[str, str] | None = None, timeout: float = 5.0)

Bases: SpatialLoader

A loader for spatial data from OpenStreetMaps (OSM) via the Overpass API.

This loader connects to the Overpass API to fetch map features like buildings, roads, and other geographical entities based on specified filters.

Note

If a feature_description is provided during initialization, data loading via the load method is triggered immediately. If it is not provided, you must call load() manually with a feature description to populate the loader with data.

Parameters:

• origin – The polar coordinates of the map’s center.

• dimensions – The (width, height) of the map in meters.

• feature_description – A mapping from a location type (e.g., “buildings”) to an Overpass API filter string (e.g., “[building]”). If provided, data is loaded upon initialization. Defaults to None.

• timeout – The number of seconds to wait before retrying a failed API query.

load(feature_description: dict[str, str]) → None

This method queries the Overpass API for ways and relations matching the provided filters. It handles retries for common network issues.

• Ways are converted to PolarPolyLine (if open) or PolarPolygon (if closed).

• Relations are converted to PolarPolygon.

Parameters:

feature_description – A mapping from a location type (e.g., “buildings”) to an Overpass API filter string (e.g., “[building]”). If None, no features are loaded.

static relation_to_polygon(relation: Relation, **kwargs) → PolarPolygon

Turn an OSM relation into a PolarPolygon.

Parameters:

• relation – The relation to turn into a PolarPolygon.

• **kwargs – Arguments that are given to PolarPolygon, e.g., location_type.

Returns:

The PolarPolygon from the data in the relation.

Raises:

ValueError – If the relation does not contain exactly one ‘outer’ way.

class promis.loaders.SpatialLoader(origin: PolarLocation, dimensions: tuple[float, float])

Bases: ABC

A base class for loaders of geospatial objects from different sources and interfaces.

Parameters:

• origin – The polar coordinates of the map’s center.

• dimensions – The (width, height) of the map in meters.

static compute_polar_bounding_box(origin: PolarLocation, dimensions: tuple[float, float]) → tuple[float, float, float, float]

Computes the north, east, south and west limits of the area to be loaded.

Parameters:

• origin – A point that defines the center of the map.

• dimensions – The width and height of the map in meters.

Returns:

A tuple containing (southern latitude, western longitude, northern latitude, eastern longitude).

abstract load(feature_description: dict[str, Any] | None = None) → None

Populates features with from a source.

Parameters:

feature_description – A mapping of location types to loader specific descriptions. Passing None can be valid for loaders with a fixed set of features.

to_cartesian_map() → CartesianMap

Creates a CartesianMap from the loaded features.

This is a convenience method that first creates a polar map and then converts it to Cartesian coordinates.

Returns:

A CartesianMap containing all loaded features, with (0, 0) corresponding to the loader’s origin.

to_polar_map() → PolarMap

Creates a PolarMap from the loaded features.

Returns:

A PolarMap centered at the loader’s origin containing all loaded features.

Logic

The ProMis logic package provides probabilistic logic program inference and spatial relations.

class promis.logic.Depth(parameters: CartesianCollection, location_type: str)

Bases: ScalarRelation

The depth information, modeled as a Gaussian distribution.

This relation is binary, relating a location to its depth. The depth is typically extracted from features of type “water”.

Parameters:

• parameters – A collection of points with each having values as [mean, variance].

• location_type – The type of the locations for which the depth is computed. A warning will be raised if this is not “water”.

static arity() → int

Returns the arity of the ‘depth’ relation, which is 2 (location, feature_type).

static compute_relation(location: CartesianLocation, r_tree: STRtree, original_geometries: CartesianMap) → float

Computes the depth at a location based on the nearest water feature.

If the map is empty, it returns a depth of 0 (sea level).

Parameters:

• location – The location to compute the depth for.

• r_tree – The R-tree of the map geometries for efficient querying.

• original_geometries – The original map geometries, which contain metadata.

Returns:

The depth in meters.

static empty_map_parameters() → list[float]

Returns the parameters for an empty map.

By default, this assumes a depth of 0 (sea level) with a default variance, representing a uniform distribution of depth values.

plot(value_index: int = 0, axis: Axes | None = None, grid_shape: tuple[int, int] | None = None, **kwargs)

Plots the depth relation as a 2D image.

This method is primarily designed for data stored in a CartesianRasterBand. If the data is in a different CartesianCollection, grid_shape must be provided to reshape the data for plotting.

The plot uses a diverging colormap centered at 0.0 (sea level).

Parameters:

• value_index – The index of the value to plot (0 for mean, 1 for variance).

• axis – The matplotlib axes to plot on. If None, a new figure and axes are created.

• grid_shape – The (height, width) to reshape the data into if it’s not a raster. Required for non-raster data.

• **kwargs – Additional keyword arguments passed to matplotlib.axes.Axes.imshow.

Returns:

The AxesImage object created by imshow.

Raises:

ValueError – If the parameters are not a CartesianRasterBand and grid_shape is not provided.

class promis.logic.Distance(parameters: CartesianCollection, location_type: str)

Bases: ScalarRelation

The distance relation, modeled as a Gaussian distribution.

This relation models the distance from a given location to the nearest map feature of a specific type. The distance is represented by a Gaussian distribution, defined by a mean and variance calculated from a set of sample maps.

Parameters:

• parameters – A collection of points, where each has values for [mean, variance].

• location_type – The name of the feature type this distance relates to (e.g., “buildings”).

static arity() → int

Returns the arity of the ‘distance’ relation, which is 2 (location, feature_type).

static compute_relation(location: CartesianLocation, r_tree: STRtree, original_geometries: CartesianMap) → float

Computes the distance from a location to the nearest geometry in the map.

Parameters:

• location – The location to compute the distance from.

• r_tree – The R-tree of the map geometries for efficient querying.

• original_geometries – The original map geometries (unused in this relation, but required by the abstract base class).

Returns:

The Euclidean distance to the nearest geometry.

static empty_map_parameters() → list[float]

Returns the parameters for an empty map.

This is a large distance with approximately zero variance, representing an effectively infinite distance to any feature.

class promis.logic.Over(parameters: CartesianCollection, location_type: str | None)

Bases: Relation

A probabilistic relation that checks if a point is “over” (i.e., within) a map feature.

This relation is true if a given location is contained within any of the geometries of a specific type on the map. The probability is derived from a set of sample maps.

static arity() → int

Returns the arity of the ‘over’ relation, which is 2 (location, feature_type).

static compute_relation(location: CartesianLocation, r_tree: STRtree, original_geometries: CartesianMap) → float

Checks if a location is within any of the geometries in the map.

This method queries the R-tree for all geometries that could contain the location and then performs a precise check.

Parameters:

• location – The location to check.

• r_tree – The R-tree of the map geometries for efficient querying.

• original_geometries – The original map geometries (unused in this relation).

Returns:

1.0 if the location is within any geometry, 0.0 otherwise.

static empty_map_parameters() → list[float]

Returns the parameters for an empty map, which is a probability of 0.0 with 0 variance.

index_to_distributional_clause(index: int) → str

Express a single index of this Relation as a distributional clause.

The clause is formatted as PROBABILITY::over(x_INDEX, location_type)., where the probability is the mean probability of the point being over a feature across the sample maps.

Parameters:

index – The index of the point within the parameters collection.

Returns:

A string representing the distributional clause for the specified entry.

class promis.logic.Relation(parameters: CartesianCollection, location_type: str | None)

Bases: ABC

An abstract base class for spatial relations.

A spatial relation models a probabilistic relationship between points in space and typed map features. It is typically represented by a distribution (e.g., Gaussian) for each point, defined by a set of parameters like mean and variance.

Parameters:

• parameters – A collection of points, where each point is associated with parameters that define the relation’s distribution (e.g., mean and variance).

• location_type – A string identifier for the type of map feature this relation pertains to, such as “buildings” or “roads”. Can be None if the relation is not specific to a feature type.

abstract static arity() → int

Return the arity of the relation.

classmethod compute_parameters(location: CartesianLocation, r_trees: list[STRtree], original_geometries: list[CartesianMap]) → array

Compute the parameters of this Relation type for a specific location and set of maps.

Parameters:

• location – The location to evaluate in Cartesian coordinates.

• r_trees – A list of generated maps, each represented as an R-tree.

• original_geometries – The original geometries indexed by the STRtrees.

Returns:

A numpy array containing the computed parameters (e.g., mean and variance) of the relation’s distribution for the given location.

abstract static compute_relation(location: CartesianLocation, r_tree: STRtree, original_geometries: CartesianMap) → float

Compute the value of this Relation type for a specific location and map.

Parameters:

• location – The location to evaluate in Cartesian coordinates.

• r_tree – The map represented as an R-tree for efficient spatial queries.

• original_geometries – The original geometries indexed by the STRtree.

Returns:

A scalar value representing the computed relation (e.g., distance, depth).

abstract static empty_map_parameters() → list[float]

Create the default parameters for a relation computed on an empty map.

These parameters are used as a fallback when no map features are present to compute the relation from.

classmethod from_r_trees(support: CartesianCollection, r_trees: list[STRtree], location_type: str, original_geometries: list[CartesianMap]) → DerivedRelation

Compute relation for a Cartesian collection of points and a set of R-trees.

Parameters:

• support – The collection of Cartesian points to compute the relation for.

• r_trees – Random variations of the features of a map, each indexible by an STRtree.

• location_type – The type of features this relates to.

• original_geometries – The original geometries indexed by the STRtrees.

Returns:

A new instance of the Relation class, populated with the computed parameters.

abstract index_to_distributional_clause(index: int) → str

Express a single index of this Relation as a distributional clause.

Parameters:

index – The index of the point within the parameters collection.

Returns:

A string representing the distributional clause for the specified entry.

static load(path: str | Path) → DerivedRelation

Load the relation from a .pkl file.

Parameters:

path – The path to the file, including its name and file extension.

Returns:

The loaded Relation instance

save(path: str | Path) → None

Save the relation to a .pkl file.

Parameters:

path – The path to the file, including its name and file extension.

save_as_plp(path: str | Path) → None

Save the relation as a text file containing distributional clauses.

Parameters:

path – The path to the file, including its name and file extension.

to_distributional_clauses() → list[str]

Express the Relation as distributional clause.

A distributional clause is a string representation of a probabilistic fact, suitable for use in a probabilistic logic program.

Returns:

A list of distributional clauses, one for each point in the parameters collection.

class promis.logic.ScalarRelation(parameters: CartesianCollection, location_type: str | None, problog_name: str, enforced_min_variance: float | None = 0.001)

Bases: Relation

A relation representing a scalar value modeled by a Gaussian distribution.

This class provides a concrete implementation for relations where the value at each point can be described by a mean and a variance. It also implements comparison operators (<, >) to facilitate probabilistic queries based on the Commulative Distribution Function (CDF) of the Gaussian distribution.

Parameters:

• parameters – A collection of points, where each has values for [mean, variance].

• location_type – The name of the locations this distance relates to.

• problog_name – The name to be used for this relation in Problog clauses.

• enforced_min_variance – The minimum variance to enforce for the distribution. Values below this will be clipped.

index_to_distributional_clause(index: int) → str

Express a single index of this Relation as a distributional clause.

Formats the clause as name(x_INDEX, location_type) ~ normal(MEAN, STD). or name(x_INDEX) ~ normal(MEAN, STD). if location_type is None.

Parameters:

index – The index of the point within the parameters collection.

Returns:

A string representing the distributional clause for the specified entry.

class promis.logic.Solver(program: str, configuration: dict[str, Any] | None = None)

Bases: object

A solver for Hybrid Probabilistic Logic Programs (HPLP) in ProMis.

This class wraps the DCProbLog inference engine, providing a simplified interface for running queries on a probabilistic logic program.

Parameters:

• program – The logic program, written as a string in ProbLog syntax with distributional clauses.

• configuration – A dictionary of configuration options for the DCProbLog solver. If None, default settings are used. See DEFAULT_SOLVER_CONFIGURATION.

inference(configuration: dict[str, Any] | None = None) → list[float]

Run probabilistic inference on the given program.

Parameters:

configuration – A dictionary of configuration options to override the solver’s default settings for this specific inference run.

Returns:

A list of probabilities, one for each query in the program.

Models

Provides mathematical abstractions for usage within Promis.

class promis.models.Gaussian(mean: ndarray, covariance: ndarray, weight: float = 1.0)

Bases: object

A weighted multivariate gaussian distribution.

Examples

A Gaussian can be simply created from a mean and covarinace vector (and an optional weight):

>>> from numpy import array
>>> from numpy import vstack
>>> mean = vstack([0.0, 0.0])
>>> covariance = array([[1.0, 0.0], [0.0, 1.0]])
>>> N = Gaussian(mean, covariance, weight=1.0)
>>> N(vstack([0.0, 0.0])).item()  
0.159...

Two Gaussians are equal if and only if all attributes are equal:

>>> N == N
True
>>> other_covariance = array([[99.0, 0.0], [0.0, 99.0]])
>>> other_N = Gaussian(mean, other_covariance, weight=1.0)
>>> other_N(vstack([10.0, 10.0])).item()  
0.000585...
>>> N == other_N
False

Sampling from Gaussians is straight forward as well. Either a single

>>> sample = N.sample()
>>> sample.shape
(2, 1)

or many samples

>>> sample = N.sample(100)
>>> sample.shape
(2, 100)

can be generated at once.

Parameters:

• mean – The mean of the distribution as column vector, of dimension (n, 1)

• covariance – The covariance matrix of the distribution, of dimension (n, n)

• weight – The weight of the distribution, e.g. within a mixture model

References

• https://en.wikipedia.org/wiki/Multivariate_normal_distribution

property P: ndarray

cdf(x: ndarray) → float

Compute the CDF as integral of the PDF from negative infinity up to x.

Parameters:

x – The upper bound of the integral

Returns:

The probability of a value being less than x

sample(number_of_samples: int = 1) → ndarray

Draw a number of samples following this Gaussian’s distribution.

Parameters:

number_of_samples – The number of samples to draw

Returns:

The drawn samples

property w: float

property x: ndarray

class promis.models.GaussianMixture(components: list[Gaussian] | None = None)

Bases: object

The Gaussian Mixture Model (GMM) for representing multi-modal probability distribution.

Parameters:

components – An initial list of components to consider in this GMM

append(component: Gaussian)

Appends a new Gaussian to this Mixture’s list of components.

Parameters:

component – The new Gaussian to append

modes(threshold: float = 0.5) → list[ndarray]

Extract all modes of the mixture model that are above a set threshold.

Parameters:

threshold – Weight that a component needs to have to be considered

Returns:

The locations of all modes with weight larger than the threshold

prune(threshold: float, merge_distance: float, max_components: int) → None

Reduces the number of gaussian mixture components.

Parameters:

• threshold – Truncation threshold s.t. components with weight < threshold are removed

• merge_distance – Merging threshold s.t. components ‘close enough’ will be merged

• max_components – Maximum number of gaussians after pruning

class promis.models.GaussianProcess

Bases: object

A Gaussian Process regressor using GPyTorch for scalable updates.

fit(coordinates: ndarray[tuple[int, ...], dtype[_ScalarType_co]], values: ndarray[tuple[int, ...], dtype[_ScalarType_co]], number_of_iterations: int = 50) → float

predict(coordinates: ndarray[tuple[int, ...], dtype[_ScalarType_co]], return_std: bool = False)

Estimators

This package provides methods for state estimation, visual perception, mapping and similar.