Skip to content

Usage of the MAVA API

Currently only a first PoC is implemented, see Roadmap for current status.

Make sure the API is running: see Installation innstructions

API usage

Note

For your convenience there are just command that show you how to call the api with curl. You will get the curl command that was executed printed out before the output. You can directly copy, customize and use the curl command with your own files.

List implemented api just commands

List API commands
╰─❯ just api
>> List api commands...
Available recipes:
    clear                               # Clears the entire graph on the server
    default                             # Lists api commands
    export filename=default_export_file # Exports the entire graph to a file (defaults to export.ttl)
    import filename=default_import_file # Imports data from a Turtle file
    import-annotations file=default_annotations_tsv_file mapping=default_map_annotations # Imports Annotation Series using a specified mapping
    import-observations file=default_observations_tsv_file mapping=default_map_observations # Imports Observation Series using a specified mapping
    status                              # Checks the status of the API and the current graph size
    view                                # Views graph directly in the terminal

Check

Check the API status and current graph size.

Check API status
╰─❯ just api status
>> Checking API status...
curl -sS http://localhost:8000 | jq
{
  "status": "ok",
  "graph_size": 0
}

Import

These imports have default files from the examples directory. You can also add your own custom files on the import commands as argument. Then your file will be imported instead.

Turtle

Import any Turtle file
╰─❯ just api import
>> Importing data from 'examples/input/corpus.ttl'...
curl -sS -X POST http://localhost:8000/graph/add -H "Content-Type: text/turtle" -d @examples/input/corpus.ttl | jq
{
  "message": "Data added successfully",
  "new_graph_size": 1
}

TSV

For TSV imports you neede to provide a json mapping so that the columns in the tsv file can be mapped to the ontology:

observations.tsv 
start_in_seconds    start_hh:mm:ss.ms   annotations
0.0 00:00:00.0  0.11306
0.5 00:00:00.500    0.11352
1.0 00:00:01.0  0.16284
1.5 00:00:01.500    0.18034
2.0 00:00:02.0  0.18213
map_observations.json 
{
  "series_description": "Cityview",
  "value_description": "probability for Cityview",
  "value_type": "numeric",
  "time_column": "start_in_seconds",
  "value_column": "annotations"
}
Import a TSV file with observation (probabilities at time points)
╰─❯ just import-observations
>> Importing tabular data from 'examples/input/observations.tsv' with mapping 'examples/input/map_observations.json'...
curl -sS -X POST "http://localhost:8000/graph/import_tsv?" -F "file=@examples/input/observations.tsv" -F "mapping_json=$(< examples/input/map_observations.json)" | jq
{
  "message": "Successfully imported data from observations.tsv",
  "new_graph_size": 24
}

Annotations have also columns for duration of the annotation interval:

annotations.tsv 
start_hh:mm:ss.ms   start_in_seconds    duration_hh:mm:ss.ms    duration_in_seconds annotations
00:00:00.0  0.0 00:00:08.0  8.0 ['Transcript:: Here is the first German television with the daily news.']
00:00:15.0  15.0    00:00:03.0  3.0 ['Transcript:: Today in the studio, Susanne Daubner.']
00:00:18.0  18.0    00:00:04.0  4.0 ['Transcript:: Good evening ladies and gentlemen, I welcome you to the daily news.']
00:00:22.0  22.0    00:00:03.0  3.0 ['Transcript:: On the sixth day of the invasion in Ukraine,']
00:00:25.0  25.0    00:00:03.0  3.0 ['Transcript:: the Russian troops have strengthened their attacks']
00:00:28.0  28.0    00:00:03.0  3.0 ['Transcript:: and also aimed at civilian targets.']
map_annotations.json 
{
  "series_description": "Transcription",
  "value_description": "transcript",
  "value_type": "string",
  "value_prefix": "Transcript:: ",
  "time_column": "start_in_seconds",
  "value_column": "annotations",
  "duration_column": "duration_in_seconds"
}
Import a TSV file with annotations (with duration)
╰─❯ just api import-annotations
>> Importing tabular data from 'examples/input/annotations.tsv' with mapping 'examples/input/map_annotations.json'...
curl -sS -X POST "http://localhost:8000/graph/import_tsv?" -F "file=@examples/input/annotations.tsv" -F "mapping_json=$(< examples/input/map_annotations.json)" | jq
{
  "message": "Successfully imported data from annotations.tsv",
  "new_graph_size": 57
}

View

View the graph after several imports
╰─❯ just api view
>> Viewing graph...
curl -sS http://localhost:8000/graph/export
@prefix ex: <http://example.org/data/> .
@prefix mava: <http://example.org/mava/ontology#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

ex:5041fee4-00cb-45d0-99f8-8d89fd7ae79e_point_1 a mava:ObservationPoint ;
    mava:atTime 0.0 ;
    mava:belongsToSeries ex:5041fee4-00cb-45d0-99f8-8d89fd7ae79e ;
    mava:numericValue 0.11306 .

ex:5041fee4-00cb-45d0-99f8-8d89fd7ae79e_point_2 a mava:ObservationPoint ;
    mava:atTime 0.5 ;
    mava:belongsToSeries ex:5041fee4-00cb-45d0-99f8-8d89fd7ae79e ;
    mava:numericValue 0.11352 .

ex:5041fee4-00cb-45d0-99f8-8d89fd7ae79e_point_3 a mava:ObservationPoint ;
    mava:atTime 1.0 ;
    mava:belongsToSeries ex:5041fee4-00cb-45d0-99f8-8d89fd7ae79e ;
    mava:numericValue 0.16284 .

ex:5041fee4-00cb-45d0-99f8-8d89fd7ae79e_point_4 a mava:ObservationPoint ;
    mava:atTime 1.5 ;
    mava:belongsToSeries ex:5041fee4-00cb-45d0-99f8-8d89fd7ae79e ;
    mava:numericValue 0.18034 .

ex:5041fee4-00cb-45d0-99f8-8d89fd7ae79e_point_5 a mava:ObservationPoint ;
    mava:atTime 2.0 ;
    mava:belongsToSeries ex:5041fee4-00cb-45d0-99f8-8d89fd7ae79e ;
    mava:numericValue 0.18213 .

ex:af2bf119-4c06-4bab-ab27-4b99f0aacfe8_point_1 a mava:AnnotationSegment ;
    mava:belongsToSeries ex:af2bf119-4c06-4bab-ab27-4b99f0aacfe8 ;
    mava:endTime 8.0 ;
    mava:startTime 0.0 ;
    mava:stringValue "['Transcript:: Here is the first German television with the daily news.']"^^xsd:string .

ex:af2bf119-4c06-4bab-ab27-4b99f0aacfe8_point_2 a mava:AnnotationSegment ;
    mava:belongsToSeries ex:af2bf119-4c06-4bab-ab27-4b99f0aacfe8 ;
    mava:endTime 18.0 ;
    mava:startTime 15.0 ;
    mava:stringValue "['Transcript:: Today in the studio, Susanne Daubner.']"^^xsd:string .

ex:af2bf119-4c06-4bab-ab27-4b99f0aacfe8_point_3 a mava:AnnotationSegment ;
    mava:belongsToSeries ex:af2bf119-4c06-4bab-ab27-4b99f0aacfe8 ;
    mava:endTime 22.0 ;
    mava:startTime 18.0 ;
    mava:stringValue "['Transcript:: Good evening ladies and gentlemen, I welcome you to the daily news.']"^^xsd:string .

ex:af2bf119-4c06-4bab-ab27-4b99f0aacfe8_point_4 a mava:AnnotationSegment ;
    mava:belongsToSeries ex:af2bf119-4c06-4bab-ab27-4b99f0aacfe8 ;
    mava:endTime 25.0 ;
    mava:startTime 22.0 ;
    mava:stringValue "['Transcript:: On the sixth day of the invasion in Ukraine,']"^^xsd:string .

ex:af2bf119-4c06-4bab-ab27-4b99f0aacfe8_point_5 a mava:AnnotationSegment ;
    mava:belongsToSeries ex:af2bf119-4c06-4bab-ab27-4b99f0aacfe8 ;
    mava:endTime 28.0 ;
    mava:startTime 25.0 ;
    mava:stringValue "['Transcript:: the Russian troops have strengthened their attacks']"^^xsd:string .

ex:af2bf119-4c06-4bab-ab27-4b99f0aacfe8_point_6 a mava:AnnotationSegment ;
    mava:belongsToSeries ex:af2bf119-4c06-4bab-ab27-4b99f0aacfe8 ;
    mava:endTime 31.0 ;
    mava:startTime 28.0 ;
    mava:stringValue "['Transcript:: and also aimed at civilian targets.']"^^xsd:string .

mava:Corpus1 a mava:Corpus .

ex:5041fee4-00cb-45d0-99f8-8d89fd7ae79e a mava:ObservationSeries ;
    mava:seriesDescription "Cityview" ;
    mava:valueDescription "probability for Cityview" .

ex:af2bf119-4c06-4bab-ab27-4b99f0aacfe8 a mava:AnnotationSeries ;
    mava:seriesDescription "Transcription" ;
    mava:valueDescription "transcript" .

Export

Export the current graph to a Turtle file.

Export the graph when finished
╰─❯ just api export
>> Exporting graph to 'examples/output/export.ttl'...
curl -sS -o examples/output/export.ttl http://localhost:8000/graph/export
Done.

Clear

Clear the current graph to start from scratch.

Clear the graph after export
╰─❯ just api clear
>> Clearing graph...
curl -sS -X DELETE http://localhost:8000/graph/clear | jq
{
  "message": "Graph cleared successfully"
}