topologicpy.Helper module

class topologicpy.Helper.Helper

Bases: object

General-purpose helper methods used throughout TopologicPy.

Methods

`BinAndAverage`(listA[, mantissa, tolerance, ...])	Groups numbers within a specified tolerance into bins, calculates the average of each bin, and returns a sorted list of these averages.
`CheckVersion`([library, version, silent])	Compares an input version with the latest version of a Python library available on PyPI.
`ClosestMatch`(item, listA)	Returns the index of the closest match in the input list to the input item.
`ClusterByKeys`(elements, dictionaries, *keys)	Clusters the input list of elements and dictionaries based on the input key or keys.
`Flatten`(listA)	Flattens the input nested list.
`Grow`(seed_idx, group_size, adjacency, ...)	Attempts to grow a spatially connected group of a specified size starting from a given seed index.
`Iterate`(listA)	Iterates the input nested list so that each sublist has the same number of members.
`MakeUnique`(listA)	Forces the strings in the input list to be unique if they have duplicates.
`MaximumIndices`(listA[, silent])	Returns a list of indices of the maximum value in the input list.
`MergeByThreshold`(listA[, threshold])	Merges the numbers in the input list so that numbers within the input threshold are averaged into one number.
`MinimumIndices`(listA[, silent])	Returns a list of indices of the minimum value in the input list.
`Normalize`(listA[, mantissa])	Normalizes the input list so that it is in the range 0 to 1
`Position`(item, listA)	Returns the position of the item in the list or the position it would have been inserts.
`RemoveEven`(listA)	Removes the even indexed members of the input list.
`RemoveOdd`(listA)	Removes the odd indexed members of the input list.
`Repeat`(listA)	Repeats the input nested list so that each sublist has the same number of members.
`SampleIndices`(values, samples[, silent])	Returns original indices at evenly spaced ranks of the sorted values.
`Sort`(listA, *otherLists[, reverseFlags, silent])	Sorts the first input list according to the values in the subsequent input lists in order.
`TopPercentIndices`(values, percent)	Returns the indices of the highest values corresponding to the specified percentage of the input list.
`TransferDictionariesByKey`(topologies, ...[, ...])	Transfers dictionaries from selectors to matching topologies using a shared dictionary key.
`Transpose`(listA)	Transposes the input list (swaps rows and columns).
`Trim`(listA)	Trims the input nested list so that each sublist has the same number of members.
`Version`([check, silent])	Returns the current version of the software.

static BinAndAverage(listA, mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False)

Groups numbers within a specified tolerance into bins, calculates the average of each bin, and returns a sorted list of these averages.

Parameters

listAlist: The input list.
mantissaint , optional: The desired length of the mantissa. Default is 6
tolerancefloat , optional: The desired tolerance. Default is 0.0001.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

list: The sorted list of bin averages.

static CheckVersion(library: str = None, version: str = None, silent: bool = False)

Compares an input version with the latest version of a Python library available on PyPI.

Parameters

librarystr, optional: The input Python library name. Default is None.
versionstr, optional: The input software version number to compare. Default is None.
silentbool, optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

str: A message indicating whether the input version is older than, equal to, or newer than the latest version available on PyPI. Returns None if the version check cannot be completed.

static ClosestMatch(item, listA)

Returns the index of the closest match in the input list to the input item. This works for lists made out of numeric or string values.

Parameters

itemint, float, or str: The input item.
listAlist: The input list.

Returns

int: The index of the best match in listA for the input item.

static ClusterByKeys(elements, dictionaries, *keys, silent=False)

Clusters the input list of elements and dictionaries based on the input key or keys.

Parameters

elementslist: The input list of elements to be clustered.
dictionarieslist[Topology.Dictionary]: The input list of dictionaries to be consulted for clustering. This is assumed to be in the same order as the list of elements.
keysstr or list or comma-separated str input parameters: The key or keys in the topology’s dictionary to use for clustering.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

dict

A dictionary containing the elements and the dictionaries, but clustered. The dictionary has two keys: “elements”: list

A nested list of elements where each item is a list of elements with the same key values.

“dictionaries”: list: A nested list of dictionaries where each item is a list of dictionaries with the same key values.

static Flatten(listA)

Flattens the input nested list.

Parameters

listAlist: The input nested list.

Returns

list: The flattened list.

static Grow(seed_idx, group_size, adjacency, visited_global)

Attempts to grow a spatially connected group of a specified size starting from a given seed index.

This method uses a breadth-first search strategy to explore neighboring indices from the seed index, guided by the provided adjacency dictionary. It avoids reusing indices that are globally visited. The growth continues until the desired group size is reached or no further expansion is possible.

Parameters

seed_idxint: The index from which to start growing the group.
group_sizeint: The target size of the group to be grown.
adjacencydict: A dictionary mapping each index to a list of adjacent indices. This defines the connectivity.
visited_globalset: A set of indices that have already been used in previously grown groups and should be avoided.

Returns

list[int] or None: A list of indices representing a connected group of the specified size if successful, otherwise None.

Notes

This method is intended for internal use in functions that generate connected subgroups of spatial elements (e.g., cells) based on adjacency. The result may vary between runs due to random shuffling of neighbor order to diversify outputs.

static Iterate(listA)

Iterates the input nested list so that each sublist has the same number of members. To fill extra members, the shorter lists are iterated from their first member. For example Iterate([[1,2,3],[‘m’,’n’,’o’,’p’],[‘a’,’b’,’c’,’d’,’e’]]) yields [[1, 2, 3, 1, 2], [‘m’, ‘n’, ‘o’, ‘p’, ‘m’], [‘a’, ‘b’, ‘c’, ‘d’, ‘e’]]

Parameters

listAlist: The input nested list.

Returns

list: The iterated list.

static MakeUnique(listA)

Forces the strings in the input list to be unique if they have duplicates.

Parameters

listAlist: The input list of strings.

Returns

list: The input list, but with each item ensured to be unique if they have duplicates.

static MaximumIndices(listA, silent: bool = False)

Returns a list of indices of the maximum value in the input list. For example, if the input list is [7,3,4,7,5,7] then the returned list is [0,3,5] to indicate the indices of the maximum value (7).

Parameters

listAlist: The input list.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

list: The resulting list.

static MergeByThreshold(listA, threshold=0.0001)

Merges the numbers in the input list so that numbers within the input threshold are averaged into one number.

Parameters

listAlist: The input nested list.
thresholdfloat , optional: The desired merge threshold value. Default is 0.0001.

Returns

list: The merged list. The list is sorted in ascending numeric order.

static MinimumIndices(listA, silent: bool = False)

Returns a list of indices of the minimum value in the input list. For example, if the input list is [1,3,4,1,5,1] then the returned list is [0,3,5] to indicate the indices of the minimum value (1).

Parameters

listAlist: The input list.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

list: The resulting list.

static Normalize(listA, mantissa: int = 6)

Normalizes the input list so that it is in the range 0 to 1

Parameters

listAlist: The input nested list.
mantissaint , optional: The number of decimal places to round the result to. Default is 6.

Returns

list: The normalized list.

static Position(item, listA)

Returns the position of the item in the list or the position it would have been inserts. item is assumed to be numeric. listA is assumed to contain only numeric values and sorted from lowest to highest value.

Parameters

itemint or float: The input number to be positioned.
listAlist: The input sorted list.

Returns

int: The position of the item within the list.

static RemoveEven(listA)

Removes the even indexed members of the input list.

Parameters

listAlist: The input list.

Returns

list: The resulting list.

static RemoveOdd(listA)

Removes the odd indexed members of the input list.

Parameters

listAlist: The input list.

Returns

list: The resulting list.

static Repeat(listA)

Repeats the input nested list so that each sublist has the same number of members. To fill extra members, the last item in the shorter lists are repeated and appended. For example Iterate([[1,2,3],[‘m’,’n’,’o’,’p’],[‘a’,’b’,’c’,’d’,’e’]]) yields [[1, 2, 3, 3, 3], [‘m’, ‘n’, ‘o’, ‘p’, ‘p’], [‘a’, ‘b’, ‘c’, ‘d’, ‘e’]]

Parameters

listAlist: The input nested list.

Returns

list: The repeated list.

static SampleIndices(values: list, samples: int, silent: bool = False) → list

Returns original indices at evenly spaced ranks of the sorted values.

Parameters

valueslist: A list of finite numerical values. The input list is not modified.
samplesint: Number of unique indices to return, between zero and len(values). Two or more samples include the minimum and maximum sorted ranks. One sample selects the middle rank (the upper middle for even lists).
silentbool , optional: Suppress error messages. Default is False.

Returns

list: Original indices ordered by increasing value. Equal values retain their original order. Fractional ranks select the nearest integer, with half-rank ties rounded upwards. Zero samples returns []. Invalid inputs, including too many samples, return None.

Notes

Distribution is by sorted rank, rather than numerical distance between values. Sorting takes O(n log n) time and O(n) additional memory.

static Sort(listA, *otherLists, reverseFlags=None, silent: bool = False)

Sorts the first input list according to the values in the subsequent input lists in order. For example, your first list can be a list of topologies and the next set of lists can be their volume, surface area, and z level. The list of topologies will then be sorted first by volume, then by surface, and lastly by z level. You can choose to reverse the order of sorting by including a list of TRUE/FALSE values in the reverseFlags input parameter. For example, if you wish to sort the volume in reverse order (from large to small), but sort the other parameters normally, you would include the following list for reverseFlag: [True, False, False].

Parameters

listAlist: The first input list to be sorts
*otherListsany number of lists to use for sorting listA, optional.: Any number of lists that are used to sort the listA input parameter. The order of these input parameters determines the order of sorting (from left to right). If no lists are included, the input list will be sorted as is.
reverseFlagslist, optional.: The list of booleans (TRUE/FALSE) to indicated if sorting based on a particular list should be conducted in reverse order. The length of the reverseFlags list should match the number of the lists in the input otherLists parameter. If set to None, a default list of FALSE values is created to match the number of the lists in the input otherLists parameter. The default is None.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

list: The sorted list.

static TopPercentIndices(values: list, percent: float) → list

Returns the indices of the highest values corresponding to the specified percentage of the input list.

Parameters

valueslist: The input list of numerical values.
percentfloat: The percentage of highest values to return. This value should be between 0 and 100.

Returns

list: The indices of the highest values in the input list, ordered from highest to lowest value.

static TransferDictionariesByKey(topologies, selectors, key, silent: bool = False)

Transfers dictionaries from selectors to matching topologies using a shared dictionary key.

Each topology in the input list is inspected for the specified dictionary key. Each selector must contain a dictionary, either as a topology dictionary or as the value associated with the “dictionary” key of a Python dictionary.

When the value associated with the specified key in a selector matches the corresponding value in one or more topologies, the selector dictionary is assigned to those topologies.

Parameters

topologieslist: The input list of topologies.
selectorslist: The input list of selectors. A selector can be a topology containing a dictionary or a Python dictionary containing a “dictionary” entry.
keystr: The dictionary key used to match selectors to topologies.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

list: The list of topologies with transferred dictionaries.

static Transpose(listA)

Transposes the input list (swaps rows and columns).

Parameters

listAlist: The input list.

Returns

list: The transposed list.

static Trim(listA)

Trims the input nested list so that each sublist has the same number of members. All lists are trimmed to match the length of the shortest list. For example Trim([[1,2,3],[‘m’,’n’,’o’,’p’],[‘a’,’b’,’c’,’d’,’e’]]) yields [[1, 2, 3], [‘m’, ‘n’, ‘o’], [‘a’, ‘b’, ‘c’]]

Parameters

listAlist: The input nested list.

Returns

list: The repeated list.

static Version(check: bool = True, silent: bool = False)

Returns the current version of the software.

Parameters

checkbool , optional: if set to True, the version number is checked with the latest version on PyPi. Default is True.
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

str: The current version of the software. Optionally, includes a check with PyPi.