User Documentation

Run RDFMutate

We assume you obtained RDFMutate as a JAR file rdfmutate-<version>.jar using one of the options described on the Installation page. For the sake of clarity, we use rdfmutate.jar as the name of the JAR file.

You can run RDFMutate using the following command:

java -jar rdfmutate.jar --config=<configuration-file>

<configuration-file> is the path of a configuration file in yaml format, which contains all information on how to run the graph generation. The next section contains information how this file needs to be structured.

We are using logback as a logging framework and the default logging level is "info" (see src/main/resources/logback.xml). If you want to change the logging level, in particular for our logger org.smolang.robust.RDFMutate, you can provide your own logging configuration as a file by running the JAR as follows:

java -Dlogback.configurationFile=<logback-config-file> -jar rdfmutate.jar --config=<configuration-file>

Configuration File

RDFmutant expects one command line argument specifying the configuration file that describes the mutation that should be performed. Configuration files contain all the information necessary to perform a mutation. The files use the yaml format. We first show the mandatory elements before discussing all possible elements.

Minimal Configuration File

To use the minimal configuration elements, set the argument strict_parsing to false. This allows RDFMutate to use default values for elements that are not provided. The following elements need to be contained in the configuration file:

• seed_graph:
  • contains information about the RDF graph that is used as the seed to start mutating
  • mandatory element file: path, where to find the file containing the RDF graph
• output_graph:
  • contains information where to save the generated RDF graph
  • mandatory element file: path, where to save the file containing the RDF graph
  • default behavior: if the output file does already exists, no mutant is generated
• number_of_mutations: an integer specifying how many mutation operators should be applied to generate the mutant
• mutation_operators:
  • a list of all the mutation operators that should be considered for the mutation
  • elements in the list can either be file resources or java modules
  • resource elements:
    • contain files from which the mutation operators are imported
    • mandatory element file: path, where to find the file containing the mutation operators
    • mandatory element syntax: syntax of the encoding of the operators (see also Mutation Operator Specification)

Example

Here is an example of such a minimal configuration file.

strict_parsing: false

seed_graph:
    file: examples/wiki/minimal/simpleKG.ttl
    
output_graph:
    file: examples/wiki/minimal/outputKG.ttl
    
number_of_mutations: 1

mutation_operators:
    - resource:
        file: examples/wiki/minimal/addRelation.ttl
        syntax: swrl

Further Elements

General Options

• print_summary:
  • is a boolean option (true / false); default: false
  • if set to true, the tool outputs a summary of the performed mutation operations after generating the mutant
• strict_parsing:
  • is a boolean option (true / false); default: true
  • if set to false, the tool assumes default values for some of the elements that are not provided. If set to true the parsing is more strict, outputting a warning instead of generating a mutant if not all elements are specified.
• number_of_mutants:
  • requires an integer; default: 1
  • the number of mutant RDF graphs that are generated. If more than one mutant is requested, a number is appended to the file provided in output_graph. E.g. for file file = exampleOutput.ttl and 5 mutants requested, the files would be named exampleOutput0.ttl ,..., exampleOutput4.ttl.
  • use this option to generate mutants in batches, which is more efficient than loading the application for each mutant individually

File Options

There are several arguments that can be provided for the seed_graph and output_graph.

• type:
  • the type of the file, which is necessary to select the correct parsers
  • can be either rdf for general rdf files, i.e. all RDF serializations supported by Apache Jena, or owl for RDF graphs representing OWL ontologies. In particular, owl needs to be selected if files in OWL functional syntax are used.
  • can be provided for both, seed_graph and output_graph
• overwrite_output:
  • is a boolean option (true / false); default: false
  • defines the behavior if the file for the output graph already exists. If set to true the existing file is replaced with the generated graph.

Additional Elements

• All options to specify mutation operators are documented in file for Mutation Operators
• All options to specify conditions that the mutant need to satisfy are documented in file for Mask Specification.
• strategy
  • defines the strategy that should be used when selecting mutation operators in order to generate a mutant that satisfies the provided constraints. At the moment, RDFMutate only provides one strategy, which is random selection of mutation operators. For implementing custom strategies, consult the Developer Documentation.
  • A strategy has two elements:
    • name: the name of the strategy; default: random
    • seed: a number that is forwarded to the strategy, e.g. as the seed for a random number generator

Example

The following is an example of a configuration file that contains all the elements that are allowed. Note, that it might take RDFMutate a few tries to generate a mutant that satisfies (all aspects of) the condition.

strict_parsing: true
print_summary: true

seed_graph:
    file: examples/wiki/allFeatures/simpleKG.ttl
    type: rdf
    
output_graph:
    file: examples/wiki/allFeatures/outputKG.ttl
    overwrite: true 
    type: rdf
    
number_of_mutations: 10

number_of_mutants: 1

strategy:
    name: random
    seed: 42
      
mutation_operators:
    - module:
        location: org.smolang.robust.mutant.operators
        operators: 
            - className: AddSubclassRelationMutation
            - className: AddObjectPropertyRelationMutation
    - resource:
        file: examples/wiki/allFeatures/addRelation.ttl
        syntax: swrl

condition:
    reasoning:
        consistency: true
        reasoner: hermit
    masks:
        - file: examples/wiki/allFeatures/AsubClassOfB.ttl
        - file: examples/wiki/allFeatures/AsubClassOfC.ttl