Database and setup

The underlaying database schema looks something like:

------------------------------------          -------------------------
|  events:                         |          |  frames:              |
------------------------------------          -------------------------
|   * id       (autoincrement)     |<--|    |-|-* run     PrimaryKey  |
| -------------------------------- |   |    |-|-* camcol  PrimaryKey  |
| |           frame              | |   |    |-|-* filter  PrimaryKey  |
| | * _run     ForeignKey(frames)|-|---|--->|-|-* field   PrimaryKey  |
| | * _camcol  ForeignKey(frames)| |   |      | * crpix1  Float       |
| | * _filter  ForeignKey(frames)| |   |      | * crpix2  Float       |
| | * _field   ForeignKey(frames)| |   |      | * crval1  Float       |
| -------------------------------- |   |      | * crval2  Float       |
| |         Point p1             | |   |      | * cd11    Float       |
| | * _x1, _cx1   Float          | |   |      | * cd12    Float       |
| | * _y1, _cy1   Float          | |   |      | * cd21    Float       |
| -------------------------------- |   |      | * cd22    Float       |
| |         Point p2             | |   |      | * t       BasicTime   |
| | * _x2, _cx2   Float          | |   |      | ------------          |
| | * _y2, _cy2   Float          | |   |------|-|  events  |          |
| -------------------------------- |          | ------------          |
| |         LineTime lt          | |          |                       |
| | * start_t  Float             | |          |                       |
| | * end_t    Float             | |          |                       |
| -------------------------------- |          |                       |
------------------------------------          -------------------------

Event describes the occurence of a single line on a Frame. A Frame is the SDSS frame on which at least one Event (linear feature) was registered. If no Event is associated to a particular Frame, that Frame should be removed from the DB.

No event can exist without an being associated toa Frame. This constitutes a One-To-Many relationship from Frames to Events and Many-To-One in reverse:

Events ->|------- Frame
Frame  -|------<- Events

The awkward notation of the tables reflects the ORM aspects of the DB. Many of the attributes of the first table are marked with an underscore and I would advise not to access them directly. Even though a lot of effort has been put into assuring consistency of data no matter what is done to it, dealing directly with the values assumed understanding of the SDSS’ CCD layout and usually comes with a loss of functionaity.

Instead many wrappers (i.e. Point, BasicTime etc.) are offered around those attributes that expand on their functionality and ensure data consistency.

Relationships ‘frame’ and ‘events’ can be accessed as attributes of the class. This allows for simpler, more object oriented access to immediatelly related objects.

Point is another special SQLAlchemy construct, a mutable composite. Point class ensures data consistency in an interactive session while managing coordinate transformations between multiple coordinate systems.

The SQL type BasicTime was implemented to allow for more powerful astronomy focused date and time management. It is essentially the SDSS modified TAI time stamp stored as a Float value in the DB but wrapped in Astropy’s Time object.

By default, SQL database that will be used is SQLite but this is not mandatory. Other DBs can be used in its stead, preferentially ones that enforce referential integrity to avoid loss of consistency.

Todo

MetaEvent - when an object passes over the entire CCD array it creates a lot of Events, but is still the same object. A MetaEvent table linking multiple Events into a singular object is still required.

Connecting to the DB

The tables and metadata are registered on import. Connecting to the Db and acquiring an engine, session and connection is done similarly to how setup of detecttrails module works. All three are availible as module global variables, but it is recommended that context managers found in utilities module are used.

1
2
import lfd
lfd.setup_results(URI="sqlite:///", dbpath="~/Desktop", name="foo.db", echo=False)

Again, as before this functionality is replciated and accessible from the module itself as well.

1
2
from lfd import results
results.connect2db(uri="sqlite:////home/user/Desktop/bar.db", echo=False)

If the DB at the desired URI does not exists a new empty DB is created and connected to instead. By default the connection is attempted to URI: sqlite:////home/$USER/Desktop/foo.db. Additionally if the used DB is SQLite, PRAGMA FOREIGN_KEYS is set to ON and echo is set to False.

If this is not flexible enough a DB can be created manually and the package’s engine and session, availible as attributes of results module, can be set to the engine and session created with that DB directly.

lfd.setup_results(URI='sqlite:///', dbpath='~/Desktop', name='foo.db', echo=False)[source]

Either connects to an existing DB (that has to be mappable by results package) or creates a new empty DB with the required tables.

Parameters:
  • URI (str) – an URI to the DB. Defaults to ‘sqlite:///$USER_HOME/food.db’.
  • dbpath (str) – location of a directory with an existing DB, or a directory where a new DB will be created. Set to ‘~’ by default.
  • name (str) – name of the existing, or newly created, DB. Default: ‘foo.db’
  • echo (bool) – verbosity, Frue by default.
lfd.results.connect2db(uri, echo=False)[source]

Connects to an existing DB or creates a new empty DB to connect too. The DB has to be mappable by the results package.

Parameters:
  • URI (an URI used to connect to a DB. By default set to:) – ‘sqlite:///$USER_HOME/foo.db’.
  • name (the name of the existing, or newly created, DB. Default: 'foo.db') –
  • echo (verbosity of the DB. False by default.) –