Utility Methods#

A collection of convenient helper-functions.

class theodias.util.TauJSONEncoder#

Methods

`default`(o)	An implementation of `JSONEncoder.default()`.
`encode`(o)	Return a JSON string representation of a Python data structure.
`iterencode`(o[, _one_shot])	Encode the given object and yield each string representation as available.

__init__(serialize_implementation=False, **kwargs)#

Constructor for JSONEncoder, with sensible defaults.

If skipkeys is false, then it is a TypeError to attempt encoding of keys that are not str, int, float or None. If skipkeys is True, such items are simply skipped.

If ensure_ascii is true, the output is guaranteed to be str objects with all incoming non-ASCII characters escaped. If ensure_ascii is false, the output can contain non-ASCII characters.

If check_circular is true, then lists, dicts, and custom encoded objects will be checked for circular references during encoding to prevent an infinite recursion (which would cause an RecursionError). Otherwise, no such check takes place.

If allow_nan is true, then NaN, Infinity, and -Infinity will be encoded as such. This behavior is not JSON specification compliant, but is consistent with most JavaScript based encoders and decoders. Otherwise, it will be a ValueError to encode such floats.

If sort_keys is true, then the output of dictionaries will be sorted by key; this is useful for regression tests to ensure that JSON serializations can be compared on a day-to-day basis.

If indent is a non-negative integer, then JSON array elements and object members will be pretty-printed with that indent level. An indent level of 0 will only insert newlines. None is the most compact representation.

If specified, separators should be an (item_separator, key_separator) tuple. The default is (’, ‘, ‘: ‘) if indent is None and (‘,’, ‘: ‘) otherwise. To get the most compact JSON representation, you should specify (‘,’, ‘:’) to eliminate whitespace.

If specified, default is a function that gets called for objects that can’t otherwise be serialized. It should return a JSON encodable version of the object or raise a TypeError.

default(o)#

An implementation of JSONEncoder.default().

This implementation handles the serialization of Position and DialecticalStructure instances.

theodias.util.arg_to_cnf(argument)#

Convert a list representation of an argument to a cnf-position-like list of negated premises and a non-negated conclusion.

Parameters:: argument (List[int]) – An integer list representing an argument where the last element is
Return type:: List[int]

assumed to be the conclusion of the preceding premises.

Return type:: List[int]
Returns:: the converted integer list with negated premises and a
Parameters:: argument (List[int]) –

non-negated conclusion.

theodias.util.args_to_cnf(arguments, n_sentence_pool)#

Convert arguments to conjunctive normal form of pysat.formula.CNF

Sentences \(p\) that are not used in arguments will be added in a tautological manner (i.e., \(p\vee\neg p\)) to the CNF formula.

Parameters:

arguments (List[List[int]]) –
n_sentence_pool (int) – the number of different sentence (without counting their negations)

Return type:

CNF

Returns:

a CNF formula

theodias.util.create_random_argument_list(n_arguments_min, n_arguments_max, n_sentences, n_premises_max, n_premises_weights=None)#

Create a list of random arguments.

A convenience function that uses create_random_arguments() to create a random list of arguments. Instead of specifying a fixed number of desired arguments, the number of arguments randomly falls between n_arguments_min and n_arguments_max.

Parameters:

n_arguments_min (int) – the minimal number of arguments
n_arguments_max (int) – the maximal number of arguments
n_sentences (int) – the number of sentences (without counting their negations)
n_premises_max (int) – the maximal number of premises per argument
n_premises_weights (Optional[List[float]]) – If None (default), the distribution of randomly choosing the number of premises in an argument is uniform. Otherwise the given weights will be used to choose a number of premises between 1 and n_max_premises.

Return type:

List[List[int]]

Returns:

A list of argument as integer lists.

theodias.util.create_random_arguments(n_sentences, n_arguments, n_max_premises, n_principles=0, variation=True, n_premises_weights=None, connected=True, use_all_sentences=False, max_loops=1000)#

Return a list of randomly generated arguments represented as integer lists.

The dialectical structure given by the returned arguments is satisfiable (i.e. there is at least one complete and dialectically consistent position). Furthermore, the arguments avoid begging the question, repeating premises, flat contradictions among premises and with the conclusion, and using the same premises for different conclusions.

Parameters:

n_sentences (int) – Number of non-negated sentences of the sentence pool. Every sentence (or its negation) occurs at least once in an argument.
n_arguments (int) – Number of generated arguments.
n_max_premises (int) – Maximal number of premises per argument.
n_principles (int) – The number of principles, i.e. sentences that may occur in arguments as premises only.
variation (bool) – If True (default), the number of premises per argument is chosen randomly. Otherwise it is constantly n_max_premises.
n_premises_weights (Optional[List[float]]) – If None (default), the distribution of randomly choosing the number of premises in an argument is uniform. Otherwise the given weights will be used to choose a number of premises between 1 and n_max_premises.
connected: – If true (default), the arguments are related (either by attack or support) to at least one other argument in the structure.
use_all_sentences (bool) – If True, the algorithm returns only dialectical structures that include each sentence, or its negation respectively, in the arguments.
max_loops (bool) – Breaks possibly endless loops. Number of arguments that tested whether they fit into the dialectical structure. If the algorithm takes longer a RuntimeWarning is raised.
connected (bool) –

Return type:

List[List[int]]

Returns:

A list of argument as integer lists.

theodias.util.get_principles(arguments)#

” Get the principles and their multiplicity for a list of arguments.

A sentence counts as a principle if and only if it occurs in at least one argument as premise and it or its negation does not occur as a conclusion in an argument. The multiplicity is the count of arguments in which the sentence occurs as premise.

Parameters:: arguments (List[List[int]]) – a list of integer list representing arguments. Each integer
Return type:: List[Tuple[int, int]]

list represents an argument where the last element is assumed to be the conclusion of the preceding premises.

Return type:: List[Tuple[int, int]]
Returns:: a list of tuples of the form (principle, multiplicity) with
Parameters:: arguments (List[List[int]]) –

multiplicity indicating the multiplicity of the principle.

theodias.util.inferential_density(dialectical_structure)#

Return the inferential density of a dialectical structure \(\tau\) as defined by Betz (2013, Debate Dynamics, p. 44): \(D(\tau) = \frac{n-log_{2}(\sigma)}{n}\), where \(\sigma(\tau)\) is the number of complete and dialectically consistent positions of :math:` au`.

Parameters:: dialectical_structure (DialecticalStructure) – An instance of DialecticalStructure
Return type:: float
Returns:: a value between 0 and 1 if the dialectical structure has complete

and consistent extensions. Otherwise, a ValueError is raised.

theodias.util.is_satisfiable(arguments, principles=None)#

Check whether some arguments and principles are satisfiable when taken together.

Parameters:

arguments (List[List[int]]) – A list of integer lists. Each integer list represents an argument where
principles (List[int] | None) –

Return type:

bool

the last element is assumed to be the conclusion of the preceding premises. :type principles: Optional[List[int]] :param principles: An optional list of integers representing principles as additional constraints.

Return type:

bool

Returns:

True if the arguments and the principles are satisfiable.

Parameters:

arguments (List[List[int]]) –
principles (List[int] | None) –

Otherwise, :code:`False`is returned.

theodias.util.number_of_complete_consistent_positions(arguments, n_unnegated_sentence_pool)#

Calculate the number of complete and consistent positions in a dialectical structure.

Parameters:

arguments (List[List[int]]) – a list of integer list representing arguments of the dialectical
n_unnegated_sentence_pool (int) –

Return type:

int

structure. Each integer list represents an argument where the last element is assumed to be the conclusion of the preceding premises. :type n_unnegated_sentence_pool: int :param n_unnegated_sentence_pool: the number of different sentences in the dialectical structure (without counting their negations).

Return type:

int

Returns:

the number of complete and consistent positions

Parameters:

arguments (List[List[int]]) –
n_unnegated_sentence_pool (int) –

theodias.util.random_dialectical_structures(n_dialectical_structures, n_arguments_min, n_arguments_max, n_sentences, n_premises_max, module_name='theodias.core', class_name='DAGDialecticalStructure')#

Create a list of randomly generated dialectical structures.

A convenience function that uses create_random_argument_list() to create instances of base.DialecticalStructure. The implementing class can be specified via the method’s arguments.

Parameters:

n_dialectical_structures (int) – The number of dialectical structures to be generated
n_arguments_min (int) – the minimal number of arguments per dialectical structure
n_arguments_max (int) – the maximal number of arguments per dialectical structure
n_sentences (int) – the number of the number of sentences (without counting their negations)
n_premises_max (int) – the maximal number of premises per argument
module_name (str) – the name of the module from which the class of the dialectical structure will be imported (default: rethon.model)
class_name (str) –
the name of the dialectical structure class (default: DAGDialecticalStructure)

returns:

An iterator over random dialectical structures.

Return type:

Iterator[DialecticalStructure]

theodias.util.random_position_as_set(n_sentences, allow_empty_position=False)#

Generates a random minimally consistent position in its set-representation.

Return type:

Set[int]

Parameters:

n_sentences (int) – Size of the sentence-pool (without negations).
allow_empty_position (bool) – Iff True an empty position might be returned.

Returns:

A set of integer representing the position.

theodias.util.random_positions(n_sentences, k=1, allow_empty_position=False)#

Randomly generate minimally consistent positions in their set-representation.

Parameters:

n_sentences (int) – Size of the sentence-pool (without negations).
k (int) – Sample size.
allow_empty_position (bool) – If and only if True, an empty position might be returned.

Return type:

List[Set[int]]

Returns:

A list of random positions as integer sets.

Raises:

ValueError – if k exceeds the number of minimally consistent positions given n_sentences.

theodias.util.tau_decoder(json_obj, use_json_specified_type=False, position_module='theodias', position_class='StandardPosition', dialectical_structure_module='theodias', dialectical_structure_class='BDDDialecticalStructure')#

Object hook for json.loads() and json.load().

Parameters:: use_json_specified_type – If True the method uses the implementation details (modulename and classname) that are specified in the json string, if there are any. Otherwise, the method uses implementation details as specified the other given parameters.

theodias.util.tau_dump(re_object, fp, cls=<class 'theodias.util.TauJSONEncoder'>, serialize_implementation=False, **kwargs)#

Saving an object as JSON-String in a file.

This is a convenient method that calls json.dump() with TauJSONEncoder as its default encoder, which will handle the JSON serialization of Position and DialecticalStructure instances.

**kwargs will be given to json.dumps()

Parameters:: serialize_implementation – If True implementation details (modulename and classname) will be serialized.
Returns:: The object as a JSON string.

theodias.util.tau_dumps(re_object, cls=<class 'theodias.util.TauJSONEncoder'>, serialize_implementation=False, **kwargs)#

Get an object as JSON-String.

This is a convenient method that calls json.dumps() with TauJSONEncoder as its default encoder, which will handle the JSON serialization of Position and DialecticalStructure.

**kwargs will be given to json.dumps()

Parameters:: serialize_implementation – If True implementation details (modulename and classname) will be serialized.
Returns:: The object as a JSON string.

theodias.util.tau_load(fp, use_json_specified_type=False, position_module='theodias.core', position_class='StandardPosition', dialectical_structure_module='theodias.core', dialectical_structure_class='BDDDialecticalStructure')#

Load an object from a JSON file.

This is a convenient method that calls json.load() and uses tau_decoder() as object hook to handle the instantiation of Position and DialecticalStructure objects. Desired implementation details can be given by parameter values (see tau_decoder()).

Note

Per default, positions will be instantiated as StandardPosition and dialectical structures as BDDDialecticalStructure (to avoid long instantiation times).

theodias.util.tau_loads(json_obj, use_json_specified_type=False, position_module='theodias', position_class='StandardPosition', dialectical_structure_module='theodias', dialectical_structure_class='BDDDialecticalStructure')#

Load an object from a JSON string.

This is a convenient method that calls json.loads() and uses tau_decoder() as object hook to handle the instantiation of Position and DialecticalStructure objects. Desired implementation details can be given by parameter values (see tau_decoder()).

Note

Per default positions will be instantiated as NumpyPosition and dialectical structures as BDDNumpyDialecticalStructure (to avoid long instantiation times).

theodias.util.write_as_dot(arguments, directory, file_name, equal_rank_for_principles=False)#

Create a graphical representation of a dialectical structure and save it as .dot-file.

Parameters:

arguments – a list of integer list representing arguments of the dialectical structure. Each integer list represents an argument where the last element is assumed to be the conclusion of the preceding premises.
directory (str) – the full path to where the .dot-file should be saved
file_name (str) – the name of the .dot-file
equal_rank_for_principles (bool) – if True, an equal rank is assigned to the principles

Returns:

None

theodias.util.write_as_tex(arguments, directory, file_name)#

Create a simple graphical representation of a dialectical structure and save it as .tex-file.

Parameters:

arguments (List[List[int]]) – a list of integer list representing arguments of the dialectical structure. Each integer list represents an argument where the last element is assumed to be the conclusion of the preceding premises.
directory (str) – the full path to where the .tex-file should be saved
file_name (str) – the name of the .tex-file

Return type:

None

Returns:

None