database module

The apsg.database module provides an SQLAlchemy interface to the PySDB database format. PySDB is a simple sqlite3-based relational database for storing structural geology field data. The module supports creating and querying databases with units, sites, structural types, and measurements. You can also use the standalone GUI application pysdb or the QGIS plugin readsdb for map-based visualization.

Usage

Create a new database and add data:

>>> from apsg.database import SDBSession
>>> db = SDBSession('database.sdb', create=True)
>>> unit = db.unit('DMU', description='Deamonic Magmatic Unit')
>>> site = db.site('LX001', unit=unit, x_coord=25934.36, y_coord=564122.5, description='diorite dyke')
>>> S2 = db.structype('S2', description='Solid-state foliation', planar=1)
>>> L2 = db.structype('L2', description='Solid-state lineation', planar=0)
>>> fol = db.add_structdata(site, S2, 150, 36)
>>> lin = db.add_structdata(site, L2, 83, 16)
>>> db.commit()
>>> db.close()

Add tags and attach linear to planar data:

>>> db = SDBSession('database.sdb')
>>> site = db.site('LX001')
>>> tag = db.tag('plot', description='to be plotted')
>>> fol = db.add_structdata(site, S2, 324, 78, tags=[tag])
>>> lin = db.add_structdata(site, L2, 212, 26)
>>> pair = db.attach(fol, lin)
>>> db.commit()
>>> db.close()

Insert Foliation, Lineation or Pair objects directly:

>>> from apsg.feature import Foliation, Lineation, Pair
>>> db = SDBSession('database.sdb')
>>> site = db.site('LX001')
>>> S2 = db.structype('S2')
>>> L2 = db.structype('L2')
>>> f = Foliation(196, 39)
>>> l = Lineation(210, 37)
>>> db.add_fol(site, S2, f)
>>> db.add_lin(site, L2, l)
>>> p = Pair(258, 42, 220, 30)           # dip direction, dip, trend, plunge
>>> db.add_pair(site, S2, L2, p)
>>> db.commit()
>>> db.close()

Retrieve data as APSG feature sets:

>>> db = SDBSession('database.sdb')
>>> g = db.getset('S2')
>>> type(g).__name__
'FoliationSet'

Classes:

`SDBSession`(sdb_file, **kwargs)	SqlAlchemy interface to PySDB database
`Meta`(**kwargs)	SQLAlchemy model for database metadata key-value pairs.
`Site`(**kwargs)	SQLAlchemy model for geological sampling sites.
`Structdata`(**kwargs)	SQLAlchemy model for structural attitude measurements.
`Structype`(**kwargs)	SQLAlchemy model for structure type definitions.
`Attached`(**kwargs)	SQLAlchemy model linking planar and linear structural data.
`Tag`(**kwargs)	SQLAlchemy model for tagging structural data.
`Unit`(**kwargs)	SQLAlchemy model for geological units.

class apsg.database.SDBSession(sdb_file, **kwargs)

Bases: object

SqlAlchemy interface to PySDB database

Parameters:

sdbfile (str) – filename of PySDB database

Keyword Arguments:

create (bool) – if True existing sdbfile will be deleted and new database will be created
autocommit (bool) – if True, each operation is autocommitted. Default False

Examples

>>> db = SDBSession('database.sdb', create=True)

add(obj): Add to session.

add_all(list_obj): Add all to session.

add_fol(site, structype, fol, **kwargs)

Add Foliation to site

Parameters:

site (Site) – Site instance
structype (Structype) – Structype instance
fol (Foliation) – Foliation instance

Keyword Arguments:

description (str) – structdata description

Returns:

Structdata

add_lin(site, structype, lin, **kwargs)

Add Lineation to site

Parameters:

site (Site) – Site instance
structype (Structype) – Structype instance
lin (Lineation) – Lineation instance

Keyword Arguments:

description (str) – structdata description

Returns:

Structdata

add_pair(site, foltype, lintype, pair, **kwargs)

Add attached foliation and lineation to database. Note that measurements of foliation and lineation are corrected.

Parameters:

site (Site) – site instance
foltype (Structype) – structype instance
lintype (Structype) – structype instance
pair (Pair) – Pair instance

Returns:

Attached

add_structdata(site, structype, azimuth, inclination, **kwargs)

Add structural measurement to site

Parameters:

site (Site) – Site instance
structype (Structype) – Structype instance
azimuth (float) – dip direction or plunge direction
inclination (float) – dip or plunge

Keyword Arguments:

description (str) – structdata description

Returns:

Structdata

attach(planar, linear)

Attach Foliation to Lineation

Parameters:

planar (Structdata) – planar Structdata
linear (Structdata) – linear Structdata

Returns:

Attached

close(): Close session

commit(): Commit session.

df(structype, **kwargs)

Method to retrieve data from SDB database as pandas.DataFrame.

Parameters:

structype (str | Structype) – structure to retrieve.
site (dict) – keyword args passed to filter site.
unit (dict) – keyword args passed to filter unit.
tag (dict) – keyword args passed to filter tag.
store (list) – list of properties to be included in dataframe. Available values:”id”, “x_coord”, “y_coord”, “site”, “unit”, “tags” or “geo”. Default [].
expand_tags (bool) – If True tags are one hot encoded. Default False.
apsg (bool) – If True structural data are added as APSG features. Default False.

Examples

>> df = db.df(“S2”) >> df = db.df(“S2”, unit=dict(name=”Main unit”)) >> df = db.df(“S2”, tag=dict(name=”AP”))

getfaults(ptype, ltype, sense, site={}, unit={}, ptag={}, ltag={})

Method to retrieve data from SDB database to FaultSet.

Parameters:

ptype (str | Structype) – planar structure to retrieve.
ltype (str | Structype) – linear structure to retrieve.
sense (float or str) – sense of movement +/-1 hanging-wall down/up. When str, must be one of ‘s’, ‘d’, ‘n’, ‘r’.

Keyword Arguments:

site (dict) – keyword args passed to filter site.
unit (dict) – keyword args passed to filter unit.
ptag (dict) – keyword args passed to filter planar tag.
ltag (dict) – keyword args passed to filter linear tag.

getpairs(ptype, ltype, site={}, unit={}, ptag={}, ltag={})

Method to retrieve data from SDB database to PairSet.

Parameters:

ptype (str | Structype) – planar structure to retrieve.
ltype (str | Structype) – linear structure to retrieve.

Keyword Arguments:

site (dict) – keyword args passed to filter site.
unit (dict) – keyword args passed to filter unit.
ptag (dict) – keyword args passed to filter planar tag.
ltag (dict) – keyword args passed to filter linear tag.

getset(structype, **kwargs)

Method to retrieve data from SDB database to FeatureSet.

Parameters:

structype (str | Structype) – structure to retrieve.
site (dict) – keyword args passed to filter site.
unit (dict) – keyword args passed to filter unit.
tag (dict) – keyword args passed to filter tag.
store (list) – list of properties to be stored in feature as _attrs. Available values:”id”, “x_coord”, “y_coord”, “site”, “unit”, “tags” or “geo”. Default [].

Examples

>> g = db.getset(“S2”) >> g = db.getset(“S2”, unit=dict(name=”Main unit”)) >> g = db.getset(“S2”, tag=dict(name=”AP”))

meta(name, **kwargs)

Query Meta when no kwargs or insert/update when kwargs provided.

Parameters:: name (str) – meta name
Keyword Arguments:: value (str) – meta value
Returns:: Meta

remove_structype(structure, **kwargs)

Remove Structype

Note: When assign is None associated data are removed

Parameters:: structure (str) – structure of structype to be removed
Keyword Arguments:: assign (str) – Structype to be assigned to data

remove_unit(name, **kwargs)

Remove Unit

Note: When assign is None associated sites are removed

Parameters:: name (str) – name of unit to be removed
Keyword Arguments:: assign (str) – Structype to be assigned to data

rollback(): Rollback session.

site(name, **kwargs)

Query Site when no kwargs or insert/update when kwargs provided.

Parameters:

name (str) – site name

Keyword Arguments:

x_coord (float) – x coord or longitude
y_coord (float) – y coord or latitude
description (str) – site description
unit (Unit) – unit instance (must be provided)

Returns:

Site

sites(): Returns list of all Site instances.

structdata(structype)

Returns list of all Structdata instances of given structype.

Parameters:: structype (str | Structype) – structure to retrieve.

structype(structure, **kwargs)

Query Structype when no kwargs or insert/update when kwargs provided.

Parameters:

structure (str) – label used for structure

Keyword Arguments:

description (str) – Structype description
planar (int) – 1 for planar 0 for linear Structype
structcode (int) – structcode (optional)
groupcode (int) – groupcode (optional)

Returns:

Structype

structypes(planar=None)

Returns list of Structype instances.

Keyword Arguments:: planar (int) – 0 for linear, 1 for planar, None for all. Default None

tag(name, **kwargs)

Query Tag when no kwargs or insert/update when kwargs provided.

Parameters:: name (str) – tag name
Keyword Arguments:: description (str) – tag description
Returns:: Tag

tags(): Returns list of all Tag instances.

unit(name, **kwargs)

Query Unit when no kwargs or insert/update when kwargs provided.

Parameters:: name (str) – unit name
Keyword Arguments:: description (str) – unit description
Returns:: Unit

units(**kwargs): Returns list of all Unit instances.

class apsg.database.Meta(**kwargs)

Bases: Base

SQLAlchemy model for database metadata key-value pairs.

class apsg.database.Site(**kwargs)

Bases: Base

SQLAlchemy model for geological sampling sites.

class apsg.database.Structdata(**kwargs)

Bases: Base

SQLAlchemy model for structural attitude measurements.

class apsg.database.Structype(**kwargs)

Bases: Base

SQLAlchemy model for structure type definitions.

class apsg.database.Attached(**kwargs)

Bases: Base

SQLAlchemy model linking planar and linear structural data.

class apsg.database.Tag(**kwargs)

Bases: Base

SQLAlchemy model for tagging structural data.

class apsg.database.Unit(**kwargs)

Bases: Base

SQLAlchemy model for geological units.