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)
`Site`(**kwargs)
`Structdata`(**kwargs)
`Structype`(**kwargs)
`Attached`(**kwargs)
`Tag`(**kwargs)
`Unit`(**kwargs)
`SDB`(sdb_file)	sqlite3 based read-only interface to PySDB database

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

Example

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

add(obj): add to session

add_all(list_obj): add 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.

Example

>> 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 []

Example

>> 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

class apsg.database.Site(**kwargs): Bases: Base

class apsg.database.Structdata(**kwargs): Bases: Base

class apsg.database.Structype(**kwargs): Bases: Base

class apsg.database.Attached(**kwargs): Bases: Base

class apsg.database.Tag(**kwargs): Bases: Base

class apsg.database.Unit(**kwargs): Bases: Base

class apsg.database.SDB(sdb_file)

Bases: object

sqlite3 based read-only interface to PySDB database

Parameters:: sdbfile (str) – filename of PySDB database

Example

>>> db = SDB('database.sdb')

getset(structs, **kwargs)

Method to retrieve data from SDB database to FeatureSet.

Parameters:

structs (str) – structure or list of structures to retrieve

Keyword Arguments:

sites (str) – name or list of names of sites to retrieve from
units (str) – name or list of names of units to retrieve from
tags (str) – tag or list of tags to retrieve
labels (bool) – if True return also list of sites. Default False

info(report='basic')

PySDB database report

Parameters:: report (str) – type of report. basic, data or tags. Default basic

sites(**kwargs)

Return list of sites in database.

For kwargs see getset method.

structures(**kwargs)

Return list of structures in database.

For kwargs see getset method

tags(**kwargs)

Return list of tags in database.

For kwargs see getset method.

units(**kwargs)

Return list of units in database.

For kwargs see getset method.