Skip to content

Snippet Generation

Jump to bottom
Julien Abid edited this page Jun 9, 2023 · 9 revisions

Snippet Generation

Table of content

  1. Foreword
  2. How to use
  3. Examples

Foreword

To facilitate the production of a VODML file mapped in MIVOT format, it can be interesting to generate snippets to save time, or to use them as reference.

The snippet generators are designed for this purpose.

There are two types of snippet generators:

  • The model snippet generator, which will allow, for a given model, to generate all types of non-abstract objects found in it.

This can be useful to have a view of the model directly formatted in MIVOT, and to use it to complete a mapping already started.

  • The instance snippet generator, which for a given concrete class name, will generate a snippet usable according to the concrete classes chosen when creating it (see Examples)

This can be used to complete a template in a mapping block.

How to use

First of all, make sure you have correctly installed the mivot-validator package, if it is not the case please consult this page

Model Snippets

The command to run the script is the following:

mivot-snippet-model [path]

Here, the path argument represent any vodml-model XML file as absolute path or URL. If you need further information just typing the command without any arguments will prompt the following text :

USAGE: mivot-snippet-model [path]
   Create MIVOT snippets from VODML files
   path: either a simple file to any VODML-Model or an url
   exit status: 0 in case of success, 1 otherwise

Instance Snippets

The command to run the script is the following:

mivot-snippet-instance [class_name] [output_dir] [output_name] <classes_list>

The arguments represents:

  • class_name: A mandatory argument which specify which class of the model we generate a snippet for, the naming goes like model:Class
  • output_dir: A mandatory argument which specify the location of the next generated snippet, as an absolute path.
  • output_name: A mandatory argument which specify the name of the next generated snippet (extension of the file is not mandatory)
  • classes_list: An optional argument which specify list of concrete classes which will replace the abstract classes in their order of appearance, so be sure to think in advance about the different encounters of abstract classes in the snippet you want to generate. (For more details please see this example)

Be aware that each concrete_class described as an optional argument classes_list must be entered in THE ORDER in which the mapping occurs, so be sure to read up on the subject beforehand, or try to generate a snippet without this argument. You should also be aware that if you don't have a dmrole to fill in, the syntax dmrole= without any text following the = is valid.

Please note that to add the same instance several times to a collection of abstract instances, you need to use the classes_list argument as many times as you want to add it. In the same case, note that if an instance has a multiplicity of 0, the presence of invalid information in the mapping order in the classes_list arguments will be interpreted as the non-presence of that instance.

If you need further information just typing the command mivot-snippet-instance -h will prompt the following text :

usage: mivot-snippet-instance [-h] [-cc [classes_list]] [class_name] [output_dir] [output_name]

Create MIVOT snippets from VODML files

positional arguments:
  class_name            either a absolute file path to any MIVOT mapping class or just a class name as model:Class
  output_dir            path to the choosen output directory
  output_name           name of the output file (no need to put the extension at the end of it)

optional arguments:
  -h, --help            show this help message and exit
  -cc [classes_list], --concrete-class [classes_list]
                        [OPTIONAL] list of classes to be included in the snippet, it will prevent the script to ask for the user input if given. Syntax is :
                        dmrole=model:Type.role,context=model:ParentType,dmtype=model:Type,class=model:Type

Examples

Model Snippets

Let's consider that we want to generate code snippets for all object types of the Coordinates model:

mivot-snippet-model https://ivoa.net/xml/VODML/Coords-v1.0.vo-dml.xml

If everything goes right, you will get the following message :

===============================================
Snippets generated in /home/jabid/.local/lib/python3.8/site-packages/mivot_validator-2.0-py3.8.egg/mivot_validator/instance_checking/tmp_snippets 
in the folder : coords
===============================================

Please note that in that state, the generic snippets are saved inside the tmp_snippets folder of the mivot-validator package. The package location is specified within the message of creation of the snippet, more precisely in the site-package of the python lib folder.

Normally, you will get a folder tree like the following inside the mivot-validator package :

mivot-validator/
└── mivot_validator/
    └── instance_checking/
        └── tmp_snippets/
            └── coords/
                ├── coords.AstroCoordSystem.xml
                ├── coords.BinnedAxis.xml
                ├── coords.CartesianCoordSpace.xml
                ├── coords.ContinuousAxis.xml
                ├── coords.DiscreteSetAxis.xml
                ├── coords.GenericFrame.xml
                ├── coords.GenericSys.xml
                ├── coords.PixelCoordSystem.xml
                ├── coords.PixelSpace.xml
                ├── coords.SpaceFrame.xml
                ├── coords.SpaceSys.xml
                ├── coords.SphericalCoordSpace.xml
                ├── coords.TimeFrame.xml
                └── coords.TimeSys.xml

Here is the result of the coords.TimeSys.xml snippet:

<INSTANCE dmrole="" dmtype="coords:TimeSys">
   <!-- Specialized coordinate system for the Temporal domain.  This object SHOULD include an appropriate TimeFrame.  If a CoordSpace is not provided, it is assumed to be represented by a Standard 1-Dimensional Coordinate Space as described in Appendix B." -->
   <!-- the axis representation (coords:PhysicalCoordSys.coordSpace) is not serialized here -->
   <INSTANCE dmrole="coords:PhysicalCoordSys.frame" dmtype="coords:TimeFrame">
      <!-- A TimeFrame SHALL include a time scale and reference position.  It MAY also include a reference direction." -->
      <!-- Put here a concrete INSTANCE of RefLocation or left blank -->
      <INSTANCE dmrole="coords:TimeFrame.refPosition" dmtype="coords:RefLocation"/>
      <ATTRIBUTE dmrole="coords:TimeFrame.timescale" dmtype="ivoa:string" ref="@@@@@" value=""/>
      <!-- Put here a concrete INSTANCE of RefLocation or left blank -->
      <INSTANCE dmrole="coords:TimeFrame.refDirection" dmtype="coords:RefLocation"/>
   </INSTANCE>
</INSTANCE>

As you can see, all the abstract classes instances are not complete, for further explanation, see this example.

Instance snippets

With user input

Let's assume that we have any snippet or mapping block which is incomplete because some instances of abstract classes are not concretely specified, such as the coords.TimeSys.xml saw before :

<INSTANCE dmrole="" dmtype="coords:TimeSys">
   <!-- Specialized coordinate system for the Temporal domain.  This object SHOULD include an appropriate TimeFrame.  If a CoordSpace is not provided, it is assumed to be represented by a Standard 1-Dimensional Coordinate Space as described in Appendix B." -->
   <!-- the axis representation (coords:PhysicalCoordSys.coordSpace) is not serialized here -->
   <INSTANCE dmrole="coords:PhysicalCoordSys.frame" dmtype="coords:TimeFrame">
      <!-- A TimeFrame SHALL include a time scale and reference position.  It MAY also include a reference direction." -->
      <!-- Put here a concrete INSTANCE of RefLocation or left blank -->
      <INSTANCE dmrole="coords:TimeFrame.refPosition" dmtype="coords:RefLocation"/>
      <ATTRIBUTE dmrole="coords:TimeFrame.timescale" dmtype="ivoa:string" ref="@@@@@" value=""/>
      <!-- Put here a concrete INSTANCE of RefLocation or left blank -->
      <INSTANCE dmrole="coords:TimeFrame.refDirection" dmtype="coords:RefLocation"/>
   </INSTANCE>
</INSTANCE>

To generate a snippet with fully concrete classes instanciates, we can use the following command:

mivot-snippet-instance coords:TimeSys `pwd` coords.TimeSys.example

Here I want to generate a snippet for coords:TimeSys which will be stored in my home directory, and named coords.TimeSys.example.xml.

The script first encounter the abstract class coords:RefLocation and will ask the user to choice between several concrete classes which extends from it:

List of possible concrete classes :
DMTYPE: coords:RefLocation
CONTEXT: coords:TimeSys
DMROLE: coords:TimeFrame.refPosition
Please choose from the list below : 
0 : coords:StdRefLocation
1 : coords:CustomRefLocation
Your choice : 0

Here my choice is 0 so coords:StdRefLocation which will replace the previous INSTANCE of RefLocation.

The script encounter a second coords:RefLocation and ask to the user the following:

List of possible concrete classes :
DMTYPE: coords:RefLocation
CONTEXT: coords:TimeSys
DMROLE: coords:TimeFrame.refDirection
Please choose from the list below : 
0 : coords:StdRefLocation
1 : coords:CustomRefLocation
Your choice : 0

Again, my choice is the same as before.

Note that the script will generate the concrete instance choosen right away and ask for concrete class within it if it found any abstract classes until no one are found.

When the script is done, it will print the following output:

Concrete MIVOT snippet for coords.TimeSys.xml stored in /home/jabid/coords.TimeSys.example.xml

Here is the output content:

<INSTANCE dmrole="" dmtype="coords:TimeSys">
   <!-- Specialized coordinate system for the Temporal domain.  This object SHOULD include an appropriate TimeFrame.  If a CoordSpace is not provided, it is assumed to be represented by a Standard 1-Dimensional Coordinate Space as described in Appendix B." -->
   <!-- the axis representation (coords:PhysicalCoordSys.coordSpace) is not serialized here -->
   <INSTANCE dmrole="coords:PhysicalCoordSys.frame" dmtype="coords:TimeFrame">
      <!-- A TimeFrame SHALL include a time scale and reference position.  It MAY also include a reference direction." -->
      <INSTANCE dmrole="coords:TimeFrame.refPosition" dmtype="coords:StdRefLocation">
         <!-- An absolute a-priori known location in phase space (position and velocity).  Values are selected from the StdRefPosition vocabulary.  Considering that the GEOCENTER is really the only place for which we know the absolute location at all times, all other locations require the specification of a planetary ephemeris.  LSR[KD] are reserved for spectral and reshift frames.  TOPOCENTER (location of the observer) is special in that it assumes that the observing location is available through other means (e.g. a geographic location or an orbit ephemeris).  RELOCATABLE is available for simulations.  UNKNOWN should only be used if absolutely necessary." -->
         <ATTRIBUTE dmrole="coords:StdRefLocation.position" dmtype="ivoa:string" ref="@@@@@" value=""/>
      </INSTANCE>
      <ATTRIBUTE dmrole="coords:TimeFrame.timescale" dmtype="ivoa:string" ref="@@@@@" value=""/>
      <INSTANCE dmrole="coords:TimeFrame.refDirection" dmtype="coords:StdRefLocation">
         <!-- An absolute a-priori known location in phase space (position and velocity).  Values are selected from the StdRefPosition vocabulary.  Considering that the GEOCENTER is really the only place for which we know the absolute location at all times, all other locations require the specification of a planetary ephemeris.  LSR[KD] are reserved for spectral and reshift frames.  TOPOCENTER (location of the observer) is special in that it assumes that the observing location is available through other means (e.g. a geographic location or an orbit ephemeris).  RELOCATABLE is available for simulations.  UNKNOWN should only be used if absolutely necessary." -->
         <ATTRIBUTE dmrole="coords:StdRefLocation.position" dmtype="ivoa:string" ref="@@@@@" value=""/>
      </INSTANCE>
   </INSTANCE>
</INSTANCE>

One action generation

Note that if you don't want the script to ask for any input, you can use the optional argument -cc of the command to provide the list of concrete classes to use as the following:

mivot-snippet-instance coords:TimeSys `pwd` coords.TimeSys.example \
    -cc dmrole=coords:TimeFrame.refPosition,context=coords:TimeSys,dmtype=coords:RefLocation,class=coords:StdRefLocation \
    -cc dmrole=coords:TimeFrame.refDirection,context=coords:TimeSys,dmtype=coords:RefLocation,class=coords:StdRefLocation

The -cc or --concrete-class flag is used to tell the program which concrete class it have to replace the abstract one given by dmtype which is contained in context with the role dmrole. We use the flag each time we have an abstract class to replace in our program. Here, the abstract class of type coords:RefLocation playing the role coords:TimeFrame.refDirection within the class coords:TimeSys will be replaced with an instance of type coords:StdRefLocation.

If any of the given information is invalid or incoherent within the model, a warning message will be displayed and the user input behavior will be used

If you need help consider running the following command:

mivot-snippet-instance -h
Clone this wiki locally