privkit.utils package#

privkit.utils.constants module#

Useful constants

privkit.utils.dev_utils module#

privkit.utils.dev_utils.error(message)#
privkit.utils.dev_utils.log(message)#
privkit.utils.dev_utils.warn(message)#

privkit.utils.discrete_utils module#

Discrete utility classes and methods.

class privkit.utils.discrete_utils.BoundingBox(min_latitude: float, max_latitude: float, min_longitude: float, max_longitude: float)#

Bases: object

get_bounding_box_array()#

Returns the latitudes and longitudes which bound the bounding box. :return: min and max latitude and longitude which bound the bounding box

get_bounding_box_corners()#

Returns the bounding corners which bound the bounding box. :return: lower left and upper right corners which bound the bounding box.

class privkit.utils.discrete_utils.Cell(lower_latitude: float, upper_latitude: float, leftmost_longitude: float, rightmost_longitude: float, cell_id: int)#

Bases: object

get_width_height()#

Computes the dimensions of the cell. :return: width and height of the cell

class privkit.utils.discrete_utils.GridMap(min_lat: float, max_lat: float, min_lon: float, max_lon: float, spacing: float)#

Bases: object

export_grid(output_file_path: str)#

Exports the grid to the file specified by :output_file_path: in CSV format, where each line is the ordered centers of the cells as: <latitude>, <longitude>

Parameters:

output_file_path – path where grip will be exported to

get_cartesian_cell(i: int, j: int)#

Computes the center of the respective grid map cell in cartesian coordinates.

Parameters:

  • i (int) – row position of the cell

  • j (int) – column position of the cell

Returns:

center of the cell in cartesian coordinates

get_cartesian_cells()#

Builds a matrix of the same size as the grid where each element represents the center of the respective grid map cell in cartesian coordinates.

Returns:

matrix of the centers of the grid map in cartesian coordinate system

get_cell_with_point_within(latitude: float, longitude: float)#

Computes the cell indexes where the given point is contained.

Parameters:

  • latitude (float) – location latitude

  • longitude (float) – location longitude

Returns:

indexes of the cell where point is contained

get_corners()#

Computes min and max latitude and longitude which bound the grid. :return: list of min and max latitude and longitude of the grid

get_locationstamp(latitude: float, longitude: float)#

Given a point finds in which cell it is contained.

Parameters:

  • latitude – point’s latitude

  • longitude – point’s longitude

Returns:

cell ID where point is contained

get_size()#

Computes the number of vertical and horizontal cells. :return: list containing the number of vertical and horizontal cells

point_within_grid(latitude: float, longitude: float)#

Given a point verifies if it is within the grid.

Parameters:

  • latitude (float) – point’s latitude

  • longitude (float) – point’s longitude

Returns:

True if the point is within the grid, False otherwise

privkit.utils.face_utils module#

Facial utility methods.

privkit.utils.face_utils.block_print()#

Temporarily redirects standard output to suppress printing

privkit.utils.face_utils.enable_print()#

Restores standard output, allowing printing to the console

privkit.utils.face_utils.folder_to_img(folder: str, store_dir: str, xlim: tuple, ylim: tuple, axis_face: str, point_size: int = 25)#

Creates a new folder and stores ‘png’ images resulting from an orthographic projection of point cloud files within a folder

Parameters:

  • folder (str) – the folder path to search for files

  • xlim (tuple) – the interval of the Y axis of the scatter plot

  • ylim (tuple) – the interval of the X axis of the scatter plot

  • store_dir (str) – the path where the projected images should be stored

  • axis_face (str) – the axis where the face is pointing (‘x’, ‘y’ or ‘z’)

  • point_size (int) – the size of each point on the scatter plot

privkit.utils.face_utils.list_files(directory: str, extension: tuple)#

Retrieve a list of file paths with a specified extension within a given directory

Parameters:

  • directory (str) – The directory to search for files

  • extension (tuple) – The file extension(s) to filter the results (e.g., (‘.png’, ‘.jpg’))

Returns:

A list containing the absolute paths of files matching the specified extension(s)

privkit.utils.face_utils.list_folders(directory: str)#

Retrieve a list of folder paths within a given directory

Parameters:

directory (str) – The directory to search for folders

Returns:

A list containing the absolute paths of folders

privkit.utils.face_utils.pcd_to_img(pcd: open3d.cpu.pybind.geometry.PointCloud, xlim: tuple, ylim: tuple, store_path: str, axis_face: str, point_size: float = 25)#

Stores a ‘png’ image resulting from an orthographic projection of a point cloud

Parameters:

  • pcd (PointCloud) – the point cloud to be projected

  • xlim (tuple) – the interval of the Y axis of the scatter plot

  • ylim (tuple) – the interval of the X axis of the scatter plot

  • store_path (str) – the path where the image should be stored

  • axis_face (str) – the axis where the face is pointing (‘x’, ‘y’ or ‘z’)

  • point_size (int) – the size of each point on the scatter plot

privkit.utils.geo_utils module#

Geospatial utility methods.

privkit.utils.geo_utils.EARTH_RADIUS = 6371009#

Earth radius a constant in meters

privkit.utils.geo_utils.cartesian2geodetic(x: float, y: float, z: float) → [<class 'float'>, <class 'float'>]#

Converts cartesian to geodetic coordinates

Parameters:

  • x (float) – cartesian coordinate

  • y (float) – cartesian coordinate

  • z (float) – cartesian coordinate

Returns:

geodetic coordinates latitude and longitude

privkit.utils.geo_utils.compute_bearing(lat1: float, lon1: float, lat2: float, lon2: float) → float#

Computes the bearing between two points’ coordinates. Expects coordinates in decimal degrees.

Parameters:

  • lat1 (float) – first point’s latitude coordinate

  • lon1 (float) – first point’s longitude coordinate

  • lat2 (float) – second point’s latitude coordinate

  • lon2 (float) – second point’s longitude coordinate

Returns:

bearing from point (lat1, lon1) to (lat2, lon2) in degrees

Return type:

float

privkit.utils.geo_utils.compute_highway_speeds_default(G: networkx.MultiDiGraph) → dict#

Computes highway types and typical speeds from a given graph G.

Parameters:

G (networkx.MultiDiGraph) – road network represented as a directed graph

Returns:

dictionary where keys are the highway types and the values are their typical speeds

privkit.utils.geo_utils.compute_trace_distance(latitudes: List, longitudes: List)#

Computes trace distance in meters given the list of latitudes and longitudes.

Parameters:

  • latitudes (List) – list of latitudes

  • longitudes (List) – list of longitudes

Returns:

trace distance in meters

privkit.utils.geo_utils.euclidean_distance(x1: float, y1: float, x2: float, y2: float) → float#

Computes the Euclidean distance between two points. For accurate results, use projected coordinates rather than decimal degrees.

Parameters:

  • x1 (float) – first point’s x coordinate

  • y1 (float) – first point’s y coordinate

  • x2 (float) – second point’s x coordinate

  • y2 (float) – second point’s y coordinate

Returns:

distance from point (x1, y1) to (x2, y2) in coordinate’s units

Return type:

float

privkit.utils.geo_utils.geodetic2cartesian(latitude: float, longitude: float, earth_radius: float = 6371009) → [<class 'float'>, <class 'float'>, <class 'float'>]#

Converts geodetic coordinates to cartesian

Parameters:

  • latitude (float) – geodetic coordinate

  • longitude (float) – geodetic coordinate

  • earth_radius (float) – radius of earth in units in which distance will be returned (default meters)

Returns:

cartesian coordinates x, y, and z

privkit.utils.geo_utils.get_dijkstra_length_path(G: networkx.MultiDiGraph, start_node: int, end_node: int, weight: str = 'length') → [<class 'float'>, typing.List]#

Computes the dijkstra path and respective length

Parameters:

  • G (networkx.MultiDiGraph) – road network represented as a directed graph

  • start_node (int) – id of the node where the path should start

  • end_node (int) – id of the node where the path should end

  • weight (str) – weight to compute the dijkstra path. The default is ‘length’.

Returns:

path from the start node to the end node and respective length, computed according to the weight parameter

privkit.utils.geo_utils.great_circle_distance(lat1: float, lon1: float, lat2: float, lon2: float, earth_radius: float = 6371009) → float#

Computes the great-circle distance between two points’ coordinates. Expects coordinates in decimal degrees.

Parameters:

  • lat1 (float) – first point’s latitude coordinate

  • lon1 (float) – first point’s longitude coordinate

  • lat2 (float) – second point’s latitude coordinate

  • lon2 (float) – second point’s longitude coordinate

  • earth_radius (float) – radius of earth in units in which distance will be returned (default meters)

Returns:

distance from point (lat1, lon1) to (lat2, lon2) in units of earth_radius (default meters)

Return type:

float

privkit.utils.geo_utils.project2crs(latitude: float, longitude: float, crs: int) → [<class 'float'>, <class 'float'>]#

Projects a point (latitude, longitude) to a different CRS.

Parameters:

  • latitude (float) – latitude to be projected

  • longitude (float) – longitude to be projected

  • crs (int or str or dict or pyproj.CRS) – the new coordinate reference system (CRS)

Returns:

projected point (x, y) in the new CRS

privkit.utils.io_utils module#

IO utility methods.

privkit.utils.io_utils.read_dataframe(filepath_or_buffer: str, unique: bool = True, extension: str | None = None, **kwargs)#

Reads data to a pandas dataframe object.

Parameters:

  • filepath_or_buffer (str or Path or object) – either a path to a file (a str or Path) or any object that can be read from pandas read() methods.

  • unique (bool) – if True, this method is the unique method to read dataframe. If False, data can be read with other method. The default value is True.

  • extension (str) – specify the file extension. Default value is None.

  • kwargs – the keyword arguments are used for specifying arguments according to the Pandas read methods.

Returns:

pandas dataframe object or the parameter filepath_or_buffer.

privkit.utils.io_utils.write_dataframe(data2save: pandas.DataFrame, filepath: str, filename: str, extension: str = 'pkl')#

Writes a dataframe to a file.

Parameters:

  • data2save (pd.DataFrame) – dataframe to save.

  • filepath (str) – path where data should be saved.

  • filename (str) – name of the file to be saved.

  • extension (str) – extension of the format of how the file should be saved. The default value is ‘pkl’.

privkit.utils.plot_utils module#

Plot utils

This module contains methods that are useful to plot data

privkit.utils.plot_utils.boxplot(values: Any, labels: Any | None = None, title: str = '', show: bool = False, **kwargs)#

This method produces a boxplot from the given values and labels

Parameters:

  • values (Any) – values to plot

  • labels (Any) – labels of the values to plot

  • title (str) – title of the plot

  • show (bool) – if True, show the plot.

  • kwargs – the keyword arguments are used for specifying arguments according to the plot read methods.

privkit.utils.plot_utils.pie_plot(values: Any, labels: Any, title: str = '', show: bool = False, **kwargs)#

This method produces a pieplot from the given values and labels

Parameters:

  • values (Any) – values to plot

  • labels (Any) – labels of the values to plot

  • title (str) – title of the plot

  • show (bool) – if True, show the plot.

  • kwargs – the keyword arguments are used for specifying arguments according to the plot read methods.

privkit.utils.plot_utils.plot_errorbar(x: Any, y: Any, confidence_level: float = 0.95, title: str = '', x_label: str = '', y_label: str = '', show: bool = False, **kwargs)#

This method plots an error bar according to x values and y values.

Parameters:

  • x (Any) – values to plot in the x axis

  • confidence_level (float) – level of confidence for the error bar

  • y (Any) – values to plot in the y axis

  • title (str) – title of the plot

  • x_label (str) – label of the x axis

  • y_label (str) – label of the y axis

  • show (bool) – if True, show the plot.

  • kwargs – the keyword arguments are used for specifying arguments according to the plot read methods.

privkit.utils.plot_utils.plot_information(title: str = '', x_label: str = '', y_label: str = '', show: bool = False)#

This method adds title and axis labels to plots

Parameters:

  • title (str) – title of the plot

  • x_label (str) – label of the x axis

  • y_label (str) – label of the y axis

  • show (bool) – if True, show the plot.

privkit.utils.plot_utils.plot_xy_data(x: Any, y: Any, title: str = '', x_label: str = '', y_label: str = '', show: bool = False, **kwargs)#

This method plots x values and y values.

Parameters:

  • x (Any) – values to plot in the x axis

  • y (Any) – values to plot in the y axis

  • title (str) – title of the plot

  • x_label (str) – label of the x axis

  • y_label (str) – label of the y axis

  • show (bool) – if True, show the plot.

  • kwargs – the keyword arguments are used for specifying arguments according to the plot read methods.

privkit.utils.training_utils module#

class privkit.utils.training_utils.BuildKnowledge#

Bases: object

get_mobility_profile(location_data: LocationData, chosen_profile: str)#

Computes the mobility profile using the chosen data

Parameters:

  • location_data (privkit.LocationData) – location data

  • chosen_profile (str) – type of mobility profile to be computed, with the training or the testing data

Returns:

mobility profile of type chosen_profile

norm_location_histogram(data: [<class 'int'>])#

Computes the histogram for mobility profile

Parameters:

data ([int]) – location stamps from train or test data to generate mobility profile

Returns:

mobility profile

class privkit.utils.training_utils.Velocities(user_velocity_max: int = 200, report_velocity_max: int = 200)#

Bases: object

get_velocities_pd(data: pandas.DataFrame)#

Builds the velocities distributions

Parameters:

data (pandas.DataFrame) – data used to calculate the velocities

Returns:

user velocity pd and report velocity pd

kernel_distribution(velocities: [<class 'float'>], type_of_data: str)#

Computes the Kernel Density Distribution of the user or report velocities

Parameters:

  • velocities ([float]) – user or report velocities

  • type_of_data (str) – indicates if it is being considered the user or report velocities

Returns:

velocity pd

static process_user_data(user_data: pandas.DataFrame)#

Computes the time interval and distance between the user data

Parameters:

user_data (pandas.DataFrame) – data from a certain user

Returns:

the time gap and the distance between every two consecutive report