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

mivot_block

Methods Summary

add_mango_brightness(*[, photcal_id, ...])

Add a Mango Brightness instance to the current MangoObject with the specified photometric calibration, using the mapping parameter to associate VOtable data with it.

add_mango_color(*[, filter_ids, mapping, ...])

Add a Mango Color instance to the current MangoObject with the specified low and high filters, using the mapping parameter to associate VOtable data with it.

add_mango_epoch_position(*[, frames, ...])

Add a Mango EpochPosition instance to the current MangoObject with 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 QueryOrigin instance 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).

extract_data_origin()

Build a mango:QueryOrigin from the INFO elements located in the VOTable header.

extract_epoch_position_parameters()

Build a dictionary with the 3 parameters required by pyvo.mivot.writer.InstancesFromModels.add_mango_epoch_position() (frames, mapping, semantic).

extract_frames()

Build space and time frames (coords:SpaceSys and 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 Brightness instance to the current MangoObject with 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.MangoObject logic.

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 Color instance to the current MangoObject with 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.MangoObject logic.

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 EpochPosition instance to the current MangoObject with 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.MangoObject logic.

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_DMID where DMID is the formatted version of filter_name (see pyvo.mivot.utils.MivotUtils.format_dmid).

  • The dmid of the PhotFilter is _photfilter_DMID where 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 QueryOrigin instance to the current MangoObject. This method acts as a front-end for pyvo.mivot.writer.MangoObject logic.

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:
MivotInstance

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 spaceRefFrame or refPosition have unexpected values.

  • No error is raised if the parameter values are inconsistent.

  • The dmid of the time frame is built from spaceRefFrame, refrefPosition_position and 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 timescale or refPosition have unexpected values.

  • No error is raised if the parameter values are inconsistent.

  • The dmid of the time rame is built from timescale and 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:QueryOrigin from the INFO elements located in the VOTable header. The instance is added to the GLOBALS Mivot block.

Returns:
MivotInstance

The mango:QueryOrigin Mivot 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).

This method does not add the EpochPosition property 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:SpaceSys and 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 frames parameter 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.