guideline

API Guideline

Annotation workflow

From the user perspective

• Votable parsing
• Check whether the table is annotated
• ask for a position and get and DM-enhanced SkyCoord

From the Python perspective

• Extracting the XML block
• for each row: building an XML model view of the row
• building model objects from the XML view
• building Astropy objects from the model object

These different steps are under the user control.

API Components

• XML block extractor: read or write mapping blocks from or out VOTables. Does not operate any processing.
• mapping explorator: apply the mapping to a particular row and provide endpoints to easily identify the mapped instance
• Model classes: place-holder classes for the supported models (MCT/PhotDM/Mango/??)
• Astropy Extensions: sub-classes of the Astropy quantities that can be instantiated from the mapping

Component location

Component	location
XML block extractor	astropy.io.votable
mapping explorator	pyvo.mivot
Model classes	pyvo.mivot.vodm
Astropy Extensions	pyvo.mivot.astropydm

Package names are no set for now, they are just here to show the code location depth.

Native Astropy classes vs extended classes

• All native features are kept
• New constructor with DM related parameters
• Accessor returning the coordinate frame
• Accessor returning the associated error
• Accessor returning associated quantities
• Accessor returning extra meta-data (UCD, vocab...)

Implementation note: It could be worth to extend Astropy quantities by using the delegation design pattern instead of using inheritance. The would allow to factorize all common DM related functions in one pyvo.mivot.astropydm super class while all Astropy functions are operated by delegated methods.

Code Examples

• Parsing the mapping block: We need a specific PyVO parsing class to keep a loose coupling with the Astropy VOTable parser. It would have been possible to extend the Resource class, but the mapping parsing has nothing to do the <RESOURCE> management. t is safer to run specific parser (or model view)

votable = parse('my_votable.xml')
model_view = pyvo.mivot.ModelView(votable.resources[0])

• Getting a sky SkyCoord instance

# get a pyvo.mivot.astropydm.SkyCoord instance
sky_coord  = model_view.get_first_sky_coord()
print(sky_coord.__class__)
<class 'pyvo.mivot.astropydm.SkyCoord'>

• Using native methods or accessor

print(f"position is {sky_coord.ra} {sky_coord.dec}")
position is 12.34 56.76

• Getting the semantic (mapped)

print(sky_coord.semantic)
<ucd="pos;meta.main", vocabulary="#star.position", description="Main position">

• Getting the space frame (mapped)

print(sky_coord.frame)
<class 'pyvo.mivot.vodm.coords.SpaceFrame'>

• Getting the error (mapped)

print(sky_coord.error)
<class 'pyvo.mivot.vodm.mango.CovarianceError'>