DiaObject

class snappl.diaobject.DiaObject(id=None, provenance_id=None, ra=None, dec=None, name=None, iauname=None, mjd_discovery=None, mjd_peak=None, mjd_start=None, mjd_end=None, ndetected=1, properties={})[source]

Bases: object

Encapsulate a single supernova (or other transient).

Standard properties:

id : UUID; the id of the object if it is in the SNPIT Internal database (or intended to be) provenance_id : UUID; the provenance of the object if it is in the SNPIT Internal database (or intended to be)

namestr; some name assigned by the thing that found it. These

will be heterogeneous, may be duplciated for different objects, and may be None, so don’t rely on this property as an identifier. View it as more a comment field.

iaunamestr; the IAU or TNS name for the object, if know, and if the field has been populated.

Will be None for most objects.

ra : ra in degrees (ICRS) dec : dec in degrees (ICRS)

The ra/dec position should be considered an _approximate_ position only. It’s the position that was saved when the object was first found, which means it was probably well before peak and likely a low S/N detection. Use get_position() with an appropriate provenance to find a better position for an object (if we’ve calcaulted one).

mjd_discovery : when the object was first discovered; may be None if unknown (float MJD) mjd_peak : peak of the object’s lightcurve; may be None if unknown (float MJD)

mjd_startMJD when the lightcurve first exists. Definition of this

is class-dependent; it may be when it was actively simulated, but it may be when the lightcurve is above some cutoff. May be None if unknown.

mjd_endMJD when the lightcurve stops existing. Definition like

mjd_start. May be None if unknown.

propertiesdictionary of additional properties. DO NOT RELY ON

THIS HAVING ANY PARTICULAR KEYS. Different provenances, and maybe even different objects within the same provenance, may have different keys in this dictionary. This is more to be used for debugging purposes. (If there is an additional key that every object should have, we should add it as a top-level property, and add that column to the database.)

Usually, don’t instantiate one of these directly. Instead, use DiaObject.get_object or DiaObject.find_objects. If you’re trying to get a manual object, use provenance_tag ‘manual’ with DiaObject.get_object. Only instantiate a DiaObject if you’re writing discovery software and want to create a new one to save to the database.

Only call this constructor if you’re making a brand new object.

If you want to get an existing object, call either DiaObject.get_object or DiaObject.find_objects.

Properties

idUUID or str, default None.

The id of the diaobject. If you leave this as None (recommended), a new one will be assigned.

provenance_idUUID or str

The provenance of the object. Required if you’re going to save this to the database later.

rafloat

Decimal degrees.

decfloat

Decimal degrees.

namestr, defanot None

A name for the object. These aren’t strictly required to be unique, but you should strive to make them unique. Normally, saving them will raise an error if you end up with more than one object in the same provenance with the same name. Ideally, this is something digestable for humans, but if you’re lazy, you can make this a string version of id and then you can be sure it will be unique. You may also just leave it at Hone.

iaunamestr, default None

The IAU / TNS name for the object. If given, this must be unique within a given provenance, though it’s OK if it’s None.

mjd_discoveryfloat

MJD when the object was found. Required.

mjd_peakfloat, default None

MJD when the object is at peak. Optional

mjd_startfloat, default None

MJD when the transient starts. This means that any images from an earlier MJD are suitable for use as a template. Optional.

mjd_endfloat, default None

MJD when the tranient “ends”. Physically, this is meaningless, but practically, it means that any images from a later MJD are suitable for use as a template. Optional.

ndetectedint, default 1

The number of times this object has been detected. When creating a new DiaObject, you usually want this to be 1 (the default) unless you really know what you’re doing. When a DiaObject has been loaded from the database, this will have the number in the corresponding database column.

propertiesdict, default {}

Any optional properties you want to save with the object.

Methods Summary

find_objects([collection, provenance, ...])

Find objects.

get_diaobject_positions([diaobject_ids, ...])

Get updated positions for a list of diaobjects.

get_object([collection, provenance, ...])

Get a DiaObject.

get_position([position_provenance, ...])

Get updated diaobject position.

save_object([association_radius, dbclient])

Save an object to the database.

save_updated_position([position_provenance, ...])

Methods Documentation

classmethod find_objects(collection='snpitdb', provenance=None, provenance_tag=None, process=None, dbclient=None, **kwargs)[source]

Find objects.

Parameters:

collection (str, default 'snpitdb') –

Which collection of objects to search. Options are:
  • snpitdbuse the Roman SNPIT Internal DB as defined in Config

    This requires either provenance_id, or provenance_tag and process

  • ou2024 : use OpenUniverse2024 truth tables

  • manual : manually create objects

provenanceProvenance, UUID, or UUIDifiable str

The provenance to search. Must specify either this or provenance_tag. If you specify both, it will verify consistency. Invalid if collection is not ‘snpitdb’.

provenance_tagstr

The provenance tag to search. For some provenance tags, this goes to a specific subclass (and in that case, provenance_id must be None), but for most, it queries the Roman SNPIT itnernal database. Optional if you specify provenance. Invalid if collection is not ‘snpitdb’.

processstr, default None

The process associated with the provenacne_tag that allows the code to determine a unique provenance. Needed if provenance_tag is not None.

dbclientSNPITDBClient, default None

The database web api connection object to use. If you don’t specify one, a new one will be made based on what’s in your configuration.

diaobject_id<something>, default None

The diaobject_id of the object to find. Only valid if collection is ‘snpitdb’.

namestr

The optional name of the object. May not be implemented for all collections.

iaunamestr

The TNS/IAU name of the object. May not be implemented for all collections.

ra: float

RA in degrees to search.

dec: float

Dec in degrees to search.

radius: float, default 1.0

Radius in arcseconds to search. Ignored unless ra and dec are given.

mjd_peak_min, mjd_peak_max: float

Only return objects whose mjd_peak is between these limits. Specify as MJD. Will not return any objects with unknown mjd_peak.

mjd_discovery_min, mjd_discovery_max: float

Only return objects whose mjd_discovery is between these limits. Specify as MJD. Wil not return any objects with unknown mjd_discovery.

mjd_start_min, mjd_start_max: float

mjd_end_min, mjd_end_max: float

order_by: str, default None

By default, the returned objects are not sorted in any particular way. Put a keyword here to sort by that value. Options include ‘id’, ‘provenance_id’, ‘name’, ‘iauname’, ‘ra’, ‘dec’, ‘mjd_discovery’, ‘mjd_peak’, ‘mjd_start’, ‘mjd_end’. Not all of these are necessarily useful, and some of them may be null for many objects in the database.

limitint, default None

Only return this many objects at most.

offsetint, default None

Useful with limit and order_by ; offset the returned value by this many entries. You can make repeated calls to find_objects to get subsets of objects by passing the same order_by and limit, but different offsets each time, to slowly build up a list.

Returns:

  • list of DiaObject

  • In reality, it may be a list of objects of a subclass of

  • DiaObject, but the calling code should not know or depend on

  • that, it should treat them all as just DiaObject objects.

classmethod get_diaobject_positions(diaobject_ids=[], position_provenance=None, provenance_tag=None, process=None, dbclient=None)[source]

Get updated positions for a list of diaobjects.

Parameters:

  • diaobject_ids (list of DiaObject, UUID, or str) – The DiaObject (or the ids of same) of the objects whose positions you want.

  • position_provenance (UUID or str, default None) – The Provenance of the position (not of the object). Must specify either this, or provenance_tag and process, not both.

  • provenance_tag (str, default None) – The provenance tag for the position (not the object). Must specify either this or position_provenance. provenance_tag requires process. (If you specify position_provenance, this is ignored.)

  • process (str, default None) – The process to go with provenance_tag to get the position provenance.

  • dbclient (SNPITDBClient, default None.) – The connection to the database web server. If None, a new one will be made that logs you in using the information in Config.

Returns:

  • dict of diaobjectid (dict)

  • Each sub-dict has keys id, diaobject_id, provenance_id, ra, ra_err, dec, dec_err, ra_dec_covar, calcualted_at

  • Note that ra_err, dec_err, and ra_dec_covar might be None.

classmethod get_object(collection='snpitdb', provenance=None, provenance_tag=None, process=None, name=None, iauname=None, diaobject_id=None, multiple_ok=False, dbclient=None)[source]

Get a DiaObject. from the database.

RECOMMENDATION: only call this when you know the diaobject_id. In that case, pass the diaobject_id, optionally pass a dbclient, and optionally pass either provenance, or provenance_tag and process. If you pass provenance info, this function will verify that the object you asked for is in that provenance; if you don’t, it will just return the object you asked for.

While you can use the name= and iauname= parameters, I recommend you don’t use this function. Instead, use find_objects.

Specify the object with exactly one of:

  • diaobject_id

  • name

  • iauname

If you pass diaobject_id, then it’s optional to pass one either provenance_id or (provenance_tag and process). If you do pass one of those, then you will get an error of the diaobject_id you asked for isn’t in the set you asked for.

Note that if you ask for “name”, there might be multiple objects in the database with the same name for a given provenance, because the database does not enforce uniqueness. (It does for iauname.) “name” is really more of an advisory field. If multiple_ok is False (the default), this is an error; if multiple_ok is True, you’ll get a list back.

NOTE : in the future we will add the concept of “root diaobject” so that we can identify when the same objects show up in different provenances. This method will change when that happens.

Parameters:

  • collection (str, default 'snpitdb') –

    Which collection of objects to search. Options are:
    • snpitdbuse the Roman SNPIT Internal DB as defined in Config

      This requires either provenance_id, or provenance_tag and process

    • ou2024 : use OpenUniverse2024 truth tables

    • manual : manually create objects

  • provenance (Provenance, UUID, or UUIDifiable str, default None) – The provenance of the object you’re looking for. You don’t need this if you pass provenance_tag and process, or if you pass diaobject_id. Invalid if collection is not ‘snpitdb’.

  • provenance_tag (str, default None) – The human-readable provenance tag for the provenance of objects you want to dig through. Requires ‘process’. You must specify at least one of provenance_Tag or provenance. Invalid if collection is not ‘snpitdb’.

  • process (str, default None) – The process associated with the provenance_tag (needed to determine a unique provenance id). Needed if provenance_tag is not None.

  • diaobject_id (UUID or str or maybe something else) – The diaobject_id of the object to get. Invalid if collection is not ‘snpitdb’.

  • name (str (usually; might be an int for some provenance_tags)) – The name of the object as determined by whoever it was that was making the mess when loading objects into the database. This is not guaranteed to be unique. However, if you know what you’re doing, it may be useful. If you are happy receiving all the objects for a given provenance with the same name, set multiple_ok to True; otherwise, it’ll be an error if more than one object has the same name.

  • iauname (str) – The iau/tns name of the object you want to find. These are guaranteed to be unique within a given provenance.

  • diaobject_id – The Romamn SNPIT internal database id of the object you want. If you specify this, you don’t need anything else. If you also give one of (provenance_id, provenance_tag and process, collection and subset), then this method will verify that the object_id you’re looking for is within the right provenance.

  • multiple_ok (bool, default False) – Only matters if you specify name instead of object_id or iauname. Ignored if you don’t specify name. See Returns.

  • dbclient (SNPITDBClient, default None) – The database web api connection object to use. If you don’t specify one, a new one will be made based on what’s in your configuration.

Returns:

  • DiaObject or list of DiaObject

  • If you specify name and you set multiple_ok=True, then you get

  • a list of DiaObject back. Otherwise, you get a single one.

  • If no object is found with your criteria, a RuntimeError

  • exception will be raised.

get_position(position_provenance=None, provenance_tag=None, process=None, dbclient=None)[source]

Get updated diaobject position.

Parameters:

  • position_provenance (UUID or str, default None) – The Provenance of the position (not of the object). Must specify either this, or provenance_tag and process, not both.

  • provenance_tag (str, default None) – The provenance tag for the position (not the object). Must specify either this or position_provenance. provenance_tag requires process. (If you specify position_provenance, this is ignored.)

  • process (str, default None) – The process to go with provenance_tag to get the position provenance.

  • dbclient (SNPITDBClient, default None.) – The connection to the database web server. If None, a new one will be made that logs you in using the information in Config.

Returns:

  • dict

  • Keys are (id, diaobject_id, provenance_id, ra, ra_err, dec, dec_err, ra_dec_covar, calculated_at)

  • Note that ra_err, dec_err, and ra_dec_covar might be None.

save_object(association_radius=1.0, dbclient=None)[source]

Save an object to the database.

Properties

association_radiusfloat, default 1.0

If an object of the right provenance already exists in the database within this many arcseconds of the object being saved, then the new object is not saved. Make this None to never associate, but always save new objects. (This is probably a bad idea.)

dbclientSNPITDBClient, default None

The connection to the database web server. If None, a new one will be made that logs you in using the information in Config. If you’re going to be saving multiple objects, it’s more efficient to make one of these once and pass it to each call to save_object than it is to let save_object make a new one each time.

returns:

  • dict

  • Either the row from the database of the pre-existing object

  • (if there was one within association_radius), or the row

  • inserted into the database.

save_updated_position(position_provenance=None, provenance_tag=None, process=None, ra=None, dec=None, ra_err=None, dec_err=None, ra_dec_covar=None, dbclient=None)[source]