InstancesFromModels¶
- class pyvo.mivot.writer.InstancesFromModels(votable, *, dmid=None)[source]¶
- Bases: - object- Top-level API class that allows to create VOTable annotations with objects issued from the Mango model and its imported classes. - The annotation structure is handled by the API based on mapping rules provided by the user. - The classes currently supported are: - Photometric Calibrations (PhotDM) 
- Spatial and temporal coordinate systems (Coordinates DM) 
- MangoObject (QueryOrigin, EpochPosition, Brightness and Color) 
 - The mapping built by this API relates to the first table. - Constructor parameters: - Parameters:
- votableastropy.io.votable.tree.VOTableFile
- parsed votable to be annotated 
- dmidstring, optional (default is None)
- Column identifier or value (is starts with - *) to be used as identifier of the MangoObject mapping each data row
 
 - Attributes Summary - Methods Summary - add_mango_brightness(*[, photcal_id, ...])- Add a Mango - Brightnessinstance to the current- MangoObjectwith the specified photometric calibration, using the mapping parameter to associate VOtable data with it.- add_mango_color(*[, filter_ids, mapping, ...])- Add a Mango - Colorinstance to the current- MangoObjectwith the specified low and high filters, using the mapping parameter to associate VOtable data with it.- add_mango_epoch_position(*[, frames, ...])- Add a Mango - EpochPositioninstance to the current- MangoObjectwith the specified frames and semantics, using the mapping parameter to associate VOtable data with it.- add_photcal(filter_name)- Add to the GLOBALS the requested photometric calibration as defined in PhotDM1.1 - add_query_origin([mapping])- Add the Mango - QueryOrigininstance to the current- MangoObject.- add_simple_space_frame([spaceRefFrame, ...])- Adds a SpaceSys instance to the GLOBALS block as defined in the Coordinates data model V1.0 (https://ivoa.net/documents/Coords/20221004/index.html). - add_simple_time_frame([timescale, refPosition])- Adds a TimeSys instance to the GLOBALS block as defined in the Coordinates data model V1.0 (https://ivoa.net/documents/Coords/20221004/index.html). - Build a - mango:QueryOriginfrom the INFO elements located in the VOTable header.- Build a dictionary with the 3 parameters required by - pyvo.mivot.writer.InstancesFromModels.add_mango_epoch_position()(frames, mapping, semantic).- Build space and time frames ( - coords:SpaceSysand- coords:TimeSys) from the INFO elements located in the header of the first VOTable resource.- pack_into_votable(*[, report_msg, sparse])- Pack all mapped objects in the annotation block and put it in the VOTable. - Attributes Documentation - mivot_block¶
 - Methods Documentation - add_mango_brightness(*, photcal_id=None, mapping={}, semantics={})[source]¶
- Add a Mango - Brightnessinstance to the current- MangoObjectwith the specified photometric calibration, using the mapping parameter to associate VOtable data with it. This method acts as a front-end for- pyvo.mivot.writer.MangoObjectlogic.- Parameters:
- photcal_idstring, optional (default is None)
- Filter profile service (http://svo2.cab.inta-csic.es/theory/fps/} identifier of the desired photometric calibration. It is made of the filter identifier followed by the photometric system (e.g. GAIA/GAIA3.Grvs/AB) 
- mappingdict, optional (default to an empty dictionary ({})
- A dictionary defining the mapping of values. It includes: - mapping of the brightness value 
- one separate block for the error specification 
 
- semanticsdict, optional (default to an empty dictionary ({})
- A dictionary specifying semantic details to be added to the Mango property. 
 
- Returns:
- Property
- The Mango property 
 
 - Notes - The mapping example below maps the data of the GaiaD3 table that can be found in the test suite. Notice that the (fake) error bounds are given as literalS. - photcal_id="GAIA/GAIA3.Grvs/AB" mapping={"value": "GRVSmag", "error": { "class": "PErrorAsym1D", "low": 1, "high": 3} } semantics={"description": "Grvs magnitude", "uri": "https://www.ivoa.net/rdf/uat/2024-06-25/uat.html#magnitude", "label": "magnitude"} builder = InstancesFromModels(votable, dmid="DR3Name") builder.add_mango_magnitude(photcal_id=photcal_id, mapping=mapping, semantics=semantics) 
 - add_mango_color(*, filter_ids={}, mapping={}, semantics={})[source]¶
- Add a Mango - Colorinstance to the current- MangoObjectwith the specified low and high filters, using the mapping parameter to associate VOtable data with it. This method acts as a front-end for- pyvo.mivot.writer.MangoObjectlogic.- Parameters:
- filter_idsstring, optional (default to an empty dictionary {})
- Filter profile service (http://svo2.cab.inta-csic.es/theory/fps/} identifiers of the high and low photometric calibrations that contain the desired filters. Identifiers are made of the filter identifier followed by the photometric system (e.g. GAIA/GAIA3.Grvs/AB). 
- mappingdict, optional (default to an empty dictionary ({})
- A dictionary defining the mapping of values. It includes: - The mapping of the color value and the color definition (ColorIndex or HardnessRatio). 
- One separate block for the error specification. 
 
- semanticsdict, optional (default to an empty dictionary {})
- A dictionary specifying semantic details to be added to the Mango property. 
 
- Returns:
- Property
- The Mango property 
 
 - Notes - The mapping example below maps the data of the GaiaD3 table that can be found in the test suite. The (fake) color value is given as a literal, it does not refer to any table column. - filter_ids={"low": "GAIA/GAIA3.Grp/AB", "high": "GAIA/GAIA3.Grvs/AB"} mapping={"value": 0.08, "definition": "ColorIndex", "error": { "class": "PErrorAsym1D", "low": 0.01, "high": 0.02} } semantics={"description": "Fake color index", "uri": "http://astrothesaurus.org/uat/1553", "label": "Spectral index"} builder = InstancesFromModels(votable, dmid="DR3Name") builder.add_mango_color(filter_ids=filter_ids, mapping=mapping, semantics=semantics) 
 - add_mango_epoch_position(*, frames={}, mapping={}, semantics={})[source]¶
- Add a Mango - EpochPositioninstance to the current- MangoObjectwith the specified frames and semantics, using the mapping parameter to associate VOtable data with it. This method acts as a front-end for- pyvo.mivot.writer.MangoObjectlogic.- Parameters:
- framesdict, optional (default to an empty dictionary {})
- A dictionary specifying the frames (space and time coordinate systems) to be used. Frames parameters are global, they cannot refer to table columns. If a frame description contains the “dmid” key, that value will be used as an identifier an already installed frame (e.g. with - extract_frames()). Otherwise the content of the frame description is meant to be used in input parameter for- add_simple_(space)time_frame()
- mappingdict, optional (default to an empty dictionary {})
- A dictionary defining the mapping of values. It includes: - A flat list for position parameters. 
- Two separate blocks for correlations and error specifications. 
 
- semanticsdict, optional (default to an empty dictionary {})
- A dictionary specifying semantic details to be added to the Mango property. 
 
- Returns:
- Property
- The Mango property 
 
 - Notes - The mapping example below maps the data of the GaiaD3 table that can be found in the test suite. - frames={"spaceSys": {"spaceRefFrame": "ICRS", "refPosition": 'BARYCENTER', "equinox": None}, "timeSys": {"timescale": "TCB", "refPosition": 'BARYCENTER'}} mapping={"longitude": "_RAJ2000", "latitude": "_DEJ2000", "pmLongitude": "pmRA", "pmLatitude": "pmDE", "parallax": "Plx", "radialVelocity": "RV", "correlations": {"isCovariance": True, "longitudeLatitude": "RADEcor", "latitudePmLongitude": "DEpmRAcor", "latitudePmLatitude": "DEpmDEcor", "longitudePmLongitude": "RApmRAcor", "longitudePmLatitude": "RApmDEcor", "longitudeParallax": "RAPlxcor", "latitudeParallax": "DEPlxcor", "pmLongitudeParallax": "PlxpmRAcor", "pmLatitudeParallax": "PlxpmDEcor", }, "errors": { "position": { "class": "PErrorSym2D", "sigma1": "e_RA_ICRS", "sigma2": "e_DE_ICRS"}, "properMotion": { "class": "PErrorSym2D", "sigma1": "e_pmRA", "sigma2": "e_pmDE"}, "parallax": { "class": "PErrorSym1D", "sigma": "e_Plx"}, "radialVelocity": { "class": "PErrorSym1D", "sigma": "e_RV"} } } semantics={"description": "6 parameters position", "uri": "https://www.ivoa.net/rdf/uat/2024-06-25/uat.html#astronomical-location", "label": "Astronomical location"} builder = InstancesFromModels(votable, dmid="DR3Name") builder.add_mango_epoch_position(frames=frames, mapping=mapping, semantics=semantics) 
 - add_photcal(filter_name)[source]¶
- Add to the GLOBALS the requested photometric calibration as defined in PhotDM1.1 - The MIVOT serialization is provided by the SVO Filter Profile Service (https://ui.adsabs.harvard.edu/abs/2020sea..confE.182R/abstract) - It is returned as one block containing the whole PhotCal instance. The filter instance is extracted from the PhotCal object, where it is replaced with a REFERENCE. This makes the filter available as a GLOBALS to objects that need it. - The dmid of the PhotCal is - _photcal_DMIDwhere DMID is the formatted version of- filter_name(see- pyvo.mivot.utils.MivotUtils.format_dmid).
- The dmid of the PhotFilter is - _photfilter_DMIDwhere DMID is the formatted version of- filter_name.
 - Parameters:
- filter_namestr
- FPS identifier (SVO Photcal ID) of the request filter 
 
- Returns:
- (str, str)
- dmids of photcal and filter instances 
 
 
 - add_query_origin(mapping={})[source]¶
- Add the Mango - QueryOrigininstance to the current- MangoObject. This method acts as a front-end for- pyvo.mivot.writer.MangoObjectlogic.- Parameters:
- mappingdict, optional (default to an empty dictionary {})
- A dictionary defining the QueryOrigin fields. Mapped fields are global, they cannot refer to table columns 
 
- Returns:
 - Notes - The partial mapping example below maps a fake QueryOrigin. A complete (long) example based on GaiaD3 can be found in the test suite. - builder = InstancesFromModels(votable, dmid="DR3Name") builder.add_query_origin( { "service_protocol": "ivo://ivoa.net/std/ConeSearch/v1.03", "request_date": "2025-04-07T12:06:32", "request": ( "https://cdsarc.cds.unistra.fr/beta/viz-bin/mivotconesearch" "/I/329/urat1?RA=52.26708&DEC=59.94027&SR=0.05" ), "contact": "cds-question@unistra.fr", "server_software": "7.4.6", "publisher": "CDS", "dataOrigin": [ { "ivoid": "ivo://cds.vizier/i/329", "creators": ["Zacharias N."], "cites": "bibcode:2015AJ....150..101Z", "original_date": "2015", "reference_url": "https://cdsarc.cds.unistra.fr/viz-bin/cat/I/329", "rights_uri": "https://cds.unistra.fr/vizier-org/licences_vizier.html", "articles": [{"editor": "Astronomical Journal (AAS)"}], } ], } ) 
 - add_simple_space_frame(spaceRefFrame='ICRS', refPosition='BARYCENTER', equinox=None, epoch=None)[source]¶
- Adds a SpaceSys instance to the GLOBALS block as defined in the Coordinates data model V1.0 (https://ivoa.net/documents/Coords/20221004/index.html). - Notes: - This function implements only the most commonly used features. Custom reference positions for TOPOCENTER frames are not supported. However, methods for implementing the missing features can be derived from this code. 
- A warning is emitted if either - spaceRefFrameor- refPositionhave unexpected values.
- No error is raised if the parameter values are inconsistent. 
- The - dmidof the time frame is built from- spaceRefFrame,- refrefPosition_positionand- equinox.
 - Parameters:
- spaceRefFramestr, optional, default “ICRS”
- The reference frame for the space frame. 
- refPositionstr, optional, default “BARYCENTER”
- The reference position for the space frame. 
- equinoxstr, optional, default None
- The equinox for the reference frame, if applicable. 
- epochstr, optional, default None
- The epoch for the reference location, if applicable. 
 
- Returns:
- str
- The actual dmid of the time frame INSTANCE 
 
 
 - add_simple_time_frame(timescale='TCB', *, refPosition='BARYCENTER')[source]¶
- Adds a TimeSys instance to the GLOBALS block as defined in the Coordinates data model V1.0 (https://ivoa.net/documents/Coords/20221004/index.html). - Notes: - This function implements only the most commonly used features. Custom reference directions are not supported. However, methods for implementing missing features can be derived from this code. 
- A warning is emitted if either - timescaleor- refPositionhave unexpected values.
- No error is raised if the parameter values are inconsistent. 
- The - dmidof the time rame is built from- timescaleand- refPosition.
 - Parameters:
- timescalestr, optional, default “TCB”
- The reference frame for the time frame. 
- refPositionstr, optional, default “BARYCENTER”
- The reference position for the time frame. 
 
- Returns:
- str
- The actual dmid of the time frame INSTANCE 
 
 
 - extract_data_origin()[source]¶
- Build a - mango:QueryOriginfrom the INFO elements located in the VOTable header. The instance is added to the GLOBALS Mivot block.- Returns:
- MivotInstance
- The - mango:QueryOriginMivot instance
 
 
 - extract_epoch_position_parameters()[source]¶
- Build a dictionary with the 3 parameters required by - pyvo.mivot.writer.InstancesFromModels.add_mango_epoch_position()(frames, mapping, semantic).- frames: references to the frames created from COOSYS/TIMSYS (see - pyvo.mivot.writer.InstancesFromModels.extract_frames()
- mapping: inferred from the FIELD ucd-s 
- semantics: hard-coded 
 - This method does not add the - EpochPositionproperty because the mapping parameters often need first to be completed (or fixed) by hand. This especially true for the correlations that cannot be automatically detected in a generic way (no specific UCD)- epoch_position_mapping = builder.extract_epoch_position_parameters() builder.add_mango_epoch_position(**epoch_position_mapping) - Returns:
- {“frames”, “mapping”, “semantics”}
- Dictionary of mapping elements that can unpacked to feed - add_mango_epoch_position().
 
 
 - extract_frames()[source]¶
- Build space and time frames ( - coords:SpaceSysand- coords:TimeSys) from the INFO elements located in the header of the first VOTable resource. The instances are added to the GLOBALS Mivot block.- Note - The VOTable can host multiple instances of COOSYS or TIMESYS, but in the current implementation, only the first one is taken - Returns:
- {“spaceSys”: [{“dmid”}], “timeSys”: [{“dmid”}]}
- Dictionary of all dmid-s of the frames actually added to the annotations. These dmid-s must be used by instances ATTRIBUTEs to their related frames. This dictionary can be used - framesparameter of- add_mango_epoch_position
 
 
 - pack_into_votable(*, report_msg='', sparse=False)[source]¶
- Pack all mapped objects in the annotation block and put it in the VOTable. - Parameters:
- report_msg: string, optional (default to an empty string)
- Content of the REPORT Mivot tag 
- sparse: boolean, optional (default to False)
- If True, all properties are added in a independent way to the the TEMPLATES. They are packed in a MangoObject otherwise.