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