Spells¶

Spells are primitives that you can use for engineering features. They are first instantiated, and then casted on a DataFrame of points.

geomancer.spells.base¶

Base class for all feature or spell implementations

In Geomancer, all feature transform primitives are of the class Spell. When defining your own feature primitive, simply create a class that inherits from Spell:

from geomancer.spells.base import Spell
class MyNewFeature(Spell):
     def __init__(self):
         super(MyNewFeature, self).__init__()

All methods must be implemented in order to not raise a NotImplementedError.

class geomancer.spells.base.Spell(source_table, feature_name, source_id='osm_id', dburl=None, options=None)[source]¶

Bases: abc.ABC

Base class for all feature/spell implementations

__init__(source_table, feature_name, source_id='osm_id', dburl=None, options=None)[source]¶

Spell constructor

Parameters:	source_table (str) – Table URI to run queries against. feature_name (str) – Column name for the output feature. dburl (str, optional) – Database url used to configure backend connection options (`geomancer.backend.settings.Config`, optional) – Specify configuration for interacting with the database backend. Auto-detected if not set.

cast(target, dburl=None, column='WKT', keep_index=False, features_only=False, pkey='__index_level_0__')[source]¶

Apply the feature transform to an input pandas.DataFrame

Parameters:	target (`pandas.DataFrame` or str) – Object containing the points to compare upon. Can be a DataFrame or a database URL. By default, we will look into the `WKT` column. You can specify your own column by passing an argument to the `column` parameter. dburl (str, optional) – Database url used to configure backend connection column (str, optional) – Column to look the geometries from. The default is `WKT` keep_index (boolean, optional) – Include index in output dataframe features_only (boolean, optional) – Only return features as output dataframe. Automatically sets `keep_index` to `True`. pkey (str, optional) – The primary key column in the database. Default is __index_level_0__. This is useful if the table you’re passing `cast` to is a database URL rather than a dataframe.
Returns:	Output dataframe with the features per given point
Return type:	`pandas.DataFrame`

extract_columns(x)[source]¶

Extract column and filter from a string input

Parameters:	x (str) – The column and filter pair in the form `column:filter`
Returns:	The extracted column and filter pair
Return type:	(str, str)

get_core(dburl)[source]¶

Instantiates an appropriate core based on given database url

Parameters:	dburl (str) – Database url used to configure backend connection
Returns:	core – DBCore instance to access DB-specific methods
Return type:	`geomancer.backend.cores.DBCore`

query(source, target, core, column, pkey)[source]¶

Build the query used to extract features

Parameters:	source (`sqlalchemy.schema.Table`) – Source table to extract features from. target (`sqlalchemy.schema.Table`) – Target table to add features to. core (`geomancer.backend.cores.base.DBCore`) – DBCore instance to access DB-specific methods column (string) – Column to look the geometries from. The default is `WKT` pkey (str, optional) – The primary key column in the database. Default is __index_level_0__. This is useful if the table you’re passing `cast` to is a database URL rather than a dataframe.
Returns:	The statement to query features with.
Return type:	`sqlalchemy.sql.expression.ClauseElement`
Raises:	`NotImplementedError` – This is an abstract method

geomancer.spells.distance_to_nearest¶

Spell DistanceToNearest obtains the distance to the nearest Point-of-Interest or geographic feature. Suppose you want to find the distance to the nearest embassy:

from geomancer.spells import DistanceToNearest
from tests.conftest import sample_points

# Load sample points
df = sample_points()

# Configure and cast the spell
spell = DistanceToNearest("embassy",
                           source_table="geospatial.ph_osm.gis_osm_pois_free_1",
                           feature_name="dist_embassy")

# Will create a new column, `dist_embassy` with the
# appropriate features
df_with_features = spell.cast(df, dburl="bigquery://geospatial")

class geomancer.spells.distance_to_nearest.DistanceToNearest(on, within=10000, **kwargs)[source]¶

Bases: geomancer.spells.base.Spell

Obtain the distance to the nearest Point-of-Interest or geographic feature

__init__(on, within=10000, **kwargs)[source]¶

Spell constructor

Parameters:

on (str) – Feature class to compare upon
within (float, optional) – Look for values within a particular range. Its value is in meters, the default is 10,000 meters.
source_table (str) – Table URI to run queries against.
feature_name (str) – Column name for the output feature.
column (str, optional) – Column to look the geometries from. The default is WKT
options (geomancer.backend.settings.Config, optional) – Specify configuration for interacting with the database backend. Auto-detected if not set.

query(source, target, core, column, pkey)[source]¶

Build the query used to extract features

Parameters:	source (`sqlalchemy.schema.Table`) – Source table to extract features from. target (`sqlalchemy.schema.Table`) – Target table to add features to. core (`geomancer.backend.cores.base.DBCore`) – DBCore instance to access DB-specific methods column (string) – Column to look the geometries from. The default is `WKT` pkey (str, optional) – The primary key column in the database. Default is __index_level_0__. This is useful if the table you’re passing `cast` to is a database URL rather than a dataframe.
Returns:	The statement to query features with.
Return type:	`sqlalchemy.sql.expression.ClauseElement`
Raises:	`NotImplementedError` – This is an abstract method

geomancer.spells.number_of¶

Spell NumberOf obtains the number of Points-of-Interests or geographic features within a particular range. Suppose you want to find the number of supermarkets given a set of points

from geomancer.spells import NumberOf
from tests.conftest import sample_points

# Load sample points
df = sample_points()

# Configure and cast the spell
spell = NumberOf("supermarket",
                  source_table="geospatial.ph_osm.gis_osm_pois_free_1",
                  feature_name="num_supermarket")

# Will create a new column, `num_supermarket` with the
# appropriate features
df_with_features = spell.cast(df, dburl="bigquery://geospatial")

class geomancer.spells.number_of.NumberOf(on, within=10000, **kwargs)[source]¶

Bases: geomancer.spells.base.Spell

Obtain the number of nearest Point-of-Interests or geographic features

__init__(on, within=10000, **kwargs)[source]¶

Spell constructor

Parameters:

on (str) – Feature class to compare upon
within (float, optional) – Look for values within a particular range. Its value is in meters, the default is 10,000 meters.
source_table (str) – Table URI to run queries against.
feature_name (str) – Column name for the output feature.
column (str, optional) – Column to look the geometries from. The default is WKT
options (geomancer.backend.settings.Config, optional) – Specify configuration for interacting with the database backend. Auto-detected if not set.

query(source, target, core, column, pkey)[source]¶

Build the query used to extract features

Parameters:	source (`sqlalchemy.schema.Table`) – Source table to extract features from. target (`sqlalchemy.schema.Table`) – Target table to add features to. core (`geomancer.backend.cores.base.DBCore`) – DBCore instance to access DB-specific methods column (string) – Column to look the geometries from. The default is `WKT` pkey (str, optional) – The primary key column in the database. Default is __index_level_0__. This is useful if the table you’re passing `cast` to is a database URL rather than a dataframe.
Returns:	The statement to query features with.
Return type:	`sqlalchemy.sql.expression.ClauseElement`
Raises:	`NotImplementedError` – This is an abstract method

geomancer.spells.length_of¶

Spell LengthOf obtains the length of all Lines-of-Interest with a certain radius. Suppose you want to find the length of residential roads given a set of points:

from geomancer.spells import LengthOf
from tests.conftest import sample_points

# Load sample points
df = sample_points()

# Configure and cast the spell
spell = LengthOf("residential",
                  source_table="geospatial.ph_osm.gis_osm_roads_free_1",
                  feature_name="len_residential")

# Will create a new column, `len_residential` with the
# appropriate features
df_with_features = spell.cast(df, dburl="bigquery://geospatial")

Warning

This spell currently doesn’t work in BigQuery. In addition, the runtime for casting this spell is slow.

class geomancer.spells.length_of.LengthOf(on, within=10000, **kwargs)[source]¶

Bases: geomancer.spells.base.Spell

Obtain the length of all Lines-of-Interest within a certain radius

__init__(on, within=10000, **kwargs)[source]¶

Spell constructor

Parameters:

on (str) – Feature class to compare upon
within (float, optional) – Look for values within a particular range. Its value is in meters, the default is 10,000 meters.
source_table (str) – Table URI to run queries against.
feature_name (str) – Column name for the output feature.
column (str, optional) – Column to look the geometries from. The default is WKT
options (geomancer.backend.settings.Config) – Specify configuration for interacting with the database backend. Default is a BigQuery Configuration

query(source, target, core, column, pkey)[source]¶

Build the query used to extract features

Parameters:	source (`sqlalchemy.schema.Table`) – Source table to extract features from. target (`sqlalchemy.schema.Table`) – Target table to add features to. core (`geomancer.backend.cores.base.DBCore`) – DBCore instance to access DB-specific methods column (string) – Column to look the geometries from. The default is `WKT` pkey (str, optional) – The primary key column in the database. Default is __index_level_0__. This is useful if the table you’re passing `cast` to is a database URL rather than a dataframe.
Returns:	The statement to query features with.
Return type:	`sqlalchemy.sql.expression.ClauseElement`
Raises:	`NotImplementedError` – This is an abstract method