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()[source]

Clear the symbol table used for creating new symbols.

gentemp(str)[source]

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()[source]

Generate a new episode name.

episode_var()[source]

Generate a new episode variable.

escaped_symbol_p(s)[source]

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

symbolp(s)[source]

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

variablep(s)[source]

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)[source]

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

duplicate_var(var)[source]

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

replaceall(str, replist)[source]

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)[source]

Indent a string some number of levels.

standardize(str, remove_parentheticals=False)[source]

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)[source]

Check if a given input is a quoted expression.

rec_replace(old, new, lst)[source]

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

rec_remove(target, lst)[source]

Recursively remove a given target from a list.

listp(lst)[source]

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

cons(lst1, lst2)[source]

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)[source]

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)[source]

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

append(lst)[source]

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

flatten(lst)[source]

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

remove_duplicates(lst, order=False)[source]

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

remove_nil(lst)[source]

Remove any null values from a list.

subst(a, b, lst)[source]

Recursively substitute b for a throughout a list.

substall(lst, replist)[source]

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

random_element(lst)[source]

Select a random element from a list.

get_keyword_contents(lst, keys)[source]

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

to_key(lst)[source]

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

split_by_cond(lst, cndfn)[source]

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)[source]

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>>)[source]

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)[source]

Return subexpressions in a tree that satisfy cndfn.

dict_substall_keys(dct, replist)[source]

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

cons_dict(dct, k, v)[source]

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

dict_get(dct, k)[source]

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

dict_rem_val(dct, k, val)[source]

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)[source]

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

squash(vector, range=(0, 1))[source]

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

normalize(vector)[source]

Normalize a vector to sum to 1.

linsum(vectors, coeffs)[source]

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

argmax(lst, scores, n)[source]

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

certainty_to_period(certainty)[source]

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)[source]

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