oraclesai

class CombineOpType(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Definitions of combine operations between two geometries

DIFFERENCE = 'DIFFERENCE': Returns the region covered by a geometry that is not also covered by the other geometry.

INTERSECTION = 'INTERSECTION': Returns the region of a geometry that is also shared by the other geometry.

UNION = 'UNION': Returns the region covered by two geometries.

XOR = 'XOR': Returns the region of two geometries that is not shared by both.

class DBSpatialDataset(table: str, schema: str = None, cursor: Cursor = None, spatial_column: str = None, **kwargs)

A reference to a database table with a geometry layer.

Parameters:

table – name of a table with a spatial layer in the database.
schema – name of the schema where table is defined.
cursor – an oracledb.Cursor to connect to the database. If running on OML Notebooks and it is not passed, the cursor is taken from oml.cursor()
spatial_column – Name of the column of type SDO_GEOMETRY.

class FileSpatialDataset(path: str, driver: str = None)

Reference to a file or directory within a local file system.

Parameters:

path (str) – path of the referenced resource.
driver – The OGR format driver used to read or write the file. Allowed values are determined by fiona.supported_drivers. If not specified, it attempts to infer it from the file extension. If writing and no extension is specified, it uses the driver ESRI Shapefile.

class GeoDataFrameDataset(gdf: GeoDataFrame)

A reference to an existing GeoDataFrame. Used for creating a SpatialDataFrame from a GeoDataFrame.

Parameters:: gdf – An instance of geopandas.GeoDataFrame.

class PARObjStoreSpatialDataset(par_url: str, namespace: str = None, bucket: str = None, prefix: str = None, object_name: str = None, driver: str = None)

Contains a Pre-Authenticated request URL to a folder or object in a spatial format located in Oracle Object Store.

Parameters:

par_url – The full PAR URL to the resource or at minimum the host URL with the PAR unique code.
namespace – The namespace name of the PAR. It overrides the namespace specified in par_url, if any.
bucket – The bucket name of the PAR. It overrides the bucket specified in the par_url, if any.
prefix – The prefix of the object. It overrides the prefix specified in the par_url, if any.
object_name – The name of the object or folder. It overrides the object name specified in the par_url, if any.
driver – The OGR format driver used to read or write the object. Allowed values are determined by fiona.supported_drivers. If not specified, it attempts to infer it from the object extension. If writing and no extension is specified, it uses the driver ESRI Shapefile.

class SpatialDataFrame(dataset: SpatialDataset)

A pandas-like interface for handling spatial vector data as if the data were in memory regardless of the data location.

An instance of SpatialDataFrame is created using the create method.

The create method takes in an instance of oraclesai.SpatialDataset which is used to describe the dataset to be associated to the proxy.

The following example shows how to create a SpatialDataFrame for a spatial table in Oracle database.

>>> from oraclesai import SpatialDataFrame, DBSpatialDataset
>>> dataset = DBSpatialDataset(cursor=oracledb_cursor, table='chicago_accidents')
>>> sdf = SpatialDataFrame.create(dataset)
>>> sdf.head()
            OGR_FID   REPORT_TYP                    geometry
0           657       ON SCENE                      POINT (-9755760.901 5133215.436)
1           659       ON SCENE                      POINT (-9758088.412 5156991.966)
            661       NOT ON SCENE (DESK REPORT)    POINT (-9758162.478 5125561.017)

More SpatialDataset implementations can be used to load data from Oracle Object Storage, local files, and from an existing geopandas.GeoDataFrame.

Once an instance of SpatialDataFrame has been created, it can be used to apply spatial transformations. If the data is located in Oracle database, The in-database Oracle Spatial engine will be used to perform spatial operations.

A SpatialDataFrame is immutable so each transformation will result in a new instance of SpatialDataFrame.

When a SpatialDataFrame is created for data residing in Oracle database, the data is downloaded (materialized) until it is needed in memory, for example, when it is transformed to a geopandas.GeoDataFrame by calling oraclesai.SpatialDataFrame.as_geodataframe() or oraclesai.SpatialDataFrame.head(), or when the data is written to another source such as Oracle Object Storage or to a file system using the method oraclesai.SpatialDataFrame.write().

add_column(column_name, series)

Add series as a new column to the current proxy. The column to be added must have the same number of rows as the current SpatialDataFrame.

Parameters:

column_name – name of the column to be added
series – A pandas’ Series, numpy array or a single-column SpatialDataFrame. If SpatialDataFrame references data from the database and series is a pandas or numpy array, the resulting SpatialDataFrame will fetch all the data to the client.

Returns:

a SpatialDataFrame containing the new column

abstract area(tolerance=None, area_col='AREA')

Get the area for each geometry from the current SpatialDataFrame.

Parameters:

tolerance – Spatial tolerance.
area_col – Name of the new column containing area values.

Returns:

A new SpatialDataFrame containing the areas as a new column.

abstract as_geodataframe() → GeoDataFrame

Convert the current SpatialDataFrame to geopandas.GeoDataFrame.

Returns:: a geopandas.GeoDataFrame.

as_oml_dataframe(): Transform the current SpatialDataFrame to an instance of oml.DataFrame

abstract buffer(distance: float)

Construct a buffer around each geometry. The result contains the same rows and column than the source but the geometry is buffered.

Parameters:: distance – distance of the buffer.
Returns:: a new SpatialDataFrame.

abstract property columns

Return a list of column names.

Returns:: A list of strings.

abstract combine(tgt, combine_op: CombineOpType = CombineOpType.UNION, tolerance: float = None, how='inner', on=None, left_on=None, right_on=None, qry_win_out_cols=None)

Combines the geometries from the current SpatialDataFrame with the geometries in tgt.

Parameters:

tgt – A SpatialDataFrame, GeoDataFrame, GeoSeries or a single shapely geometry.
combine_op – (default CombineOpType.UNION) The type of combine operation to be performed.
tolerance – The spatial tolerance.
how – Specifies how the join will be performed. Possible values are: ‘inner’ (default), ‘full’, ‘left’ or ‘right’.
on – A column name or a list of column names. Column(s) contained in both SpatialDataFrames which will be used as joining key(s). If this parameter is set, left_on and right_on will be ignored.
left_on – A column name or a list of column names. Column(s) from current SpatialDataFrame used as joining key(s).
right_on – A column name or a list of column names. Column(s) from qry_win SpatialDataFrame paramer, used as joining key(s).
qry_win_out_cols – Specifies the name or a list of names of columns from qry_win that will be included in the returned SpatialDataFrame. If None, the returned SpatialDataFrame only will contain columns from the calling SpatialDataFrame.If the value is ‘*’, the result SpatialDataFrame will contain all the columns from both, the calling SpatialDataFrame and qry_win.

Returns:

A SpatialDataFrame with the combined geometries.

classmethod create(dataset: SpatialDataset)

Creates a SpatialDataFrame instance based on the dataset type.

Parameters:: dataset – A SpatialDataFrame is created bases on the dataset type.

abstract property crs

Return the coordinate reference system associated to the geometry layer.

Returns:: a pyproj.CRS instance or a string.

abstract distance(qry_win, distance_col='DISTANCE', tolerance: float = None, how='inner', on=None, left_on=None, right_on=None, qry_win_out_cols=None)

Get the distance between the geometries from the current SpatialDataFrame and qry_win.

A SpatialDataFrame with the same columns from the source plus the calculated distance is returned along with columns from qry_win specified in qry_win_out_cols.

Parameters:

qry_win – A SpatialDataFrame, GeoDataFrame, GeoSeries or a single shapely geometry.
distance – name of the added distance column.
tolerance – spatial tolerance.
how – Specifies how the join will be performed. Possible values are: ‘inner’ (default), ‘full’, ‘left’ or ‘right’.
on – A column name or a list of column names. Column(s) contained in both SpatialDataFrames which will be used as joining key(s). If this parameter is set, left_on and right_on will be ignored.
left_on – A column name or a list of column names. Column(s) from current SpatialDataFrame used as joining key(s).
right_on – A column name or a list of column names. Column(s) from qry_win SpatialDataFrame paramer, used as joining key(s).
qry_win_out_cols – Specifies the name or a list of names of columns from qry_win that will be included in the returned SpatialDataFrame. If None, the returned SpatialDataFrame only will contain columns from the calling SpatialDataFrame.If the value is ‘*’, the result SpatialDataFrame will contain all the columns from both, the calling SpatialDataFrame and qry_win.

Returns:

a new SpatialDataFrame containing the distance as a new column.

drop(columns)

Return a new SpatialDataFrame without the columns specified by the columns parameter.

Parameters:: columns – column name or list of column names.
Returns:: a SpatialDataFrame without the specified columns.

abstract dropna()

Remove rows containing missing values.

Returns:: A new SpatialDataFrame containing only rows with no missing values.

property dtypes: Python types of the columns of the SpatialDataFrame

abstract filter(qry_win: BaseGeometry, tolerance: float = None)

Executes a primary spatial filter on a SpatialDataFrame. For non-spatially-indexed data, it performs an anyinteract test between the MBR of the geometries and the query window.

Parameters:

qry_win – a shapely geometry.
tolerance – spatial tolerance.

Returns:

a new SpatialDataFrame.

get_values(include_geometry=False)

Return the content of the SpatialDataFrame as numpy array.

Parameters:: include_geometry – If True, content from the geometry column is returned as part of the array.
Returns:: a numpy array.

abstract groupby(by)

Group data by one or more columns. The result can be used to perform aggregations over the grouped data.

The following example groups the SpatialDataFrame data by the zone column, and performs the aggreations mbr over the geoemetry column , and avg on the accidents column.

>>> grouped_proxy = proxy.groupby('zone').aggregate(mbr='geoemetry', avg='accidents')
>>> grouped_proxy.head()
zone   accidents       geometry
200     7.8             POLYGON ((85.87653 27.61234, 85.87355 27.60861...             
301     12.3            POLYGON ((81.75089 28.31038, 81.75562 28.30740...
35      10.5            POLYGON ((83.70647 28.39278, 83.70721 28.38781...

The aggregate function can be used to perform multiple aggregations on various columns, or a specific aggregation functions can be called directly, instead of the aggregate function. When aggregate is used, the aggregations operations and aggregating columns can be specified as follows: aggregate(<aggregation>=’single_column’ | list_of_columns)

Available aggregations:

Spatial Aggregations

Aggregation	Description
mbr	Returns the minimum bounding rectangle of the grouped geometries as a polygon
convexhull	Creates the convex hull polygon from all the geometries in the group
union	Creates a single geometry from all the geometries in the group
centroid	Calculates the centroid from all the geometries in the group

Non-Spatial Aggregations

Aggregation	Description
count	Counts all the non-empty samples in the group
sum	Sums the numerical value of all the samples in the group
avg	Calculates the average of the values of all the samples in the group
min	Gets the minimum value in the group
max	Gets the maximum value in the group

The following example calls the count aggregation and does not specify any column. When no column is specified, the aggregation is performed over all the not grouping columns.

>>> count_all_proxy = proxy.groupby('zone').count()
>>> count_all_proxy.head()
zone    accidents   injured
200     3           1
301     5           2
35      7           3

NOTE: for database-backed SpatialDataFrame, when no spatial aggregations are specified, an instance of oml.DataFrame is returned. For memory-backed SpatialDataFrame, an instance of pandas.DataFrame will be returned when there are no spatial aggregations specified.

If a spatial aggregation is called directly, only the aggregated geometries are returned, as shown in the following example.

>>> only_geom_proxy = proxy.groupby('zone').union()
>>> only_geom_proxy.head()
zone    geometry
200     POLYGON ((85.87653 27.61234, 85.87355 27.60861...             
301     POLYGON ((81.75089 28.31038, 81.75562 28.30740...
35      POLYGON ((83.70647 28.39278, 83.70721 28.38781...

Parameters:: by – A column name or a list of column names from the SpatialDataFrame object.
Returns:: An intermediate object used to perform aggregations.

abstract head(n=5) → GeoDataFrame

Return the first n rows from the referenced data.

Parameters:: n – number of rows
Returns:: a geopandas.GeoDataFrame with n rows.

abstract iterrows(chunk_size: int = None)

Iterates through all the rows of the current instance.

Parameters:: chunk_size – int, default=None

abstract length(tolerance=None, length_col='LENGTH')

Computes the length of each geometry from the current SpatialDataFrame.

Parameters:

tolerance – Spatial tolerance.
length_col – Name of the new column containing length values.

Returns:

A new SpatialDataFrame containing the geometries’ lengths as a new column.

materialize(table=None, schema=None, create_spatial_metadata=True, create_spatial_index=True, if_exists='fail')

Creates a database table with the information of the current SpatialDataFrame. If the SpatialDataFrame’s data comes from memory, it pushes the data to the database. If the SpatialDataFrame’s data is in the database and it is the product of multiple transformations, it creates a table based on all the transformations. This can help on improving the execution time of further transformations. When no table is specified it creates a temporary table, only available during the current session.

Parameters:

table – Name of the database table to be created.
schema – Name of the schema where the table will be created. Only used if table is specified.
create_spatial_metadata – If True, metadata will be added to SDO_GEOM_METADATA.
create_spatial_index – If True, a spatial index will be created for the data.
if_exists – If the value is ‘fail’, parameter table is specified and it already exists, it will fail. When the value is ‘replace’ and the table exists, it will be overwritten.

Returns:

A new SpatialDataFrame that points to a newly created temporary table.

abstract merge(right, how: str = 'inner', on=None, left_on=None, right_on=None, main_geometry_side='left', keep_secondary_geometry=True)

Join two SpatialDataFrame objects by comparing the given joining keys. The resulting SpatialDataFrame object will contain columns from both sides.

Parameters:

right – A SpatialDataFrame, pandas.DataFrame or oml.DataFrame used as the join right-hand side.
how – Specifies how the join will be performed. Possible values are: ‘inner’ (default), ‘full’, ‘left’ or ‘right’.
on – A column name or a list of column names. Column(s) contained in both SpatialDataFrames which will be used as joining key(s). If this parameter is set, left_on and right_on will be ignored.
left_on – A column name or a list of column names. Column(s) from current SpatialDataFrame used as joining key(s).
right_on – A column name or a list of column names. Column(s) from right SpatialDataFrame paramer, used as joining key(s).
main_geometry_side – Possible values are ‘left’ (default) or ‘right’. Specifies which geometry will be used as the resulting SpatialDataFrame main geometry column.
keep_secondary_geometry – If True (default), the geometry column from the side that was not set as the main geometry, will appear on the resulting SpatialDataFrame object but will not be used to perform spatial operations.

abstract merge_oml_dataframe(oml_df, on=None, left_on=None, right_on=None, keep_on_side='left', how='inner')

Merge the current SpatialDataFrame with an existing oml.DataFrame based on a key. The result is a SpatialDataFrame containing the records that matched the condition.

Parameters:

oml_df – An instance of oml.DataFrame
on – A column that is present in both, the SpatialDataFrame and the oml.DataFrame, which will be used to join both datasets.
left_on – Column present in the SpatialDataFrame used as joining key.
left_on – Column present in the oml.DataFrame used as joining key.
keep_on_side – If left_on and right_on have different names, it specifies which joining key will be kept in the result.
how – Type of join. Possible valures: inner, left, right.

Returns:

A SpatialDataFrame

abstract nearest_neighbors(qry_win, num_neighbors=None, distance_col=None, qry_win_out_cols=None)

Returns a SpatialDataFrame containing records which are closer to a given location specified as a shapely geometry or another SpatialDataFrame.

If num_neighbors parameter is specified, only num_neighbors will be returned for the query window.

Optionally, the distance to each nearest neighbors can be included by specifying the name of the column with distance_col parameter.

If a SpatialDataFrame is specified instead of a shapely geometry, the resulting SpatialDataFrame will contain records where each record is composed of information from both input SpatialDataFrames, that is, the nearest neighbor and the base geometry for which the nearest neighbors are looked.

Parameters:

qry_win – a shapely geometry or another SpatialDataFrame.
num_neighbors – number of nearest neighbors.
distance_col – name of distance column to be generated.
qry_win_out_cols – Specifies the name or a list of names of columns from qry_win that will be included in the returned SpatialDataFrame. If None, the returned SpatialDataFrame only will contain columns from the calling SpatialDataFrame. If the value is ‘*’, the result SpatialDataFrame will contain all the columns from both, the calling SpatialDataFrame and qry_win.

Returns:

a new SpatialDataFrame.

plot(**plot_geometries_extra_kwargs)

Plot a SpatialDataFrame using matplolib. Calling this method causes the SpatialDataFrame’s data to be fetched to the client.

This method is a shorthand for oraclesai.vis.plot_geometries().

Parameters:

**plot_geometries_extra_kwargs –

The paremeters accepted by oraclesai.vis.plot_geometries(), except for the data parameter.

abstract relate(qry_win: BaseGeometry | SpatialDataFrame, mask: SpatialFilterMask = SpatialFilterMask.ANY_INTERACT, tolerance: float = None, qry_win_out_cols=None)

Perform spatial filtering using the specified spatial operator.

A spatial join can be performed when qry_win is a SpatialDataFrame instance. Columns from qry_win can be included in the resulting SpatialDataFrame by passing the names of the columns using the parameter qry_win_out_cols. The following example performs a spatial join and returns a SpatialDataFrame containing all the columns from the calling SpatialDataFrame and one column from qry_win.

>>> sdf1.head(2)
      ID             geometry
0     23432          POLYGON ((85.87653 27.61234, 85.87355 27.60861...             
1     45465          POLYGON ((81.75089 28.31038, 81.75562 28.30740...
>>> sdf2.head(2)
      NAME           geometry
0     G0134          POLYGON ((84.56565 34.445454, 84.3434 27.88788...             
1     K0454          POLYGON ((83.70647 28.39278, 83.70721 28.38781...
>>> joined_sdf = sdf1.relate(qry_win=sdf2, mask=SpatialFilterMask.ANY_INTERACT, qry_win_out_cols=['NAME'])
>>> joined_sdf.head(2)
      ID      NAME       geometry
0     23432   J095       POLYGON ((85.87653 27.61234, 85.87355 27.60861...             
1     45465   G043       POLYGON ((81.75089 28.31038, 81.75562 28.30740...

Parameters:

qry_win – a shapely geometry or a SpatialDataFrame.
mask – the spatial operator, a value from oraclesai.SpatialFilterMask.
tolerance – tolerance used.
qry_win_out_cols – Specifies the name or a list of names of columns from qry_win that will be included in the returned SpatialDataFrame. If None, the returned SpatialDataFrame only will contain columns from the calling SpatialDataFrame. If the value is ‘*’, the result SpatialDataFrame will contain all the columns from both, the calling SpatialDataFrame and qry_win.

Returns:

a new SpatialDataFrame.

rename_columns(): Rename the column names specified by column_map. For example, raname columns ZIP and ADDR to ZIPCODE and ADDRESS: sdf = sdf.rename_columns({‘ZIP’: ‘zipcode’, ‘ADDR’: ‘ADDRESS’}) :returns: A new SpatialDataFrame with renamed columns.

abstract property shape: Tuple[int, int]

Dimensionality of the SpatialDataFrame.

Returns:: number of rows and columns.

abstract sort_values(by, ascending=True)

Returns a SpatialDataFrame sorted by the values of the columns specified.

Parameters:

by – One column name or a list of column names
ascending – If True, values will be sorted in ascending way

abstract split(ratio=(0.7, 0.3), seed=12345, use_hash=True)

Splits the SpatialDataFrame randomly into multiple subsets

Parameters:

ratio – A list or tuple of values that specify the size of each subset as a percentage of the full data set size.
seed – Seed used for random splitting.
use_hash – If True, hashing is used to randomly plit the data, otherwise, a value number is used.

Returns:

A list of SpatialDataFrame instances where each instance correspondos to one value of the ratio list.

abstract tail(n=5) → GeoDataFrame

Return the last n rows from the referenced data.

Parameters:: n – number of rows
Returns:: a geopandas.GeoDataFrame with n rows.

abstract to_crs(crs) → SpatialDataFrame

Return a new SpatialDataFrame containing the geometries in the specified CRS.

Parameters:: crs – Any input accepted by pyproj.CRS.from_user_input function.

abstract property total_bounds

Calculate the minimum bounding rectangle enclosing all the data.

Returns:: a tuple of floats with the following elements (min_x, min_y, max_x, max_y)

abstract within_distance(qry_win, distance: float, tolerance: float = None, qry_win_out_cols=None)

Returns a SpatialDataFrame containing only records which are within a certain distance from a query window specified as a shapely query window or another SpatialDataFrame.

Parameters:

qry_win – a SpatialDataFrame or a shapely geometry.
distance – maximum distance to qry_win.
tolerance – spatial tolerance.
qry_win_out_cols – Specifies the name or a list of names of columns from qry_win that will be included in the returned SpatialDataFrame. If None, the returned SpatialDataFrame only will contain columns from the calling SpatialDataFrame. If the value is ‘*’, the result SpatialDataFrame will contain all the columns from both, the calling SpatialDataFrame and qry_win.

Returns:

a new SpatialDataFrame.

abstract write(dataset, if_exists='fail', create_spatial_metadata=False, create_spatial_index=False)

Writes the current SpatialDataFrame data into the destination specified by the dataset argument.

Parameters:

dataset – An instance of oraclesai._data.SpatialDataset. It describes how the data will be stored.
if_exists – Defines what happens if the resulting dataset already exists. Possible values are: ‘fail’, ‘replace’.
create_spatial_metadata – True if spatial metadata needs to be created. Only used for Oracle database datasets.
create_spatial_index – True if a spatial index needs to be created. Only used for Oracle database datasets.

class SpatialDataset: A generic dataset of vector data.

exception SpatialError(code, message=None, cause=None, action=None)

Common error class used across the Spatial AI API.

Parameters:: code – A numerical code indicating the error type.

class SpatialFilterMask(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Definitions of spatial interactions used in different spatial operations.

ANY_INTERACT = 'anyinteract': This interaction is true if either the boundary or interior of a data geometry intersects with the boundary or interior of the query window. In other words, if there is any intersection between the two geometries.

CONTAINS = 'contains': This holds if the boundary and interior of the query window are inside the interior of a data geometry. This relationship is the reverse of INSIDE.

COVERED_BY = 'coveredby': A data geometry is COVEREDBY the query window if the interior and boundary of a data geometry are inside the interior of the query window, except that the boundaries overlap.

COVERS = 'covers': This interaction is true if the interior and boundary of the query window is inside the interior of a data geometry and the boundaries overlap. This is the reverse of COVEREDBY.

EQUAL = 'equal': This holds if the interior and boundary of a data geometry exactly match those of the query window.

INSIDE = 'inside': This interaction holds if the boundary and interior of a data geometry are inside the interior of the query window.

ON = 'on': The interior and boundaries of a data geometry interact exclusively with the boundary of the query window.

OVERLAP_BDY_DISJOINT = 'overlapbdydisjoint': This holds if the interior of one intersects the interior and boundary of the other, but the two boundaries do not intersect.

OVERLAP_BDY_INTERSECT = 'overlapbdyintersect': This holds if the boundaries and interiors of a data geometry and the query window intersect.

TOUCH = 'touch': This holds if the boundaries of two geometries touch, but the interiors do not intersect.

push(gdf, create_spatial_index=True)

Pushes a geopandas.GeodataFrame into Oracle Database. Creates an internal table in Oracle Database and inserts the data into the table. The table exists as long as a SpatialDataFrame in the Python client references the table.

Parameters:

gdf – A class::geopandas.GeodataFrame.
create_spatial_index – If True, creates a spatial index in Oracle Database.

Returns:

A new oraclesai.SpatialDataFrame:

read(dataset: SpatialDataset) → GeoDataFrame

Load the given dataset reference into a geopandas GeoDataFrame object.

Parameters:: dataset – An instance of SpatialDataset. It specifies the name and source of the dataset to be loaded.
Returns:: a geopandas GeoDataFrame.

write(gdf: GeoDataFrame, dataset: SpatialDataset, include_index=False, if_exists='fail', create_spatial_metadata=True, create_spatial_index=False)

Write the content from an existing GeoDataFrame to the destination defined by the dataset parameter.

Parameters:

gdf – a geopandas GeoDataFrame
dataset – an instance of SpatialDataset. Depending on the specific implementation of this parameter, the geodataframe will be stored as a file in a local file system, object storage or as a table in Oracle database.
include_index – If True, the GeoDataFrame index column(s) will be written.
if_exists – A string value that specifies the action when the dataset already exists. Possible values are: fail, replace, and append. Default value is fail. Value append only is used in database datasets.
create_spatial_metadata – If True and the dataset is a database table, geometry metadata info will be created.
create_spatial_index – If true and the dataset is a database table, a spatial index will be created for the GeoDataFrame geometry.