Predicates¶

class authorityspoke.predicates.Predicate(template, truth=True)¶

A statement about real events or about a legal conclusion.

Should contain an English-language phrase in the past tense. The past tense is used because legal analysis is usually backward-looking, determining the legal effect of past acts or past conditions.

Don’t use capitalization or end punctuation to signal the beginning or end of the phrase, because the phrase may be used in a context where it’s only part of a longer sentence.

If you need to mention the same term more than once in a Predicate, use the same placeholder for that term each time. If you later create a Fact object using the same Predicate, you will only include each unique term once.

>>> # the template has two placeholders referring to the identical term
>>> Predicate("$applicant opened a bank account for $applicant and $cosigner")

Sometimes, a Predicate or Comparison needs to mention two terms that are different from each other, but that have interchangeable positions in that particular phrase. To convey interchangeability, the template string should use identical text for the placeholders for the interchangeable terms, except that the different placeholders should each end with a different digit.

>>> # the template has two placeholders referring to different but interchangeable terms
>>> Predicate("$relative1 and $relative2 both were members of the same family")

Parameters

template (str) – a clause containing an assertion in English in the past tense, with placeholders showing where references to specific Factors from the case can be inserted to make the clause specific. This string must be a valid Python string.Template.
truth (Optional[bool]) – indicates whether the clause in content is asserted to be true or false. None indicates an assertion as to “whether” the clause is true or false, without specifying which.

__init__(template, truth=True)¶

Clean up and test validity of attributes.

If the content sentence is phrased to have a plural context factor, normalizes it by changing “were” to “was”.

__repr__()¶: Return repr(self).

content_with_terms(context)¶

Make a sentence by filling in placeholders with names of Factors.

Parameters: context (Union[Factor, Sequence[Factor]]) – Factors to be mentioned in the context of this Predicate. They do not need to be type Entity
Return type: str
Returns: a sentence created by substituting string representations Factors for the placeholders in the content template

contradicts(other)¶

Test whether other and self have contradictory meanings.

This is determined only by the truth value, the exact template content, and whether the placeholders indicate interchangeable terms.

Return type: bool

same_content_meaning(other)¶

Test if content strings of self and other have same meaning.

This once was used to disregard differences between “was” and “were”, but that now happens in Predicate.__post_init__().

Parameters: other (Predicate) – another Predicate being compared to self
Return type: bool
Returns: whether self and other have content strings similar enough to be considered to have the same meaning.

means(other)¶

Test whether self and other have identical meanings.

To return True, other can be neither broader nor narrower.

Return type: bool

__gt__(other)¶

Test whether self implies other.

Return type: bool
Returns: whether self implies other, which is True if their statements about quantity imply it.

implies(other)¶

Test whether self implies other.

Return type: bool

__ge__(other)¶

Return self>=value.

Return type: bool

__len__()¶

Also called the linguistic valency, arity, or adicity.

Returns: the number of entities that can fit in the pairs of brackets in the predicate. self.expression doesn’t count as one of these entities, even though the place where self.expression goes in represented by brackets in the self.content string.

negated()¶

Copy self, with the opposite truth value.

Return type: Predicate

term_positions()¶

Create list of positions that each term could take without changing Predicate’s meaning.

Assumes that if placeholders are the same except for a final digit, that means they’ve been labeled as interchangeable with one another.

term_index_permutations()¶

Get the arrangements of all this Predicate’s terms that preserve the same meaning.

Return type: List[List[int]]

__str__()¶: Return str(self).

__weakref__¶: list of weak references to the object (if defined)

class authorityspoke.predicates.Comparison(template, sign='=', expression=0, truth=True)¶

A Predicate that compares a described quantity to a constant.

The Comparison class extends the concept of a Predicate. A Comparison still contains a truth value and a template string, but that template should be used to identify a quantity that will be compared to an expression using a sign such as an equal sign or a greater-than sign. This expression must be a constant: either an integer, a floating point number, or a physical quantity expressed in units that can be parsed using the pint library.

To encourage consistent phrasing, the template string in every Comparison object must end with the word “was”.

If you phrase a Comparison with an inequality sign using truth=False, AuthoritySpoke will silently modify your statement so it can have truth=True with a different sign. In this example, the user’s input indicates that it’s false that the weight of marijuana possessed by a defendant was more than 10 grams. AuthoritySpoke interprets this to mean it’s true that the weight was no more than 10 grams.

>>> # example comparing a pint Quantity
>>> drug_comparison_with_upper_bound = Comparison(
>>>     "the weight of marijuana that $defendant possessed was",
>>>     sign=">",
>>>     expression="10 grams",
>>>     truth=False)
>>> str(drug_comparison_with_upper_bound)
'that the weight of marijuana that $defendant possessed was no more than 10 gram'

When the number needed for a Comparison isn’t a physical quantity that can be described with the units in the pint library library, you should phrase the text in the template string to explain what the number describes. The template string will still need to end with the word “was”. The value of the expression parameter should be an integer or a floating point number, not a string to be parsed.

>>> # example comparing an integer
>>> three_children = Comparison(
>>>     "the number of children in ${taxpayer}'s household was",
>>>     sign="=",
>>>     expression=3)
>>> str(three_children)
"that the number of children in ${taxpayer}'s household was exactly equal to 3"

Parameters

sign (str) – A string representing an equality or inequality sign like ==, >, or <=. Used to indicate that the clause ends with a comparison to some quantity. Should be defined if and only if a quantity is defined. Even though “=” is the default, it’s the least useful, because courts almost always state rules that are intended to apply to quantities above or below some threshold.
quantity – a Python number object or ureg.Quantity from the pint library. Comparisons to quantities can be used to determine whether Predicates imply or contradict each other. A single Predicate may contain no more than one sign and one quantity.

__init__(template, sign='=', expression=0, truth=True)¶

Clean up and test validity of attributes.

If the content sentence is phrased to have a plural context factor, normalizes it by changing “were” to “was”.

__repr__()¶: Return repr(self).

classmethod read_quantity(value)¶

Create numeric expression from text for Comparison class.

This expression can be a datetime.date, an int, a float, or a pint quantity. (See pint tutorial)

Parameters: quantity – an object to be interpreted as the expression field of a Comparison
Return type: Union[date, float, int, Quantity]
Returns: a Python number object or a pint.Quantity object created with pint.UnitRegistry.

consistent_dimensionality(other)¶

Test if other has a quantity parameter consistent with self.

Return type: bool

implies(other)¶

Test whether self implies other.

Return type: bool

means(other)¶

Test whether self and other have identical meanings.

To return True, other can be neither broader nor narrower.

Return type: bool

contradicts(other)¶

Test whether other and self have contradictory meanings.

If the checks in the Predicate class find no contradiction, this method looks for a contradiction in the dimensionality detected by the pint library, or in the possible ranges for each Comparison’s numeric expression.

Return type: bool

negated()¶

Copy self, with the opposite truth value.

Return type: Comparison

expression_comparison()¶

Convert text to a comparison with a quantity.

Return type: str
Returns: string representation of a comparison with a quantity, which can include units due to the pint library.

excludes_other_quantity(other)¶

Test if quantity ranges in self and other are non-overlapping.

Return type: bool

includes_other_quantity(other)¶

Test if the range of quantities mentioned in self is a subset of other’s.

Return type: bool