...

• DBObject – This class will create a connection to a database file, however, it .  It leaves the querying of that database to the user.  This is the class to use if you want to write your own SQL queries by hand.  This is not the class to use if you are expecting to interface your database with the InstanceCatalog class to produce a CatSim-generated catalog.
• CatalogDBObject – This class provides all the functionality of DBObject while adding the ability to automatically generate SQL queries based on just a list of column names.  This is the class used by InstanceCatalog to create catalogs from databases.  CatalogDBObject also provides functionality that allows the user to map columns from an arbitrary database file into a format that InstanceCatalog expect.
• fileDBObject – This class provides the ability to read in a text file and then map it to a CatalogDBObject and either connect that to an InstanceCatalog or output it as a database file for future use.

...

The DBObject class is the most basic way of interfacing with a database.  It is designed to connect to a database and allow the user to execute arbitrary queries (written in SQL) from on any table or tables in the database.

...

CatalogDBObject is a daughter class of DBObject (meaning that CatalogDBObjects have access to all of the functionality of DBObjects).  It is designed specifically to connect databases with InstanceCatalogs (a class defined in /python/lsst/sims/catalogs/measures/instance/InstanceCatalog.py in sims_catalogs_measures).  In addition to the functionality of DBObject, CatalogDBObject contains functionality that allows it to take a list of pre-defined columns or column transformations (specified in the InstanceCatalog) and return an SQL query on those columns.  This is the functionality defined in the CatalogDBObjects section of the framework overview page.

CatalogDBObjects contain CatalogDBObject contains several member variables that are used to perform InstanceCatalog-based queries:

• epoch is a double that defines the epoch against which astrometric quantities are calculated (i.e. the epoch of the equinoxes equinox being used)

• objid is a string uniquely identifying each daughter class of CatalogDBObject.  The metaclass of CatalogDBObject creates a registry of these daughter classes so that, at run time, the user can create an instantiation of a specific CatalogDBObject daughter class using

  CatalogDBObjec

  Code Block
  CatalogDBObject.from_objid('myDaughterClass')

  assuming that myDaughterClass's objid='myDaughterClass'.  The framework overview page contains some concrete examples of this functionality in action.

• tableid is a string indicating what table within the database this particular CatalogDBObject will query.
• idColKey is a string indicating the name of the column in the database table that uniquely identifies each astronomical objectobjectTypeId is an int indicating what type of objects this CatalogDBObject refers to.  In addition to the registry of daughter classes, the CatalogDBObject meta class keeps a list of daughter classes corresponding to different objectTypeId's.  This is stored in CatalogDBObject.objectTypeIdList.   It is used by InstanceCatalog to give objects in each catalog a uniqueId (even if the object appears in more than one catalog).  See the get_uniqueId() method in the InstanceCatalog class in sims_catalogs_measures.
• skipRegistration is a boolean.  If True, this particular daughter class of CatalogDBobject will not be added to CatalogDBobject.objectTypeIdList.

• columns is a list of columns transformations made by this CatalogDBObject to convert raw database columns into outputs the InstanceCatalog expects (converting 'ra' to 'raJ2000', etc.).  For an example of how this is used, see the iPython notebook

  Code Block
  sims_catUtils/examples/tutorials/reading_int_custom_data.ipynb

• dbDefaultValues is a dict containing default values to assign to columns in the event that they are 'None' in the database (Note: the defaulted columns must exist in the database; this default applies only if the database-assigned value is None)
• raColName is a string indicating the name of the column in the database containing RA
• decColNam is a string indicating the name of the column in the database containing dec

...

• query_columns – This method accepts a list of column names and automatically construct an SQL query to pull those columns (subject to contraints imposed by an ObservationMetaData instantiation) from the database.  This is the principal innovation going from DBObject to CatalogDBObject.
• from_objid – This is a method which allows you to instantiate a daughter class of CatalogDBobject by referring to its objid.  See the framework overview page (specifically the CatalogDBObject subsection) for an example of this code in-use.
• getCatalog – This is the equivalent of from_objid for catalog classes.  If you know the catalog_type member variable of a specific catalog class, you can instantiate that catalog class from a CatalogDBObject using myCatalogDBObject.getCatalog('myCatalogType').  See the 'Pre-defined catalog classes' section of the framework overview page for an example of how to use this code.

fileDBObject

The fileDBObject class is a daughter of CatalogDBObject whose constructor is designed to read in a text file and convert it into a database file.  To see how this is done, consult the iPython notebook

sims_catUtils/examples/tutorials/reading_in_custom_data.ipynb

Return to the Catalog Simulations Framework Overview page.

...