eta.util.general

Generic utility functions for various basic data types.

Functions

append	Append each sublist within lst together, creating a single combined list.
argmax	Select the n top values in a given list, according to a list of scores for each list element.
atom	Check whether an input is an atom (either empty list or a non-list).
certainty_to_period	Map a certainty in [0,1] to a period (in seconds) that an expected event should occur within.
clear_symtab	Clear the symbol table used for creating new symbols.
cons	Insert a value to the front of a list or set.
cons_dict	Add v to the list at key k in dct, creating a new list if none exists.
dict_get	Safe version of dict accessor that returns an empty list if key is not found.
dict_rem	Safe version of dict pop that removes a key from the dict.
dict_rem_val	Safe version of dict remove that removes val from the list stored at key (or pops the key if it stores an atom).
dict_substall_keys	Given a set of replacements, make a substitution to the keys in a dict for each replacement.
dual_var	Given an episode variable like ?e1, return the non-fluent dual of that variable, e.g., !e1 (and vice-versa).
duplicate_var	Duplicate a variable by generating a new variable symbol with the initial variable (excluding trailing numbers) as a prefix.
episode_name	Generate a new episode name.
episode_var	Generate a new episode variable.
escaped_symbol_p	Check if a given symbol is an "escaped" symbol, equivalent to vertical bars in LISP.
extract_category	Recurse through a (possibly nested) list and extract categories that satisfy a given function.
flatten	Recursively flatten a list, creating a single list with no sub-lists.
gentemp	Generate a unique symbol that hasn't been used before by appending an integer suffix i and then incrementing i.
get_keyword_contents	Get the contents immediately following each keyword in keys from a list.
has_elapsed_certainty_period	Check whether a given time delta has elapsed the period corresponding to a given certainty.
indent	Indent a string some number of levels.
isquote	Check if a given input is a quoted expression.
linsum	Compute a linear sum of a list of vectors, scaling each vector by the corresponding coefficient.
listp	Check whether an input is a list (including the empty list).
normalize	Normalize a vector to sum to 1.
push	Insert a value to the end of a list or set.
random_element	Select a random element from a list.
rec_find	Return subexpressions in a tree that are the same as the given symbol.
rec_find_if	Return subexpressions in a tree that satisfy cndfn.
rec_remove	Recursively remove a given target from a list.
rec_replace	Recursively replace some old value with a new value throughout a list.
remove_duplicates	Remove duplicate items in a list, preserving the initial order of order is given as True.
remove_nil	Remove any null values from a list.
replaceall	Make a list of replacements to a given string in sequence.
split_by_cond	Split a list by a given condition function.
squash	Squash each number within a vector to be within the given range.
standardize	Standardize a string by applying a series of transformations.
subst	Recursively substitute b for a throughout a list.
substall	Given a set of replacements, make a substitution in a list for each replacement.
symbolp	Check if a given variable is a "symbol" (i.e., a string).
to_key	Convert a list to a valid dict key consisting of only tuples and strings.
variablep	Check if a given input is a variable symbol, i.e., starts with '?' or '!'.

clear_symtab()

Clear the symbol table used for creating new symbols.

gentemp(str)

Generate a unique symbol that hasn’t been used before by appending an integer suffix i and then incrementing i.

Parameters:

str (str) – String to use for symbol generation.

Returns:

A “symbol” with a unique integer suffix attached to the given string.

Return type:

str

Notes

This currently relies on an external symbol table stored in a file, which exploits the fact that race conditions with a shared file cannot occur with Python multiprocess (see: https://superfastpython.com/multiprocessing-race-condition-python/#Race_Condition_With_Shared_Data-2) However, this is somewhat clumsy/inefficient and should eventually be replaced by a proper solution.

episode_name()

Generate a new episode name.

episode_var()

Generate a new episode variable.

escaped_symbol_p(s)

Check if a given symbol is an “escaped” symbol, equivalent to vertical bars in LISP.

symbolp(s)

Check if a given variable is a “symbol” (i.e., a string).

variablep(s)

Check if a given input is a variable symbol, i.e., starts with ‘?’ or ‘!’.

Notes

For now, this excludes indexical variables, such as ‘^you’.

dual_var(ep_var)

Given an episode variable like ?e1, return the non-fluent dual of that variable, e.g., !e1 (and vice-versa).

duplicate_var(var)

Duplicate a variable by generating a new variable symbol with the initial variable (excluding trailing numbers) as a prefix.

replaceall(str, replist)

Make a list of replacements to a given string in sequence.

Parameters:

• str (str) – A string whose contents should be replaced.

• replist (list[tuple]) –

  A list of replacements to make. A replacement is a tuple of one of the following forms:

  • (old, new)

  • (old, new, is_regex)

  If is_regex is given as True for a tuple, the old and new values are interpreted as regex strings.

Return type:

str

indent(n)

Indent a string some number of levels.

standardize(str, remove_parentheticals=False)

Standardize a string by applying a series of transformations.

Specifically:

1. Replace – with -, and _ with whitespace.

2. Remove parenthetical content (i.e., […] or …), if remove_parentheticals is True.

3. Add whitespace around all punctuation.

4. Collapse all whitespace to a single space.

5. Convert to lowercase.

isquote(s)

Check if a given input is a quoted expression.

rec_replace(old, new, lst)

Recursively replace some old value with a new value throughout a list.

rec_remove(target, lst)

Recursively remove a given target from a list.

listp(lst)

Check whether an input is a list (including the empty list).

cons(lst1, lst2)

Insert a value to the front of a list or set.

Parameters:

• lst1 (object) – An object (possibly a sublist) to insert.

• lst2 (list[object], set[object], or object) – A list, set, or object to cons the given object to.

Return type:

list[object] or set[object]

push(lst1, lst2)

Insert a value to the end of a list or set.

Parameters:

• lst1 (object) – An object (possibly a sublist) to insert.

• lst2 (list[object], set[object], or object) – A list, set, or object to push the given object to.

Return type:

list[object] or set[object]

atom(lst)

Check whether an input is an atom (either empty list or a non-list).

append(lst)

Append each sublist within lst together, creating a single combined list.

flatten(lst)

Recursively flatten a list, creating a single list with no sub-lists.

remove_duplicates(lst, order=False)

Remove duplicate items in a list, preserving the initial order of order is given as True.

remove_nil(lst)

Remove any null values from a list.

subst(a, b, lst)

Recursively substitute b for a throughout a list.

substall(lst, replist)

Given a set of replacements, make a substitution in a list for each replacement.

random_element(lst)

Select a random element from a list.

get_keyword_contents(lst, keys)

Get the contents immediately following each keyword in keys from a list.

to_key(lst)

Convert a list to a valid dict key consisting of only tuples and strings.

split_by_cond(lst, cndfn)

Split a list by a given condition function.

Parameters:

• lst (list) –

• cndfn (function) –

Returns:

• filtered (list) – The input list with elements matching cndfn filtered out.

• matching (list) – A list of elements from the input list matching cndfn.

extract_category(lst, catfn, ignfn=None)

Recurse through a (possibly nested) list and extract categories that satisfy a given function.

Parameters:

• lst (s-expr) –

• catfn (function) – A function used to match categories to be extracted.

• ignfn (function, optional) – If given, a function used to ignore matching subexpressions (i.e., avoid recursing within them).

Returns:

• lst_new (s-expr) – The input list with matching subexpressions removed.

• categories (list[s-expr]) – A list of extracted matching subexpressions.

rec_find(lst, x, test=<function <lambda>>)

Return subexpressions in a tree that are the same as the given symbol.

A different binary function can be provided using the test argument.

rec_find_if(lst, cndfn)

Return subexpressions in a tree that satisfy cndfn.

dict_substall_keys(dct, replist)

Given a set of replacements, make a substitution to the keys in a dict for each replacement.

cons_dict(dct, k, v)

Add v to the list at key k in dct, creating a new list if none exists.

dict_get(dct, k)

Safe version of dict accessor that returns an empty list if key is not found.

dict_rem_val(dct, k, val)

Safe version of dict remove that removes val from the list stored at key (or pops the key if it stores an atom).

dict_rem(dct, k)

Safe version of dict pop that removes a key from the dict.

squash(vector, range=(0, 1))

Squash each number within a vector to be within the given range.

normalize(vector)

Normalize a vector to sum to 1.

linsum(vectors, coeffs)

Compute a linear sum of a list of vectors, scaling each vector by the corresponding coefficient.

argmax(lst, scores, n)

Select the n top values in a given list, according to a list of scores for each list element.

certainty_to_period(certainty)

Map a certainty in [0,1] to a period (in seconds) that an expected event should occur within.

The proportion between the period and the quantity -log(1 - certainty) is determined by the global constant EXPECTED_STEP_FAILURE_PERIOD_COEFFICIENT, defined in eta.constants.

Parameters:

certainty (float) – A certainty value in [0,1]

Returns:

The period (in seconds), or infinity if the certainty is 1.

Return type:

float or np.inf

has_elapsed_certainty_period(time, certainty)

Check whether a given time delta has elapsed the period corresponding to a given certainty.

Parameters:

• time (float) – The difference between two times (POSIX timestamps).

• certainty (float) – A certainty value in [0,1]

Return type:

bool