pycsamt.api.util#

util module provides utility functions and classes to support various data manipulation and analysis tasks

Functions

`apply_precision`(value[, precision])	Applies precision to a numerical value only if the decimal part is larger than the specified precision.
`beautify_dict`(d[, space, key, max_char])	Format a dictionary with custom indentation and aligned keys and values.
`count_functions`(module_name[, ...])	Count and list the number of functions and classes in a specified module.
`find_maximum_table_width`(summary_contents[, ...])	Calculates the maximum width of tables in a summary string based on header lines.
`format_cell`(x, max_text_length[, max_width])	Truncates a string to the maximum specified length and appends '...' if needed, and right-aligns it.
`format_dict_result`(dictionary[, dict_name, ...])	Formats a dictionary into a string with specified formatting rules.
`format_iterable`(attr)	Formats an iterable with a string representation that includes statistical or structural information depending on the iterable's type.
`format_text`(text[, key, key_length, ...])	Formats a block of text to fit within a specified maximum character width, optionally prefixing it with a key.
`format_value`(value[, precision])	Format a numeric value to a string, rounding floats to four decimal places and converting integers directly to strings.
`generate_column_name_mapping`(columns)	Generates a mapping from snake_case column names to their original names.
`generate_legend`([custom_markers, ...])	Generates a legend for a table (dataframe) matrix visualization, formatted according to specified parameters.
`get_frame_chars`(frame_char)	Retrieve framing characters based on the input frame indicator.
`get_table_size`([width, error, return_height])	Determines the appropriate width (and optionally height) for table display based on terminal size, with options for manual width adjustment.
`get_table_width_from`(formatted_str, /[, ...])	Calculate the maximum table width from the given formatted string based on
`get_terminal_size`()	Retrieves the current terminal size (width and height) to help dynamically set the maximum width for displaying data columns.
`parse_component_kind`(pc_list, kind)	Extracts specific principal component's feature names and their importance values from a list based on a given component identifier.
`remove_extra_spaces`(text)	Removes extra spaces from the input text, leaving only one space between words.
`round_numeric_values`(df[, precision])	Rounds numeric floating values in a DataFrame to the specified precision.
`series_to_dataframe`(series)	Transforms a pandas Series into a DataFrame where the columns are the index of the Series.
`to_camel_case`(text[, delimiter, use_regex])	Converts a given string to CamelCase.
`to_snake_case`(name[, mode])	Converts a string to snake_case.
`validate_precision`(precision, /)	Validates and converts the precision parameter to ensure it is a non-negative integer.

Classes

TerminalSize()

A utility class to get the size of the terminal window.

class pycsamt.api.util.TerminalSize[source]#

Bases: object

A utility class to get the size of the terminal window. This class provides methods to obtain the terminal size across different platforms, ensuring compatibility and providing a fallback size when necessary.

Variables:: DEFAULT_SIZE (tuple) – A default terminal size to fallback to when the actual terminal size cannot be determined. The default is (80, 20).

get_terminal_size()[source]#: Get the size of the terminal window as (columns, rows). Attempts multiple methods to ensure compatibility across different platforms.

_get_terminal_size_windows()[source]#: Get the terminal size for Windows platforms using ctypes.

_get_terminal_size_unix()[source]#: Get the terminal size for Unix-like platforms using ioctl syscall.

Notes

The get_terminal_size method first tries to use shutil.get_terminal_size with a fallback to DEFAULT_SIZE. If that fails, it checks the operating system and attempts to use platform-specific methods. On Windows, it uses the ctypes library to query the terminal size. On Unix-like systems, it uses the ioctl syscall.

Examples

>>> from fusionlab.api.util import TerminalSize
>>> TerminalSize.get_terminal_size()
(80, 25)

See also

shutil.get_terminal_size: Get the size of the terminal window.

References

DEFAULT_SIZE = (80, 20)#

static get_terminal_size()[source]#

Get the size of the terminal window as (columns, rows). Attempts multiple methods to ensure compatibility across different platforms.

Returns:: The size of the terminal as (columns, rows).
Return type:: tuple

pycsamt.api.util.format_value(value, precision=4)[source]#

Format a numeric value to a string, rounding floats to four decimal places and converting integers directly to strings.

Parameters:: value (int, float, np.integer, np.floating) – The numeric value to be formatted.
Returns:: A formatted string representing the value.
Return type:: str

Examples

>>> from fusionlab.api.util import format_value
>>> format_value(123)
'123'
>>> format_value(123.45678)
'123.4568'

pycsamt.api.util.apply_precision(value, precision=4)[source]#

Applies precision to a numerical value only if the decimal part is larger than the specified precision. Otherwise, returns the value as is.

Parameters:

value (int, float, np.integer, np.floating) – The numerical value to be formatted.
precision (int, optional) – The number of decimal places to format floating-point numbers. Default is 4.

Returns:

The formatted value if the decimal part is larger than the specified precision; otherwise, the value as is.

Return type:

int, float

Examples

>>> from fusionlab.api.util import apply_precision
>>> apply_precision(123.456789, 2)
123.46
>>> apply_precision(123.4, 2)
123.4
>>> apply_precision(np.int32(456), 2)
456
>>> apply_precision(np.float64(456.78), 2)
456.78
>>> apply_precision(123, 2)
123
>>> apply_precision(123.00, 2)
123.0

pycsamt.api.util.validate_precision(precision, /)[source]#

Validates and converts the precision parameter to ensure it is a non-negative integer.

Parameters:: precision (int, float, np.integer, np.floating) – The precision value to be validated.
Returns:: The validated and converted precision value.
Return type:: int
Raises:: ValueError – If the precision is not a non-negative number or cannot be converted to a non-negative integer.

Examples

>>> validate_precision(3)
3
>>> validate_precision(3.0)
3
>>> validate_precision(np.int32(2))
2
>>> validate_precision(np.float64(2.0))
2
>>> validate_precision(-1)
Traceback (most recent call last):
    ...
ValueError: Precision must be a non-negative integer.
>>> validate_precision('three')
Traceback (most recent call last):
    ...
ValueError: Precision must be a non-negative integer.

pycsamt.api.util.parse_component_kind(pc_list, kind)[source]#

Extracts specific principal component’s feature names and their importance values from a list based on a given component identifier.

Parameters:

pc_list (list of tuples) –

A list where each tuple contains (‘pc{i}’, feature_names,
sorted_component_values),

corresponding to each principal component. ‘pc{i}’ is a string label like ‘pc1’, ‘feature_names’ is an array of feature names sorted by their importance, and ‘sorted_component_values’ are the corresponding sorted values of component loadings.
kind (str) – A string that identifies the principal component number to extract, e.g., ‘pc1’. The string should contain a numeric part that corresponds to the component index in pc_list.

Returns:

A tuple containing two elements: - An array of feature names for the specified principal component. - An array of sorted component values for the specified principal

component.

Return type:

tuple

Raises:

ValueError – If the kind parameter does not contain a valid component number or if the specified component number is out of the range of available components in pc_list.

Examples

>>> from fusionlab.api.extension import parse_component_kind
>>> pc_list = [
...     ('pc1', ['feature1', 'feature2', 'feature3'], [0.8, 0.5, 0.3]),
...     ('pc2', ['feature1', 'feature2', 'feature3'], [0.6, 0.4, 0.2])
... ]
>>> feature_names, importances = parse_component_kind(pc_list, 'pc1')
>>> print(feature_names)
['feature1', 'feature2', 'feature3']
>>> print(importances)
[0.8, 0.5, 0.3]

Notes

The function requires that the kind parameter include a numeric value that accurately represents a valid index in pc_list. The index is derived from the numeric part of the kind string and is expected to be 1-based. If no valid index is found or if the index is out of range, the function raises a ValueError.

pycsamt.api.util.find_maximum_table_width(summary_contents, header_marker='=')[source]#

Calculates the maximum width of tables in a summary string based on header lines.

This function parses a multi-table summary string, identifying lines that represent the top or bottom borders of tables (header lines). It determines the maximum width of these tables by measuring the length of these header lines. The function assumes that the header lines consist of repeated instances of a specific marker character.

Parameters:

summary_contents (str) – A string containing the summarized representation of one or more tables. This string should include header lines made up of repeated header markers that denote the start and end of each table’s border.
header_marker (str, optional) – The character used to construct the header lines in the summary_contents. Defaults to ‘=’, the common character for denoting table borders in ASCII table representations.

Returns:

The maximum width of the tables found in summary_contents, measured as the length of the longest header line. If no header lines are found, returns 0.

Return type:

int

Examples

>>> from fusionlab.api.util import find_maximum_table_width
>>> summary = '''Model Performance
... ===============
... Estimator : SVC
... Accuracy  : 0.9500
... Precision : 0.8900
... Recall    : 0.9300
... ===============
... Model Performance
... =================
... Estimator : RandomForest
... Accuracy  : 0.9500
... Precision : 0.8900
... Recall    : 0.9300
... ================='''
>>> find_maximum_table_width(summary)
18

This example shows how the function can be used to find the maximum table width in a string containing summaries of model performances, where ‘=’ is used as the header marker.

pycsamt.api.util.format_text(text, key=None, key_length=15, max_char_text=50, add_frame_lines=False, border_line='=', buffer_space=4)[source]#

Formats a block of text to fit within a specified maximum character width, optionally prefixing it with a key. If the text exceeds the maximum width, it wraps to a new line, aligning with the key or the specified indentation.

Parameters:

text (str) – The text to be formatted.
key (str, optional) – An optional key to prefix the text. Defaults to None.
key_length (int, optional) – The length reserved for the key, including following spaces. If key is provided but key_length is None, the length of the key plus one space is used. Defaults to 15.
max_char_text (int, optional) – The maximum number of characters for the text width, including the key if present. Defaults to 50.
add_frame_lines (bool, False) – If True, frame the text with ‘=’ line (top and bottom)
border_line (str, optional) – The border line to frame the text. Default is ‘=’
buffer_space (int, default=4) – The extra space to force breaken the text. Using a large value will provide nice reading and force terminating the line sentence with no preprosition like a, ‘of’ or the etc.

Returns:

The formatted text with line breaks added to ensure that no line exceeds max_char_text characters. If a key is provided, it is included only on the first line, with subsequent lines aligned accordingly.

Return type:

str

Examples

>>> from fusionlab.api.util import format_text
>>> text_example = ("This is an example text that is supposed to wrap"
                  "around after a certain number of characters.")
>>> print(format_text(text_example, key="Note"))
Note           : This is an example text that is supposed to
                  wrap around after a certain number of
                  characters.

Notes

The function dynamically adjusts the text to fit within max_char_text, taking into account the length of key if provided.
Text that exceeds the max_char_text limit is wrapped to new lines, with proper alignment to match the initial line’s formatting.

pycsamt.api.util.get_frame_chars(frame_char)[source]#

Retrieve framing characters based on the input frame indicator.

Parameters:: frame_char (str) – A single character that indicates the desired framing style.
Returns:: A tuple containing the close character and the open-close pair for framing index values.
Return type:: tuple

Examples

>>> from fusionlab.api.util import get_frame_chars
>>> get_frame_chars('[')
(']', '[', ']')
>>> get_frame_chars('{')
('}', '{', '}')

pycsamt.api.util.format_cell(x, max_text_length, max_width=None)[source]#

Truncates a string to the maximum specified length and appends ‘…’ if needed, and right-aligns it.

Parameters: x (str): The string to format. max_width (int): The width to which the string should be aligned. max_text_length (int): The maximum allowed length of the string before truncation.

Returns: str: The formatted and aligned string.

pycsamt.api.util.get_table_width_from(formatted_str, /, border_char='=', check_first=True, deep_check=True, width_strategy='max', error='warn')[source]#

Calculate the maximum table width from the given formatted string based on the border style.

formatted_strstr
The string containing the formatted table.

border_charstr, optional
The character used for the table border. Default is ‘=’.

check_firstbool, optional
If True, check the width of the first border line found and return it. If False, check for additional border lines if the first one is found. Default is True.

deep_checkbool, optional
If True, evaluate all lines containing the border character to determine the table width. If False, follow the check_first strategy. Default is True.

width_strategy{‘max’, ‘min’, ‘average’}, optional
Strategy to determine the table width if deep_check is True. ‘max’ returns the longest border line. ‘min’ returns the shortest border line. ‘average’ returns the average width of all border lines. Default is ‘max’.

error{‘warn’, ‘raise’, ‘ignore’}, optional
How to handle cases where no border line is found. ‘warn’ logs a warning message. ‘raise’ raises an exception. ‘ignore’ does nothing and returns None. Default is ‘warn’.

int or None
The calculated table width, or None if no border line is found and error handling is set to ‘ignore’.

This function identifies lines in the formatted_str containing the border_char and calculates the width of the table based on the specified strategies and checks.

The calculation follows these steps:

Identify lines in formatted_str containing border_char.

If no such lines are found, handle the error based on error parameter.

If deep_check is False:

If check_first is True, return the length of the first border line.

Otherwise, return the length of the last border line.

If deep_check is True:

Compute the lengths of all border lines.

If width_strategy is ‘average’, return the average length of border lines:

\[ext{average\_width} =\]

rac{sum_{i=1}^{n} ext{length}_i}{n}

If width_strategy is ‘min’, return the minimum length of border lines.

If width_strategy is ‘max’, return the maximum length of border lines.
>>> from fusionlab.api.util import get_table_width_from
>>> formatted_str = "=======

Col |

>>> get_table_width_from(formatted_str)
7

>>> formatted_str = "=====

C |

>>> get_table_width_from(formatted_str, border_char='=')
5
pandas.DataFrameDataFrame structure used in pandas for data manipulation
and analysis.

[1]
McKinney, Wes. “Data Structures for Statistical Computing in Python.” Proceedings of the 9th Python in Science Conference. 2010.

pycsamt.api.util.generate_legend(custom_markers=None, no_corr_placeholder='...', hide_diag=True, max_width=50, add_frame_lines=True, border_line='.')[source]#

Generates a legend for a table (dataframe) matrix visualization, formatted according to specified parameters.

This function supports both numeric and symbolic representations of table values. Symbolic representations, which are used primarily for visual clarity, include the following symbols:

'++': Represents a strong positive relationship.
'--': Represents a strong negative relationship.
'-+': Represents a moderate relationship.
'o': Used exclusively for diagonal elements, typically representing a perfect relationship in correlation matrices (value of 1.0).

Parameters:

custom_markers (dict, optional) – A dictionary mapping table symbols to their descriptions. If provided, it overrides the default markers. Default is None.
no_corr_placeholder (str, optional) – Placeholder text for table values that do not meet the minimum threshold. Default is ‘…’.
hide_diag (bool, optional) – If True, omits the diagonal entries from the legend. These are typically frame of a variable with itself (1.0). Default is True.
max_width (int, optional) – The maximum width of the formatted legend text, influences the centering of the title. Default is 50.
add_frame_lines (bool, optional) – If True, adds a frame around the legend using the specified border_line. Default is True.
border_line (str, optional) – The character used to create the border of the frame if add_frame_lines is True. Default is ‘.’.

Returns:

The formatted legend text, potentially framed, centered according to the specified width, and including custom or default descriptions of correlation values.

Return type:

str

Examples

>>> from fusionlab.api.util import generate_legend
>>> custom_markers = {"++": "High Positive", "--": "High Negative"}
>>> print(generate_legend(custom_markers=custom_markers, max_width=60))
............................................................
Legend : ...: Non-correlated, ++: High Positive, --: High
         Negative, -+: Moderate
............................................................

>>> print(generate_legend(hide_diag=False, max_width=70))
......................................................................
Legend : ...: Non-correlated, ++: Strong positive, --: Strong negative,
         -+: Moderate, o: Diagonal
......................................................................
>>> custom_markers = {"++": "Highly positive", "--": "Highly negative"}
>>> legend = generate_legend(custom_markers=custom_markers,
...                          no_corr_placeholder='N/A', hide_diag=False,
...                          border_line ='=')

>>> print(legend)

Diagonal

pycsamt.api.util.to_snake_case(name, mode='standard')[source]#

Converts a string to snake_case.

Parameters:

name (str) – The string to convert to snake_case.
mode (str, optional) – If ‘soft’, extra whitespace and case inconsistencies are handled to produce clean snake_case.

Returns:

The snake_case version of the input string.

Return type:

str

pycsamt.api.util.generate_column_name_mapping(columns)[source]#

Generates a mapping from snake_case column names to their original names.

Parameters:: columns (List[str]) – The list of column names to convert and map.
Returns:: A dictionary mapping snake_case column names to their original names.
Return type:: dict

pycsamt.api.util.series_to_dataframe(series)[source]#

Transforms a pandas Series into a DataFrame where the columns are the index of the Series. If the Series’ index is numeric, the index values are converted to strings and used as column names.

Parameters:: series (pandas.Series) – The Series to be transformed into a DataFrame.
Returns:: A DataFrame where each column represents a value from the Series, with column names corresponding to the Series’ index values.
Return type:: pandas.DataFrame
Raises:: TypeError – If the input is not a pandas Series.

Examples

>>> import pandas as pd
>>> from fusionlab.api.util import series_to_dataframe
>>> series = pd.Series(data=[1, 2, 3], index=['a', 'b', 'c'])
>>> df = series_to_dataframe(series)
>>> print(df)
   a  b  c
0  1  2  3

>>> series_numeric_index = pd.Series(data=[4, 5, 6], index=[10, 20, 30])
>>> df_numeric = series_to_dataframe(series_numeric_index)
>>> print(df_numeric)
  10 20 30
0  4  5  6

pycsamt.api.util.get_table_size(width='auto', error='warn', return_height=False)[source]#

Determines the appropriate width (and optionally height) for table display based on terminal size, with options for manual width adjustment.

Parameters:

width (int or str, optional) – The desired width for the table. If set to ‘auto’, the terminal width is used. If an integer is provided, it will be used as the width, default is ‘auto’.
error (str, optional) – Error handling strategy when specified width exceeds terminal width: ‘warn’ or ‘ignore’. Default is ‘warn’.
return_height (bool, optional) – If True, the function also returns the height of the table. Default is False.

Returns:

The width of the table as an integer, or a tuple of (width, height) if return_height is True.

Return type:

int or tuple

Examples

>>> table_width = get_table_size()
>>> print("Table width:", table_width)
>>> table_width, table_height = get_table_size(return_height=True)
>>> print("Table width:", table_width, "Table height:", table_height)

pycsamt.api.util.get_terminal_size()[source]#

Retrieves the current terminal size (width and height) to help dynamically set the maximum width for displaying data columns.

Returns:: A tuple containing two integers: - The width of the terminal in characters. - The height of the terminal in lines.
Return type:: tuple

Examples

>>> from fusionlab.api.util import get_terminal_size
>>> terminal_width, terminal_height = get_terminal_size()
>>> print("Terminal Width:", terminal_width)
>>> print("Terminal Height:", terminal_height)

pycsamt.api.util.to_camel_case(text, delimiter=None, use_regex=False)[source]#

Converts a given string to CamelCase. The function handles strings with or without delimiters, and can optionally use regex for splitting based on non-alphanumeric characters.

Parameters:

text (str) – The string to convert to CamelCase.
delimiter (str, optional) – A character or string used as a delimiter to split the input string. Common delimiters include underscores (‘_’) or spaces (’ ‘). If None and use_regex is False, the function tries to automatically detect common delimiters like spaces or underscores. If use_regex is True, it splits the string at any non-alphabetic character.
use_regex (bool, optional) – Specifies whether to use regex for splitting the string on non-alphabetic characters. Defaults to False.

Returns:

The CamelCase version of the input string.

Return type:

str

Examples

>>> from fusionlab.api.util import to_camel_case
>>> to_camel_case('outlier_results', '_')
'OutlierResults'

>>> to_camel_case('outlier results', ' ')
'OutlierResults'

>>> to_camel_case('outlierresults')
'Outlierresults'

>>> to_camel_case('data science rocks')
'DataScienceRocks'

>>> to_camel_case('data_science_rocks')
'DataScienceRocks'

>>> to_camel_case('multi@var_analysis', use_regex=True)
'MultiVarAnalysis'

>>> to_camel_case('OutlierResults')
'OutlierResults'

>>> to_camel_case('BoxFormatter')
'BoxFormatter'

>>> to_camel_case('MultiFrameFormatter')
'MultiFrameFormatter'

pycsamt.api.util.beautify_dict(d, space=4, key=None, max_char=None)[source]#

Format a dictionary with custom indentation and aligned keys and values.

Parameters:#

ddict: The dictionary to format.
spaceint, optional: The number of spaces to indent the dictionary entries.
keystr, optional: An optional key to nest the dictionary under.
max_charint, optional: Maximum characters a value can have before being truncated.

Returns:#

str: A string representation of the dictionary with custom formatting.

Examples:#

>>> from fusionlab.api.util import beautify_dict
>>> dictionary = {
...     3: 'Home & Garden',
...     2: 'Health & Beauty',
...     4: 'Sports',
...     0: 'Electronics',
...     1: 'Fashion'
... }
>>> print(beautify_dict(dictionary, space=4))

pycsamt.api.util.remove_extra_spaces(text)[source]#

Removes extra spaces from the input text, leaving only one space between words.

Parameters:: text (str) – The string from which extra spaces need to be removed.
Returns:: The string with only one space between each word.
Return type:: str

Example

>>> from fusionlab.api.util import remove_extra_spaces
>>> text = "this is      text that    have   extra          space."
>>> remove_extra_spaces(text)
'this is text that have extra space.'

pycsamt.api.util.format_iterable(attr)[source]#: Formats an iterable with a string representation that includes statistical or structural information depending on the iterable’s type.

pycsamt.api.util.format_dict_result(dictionary, dict_name='Container', max_char=50, include_message=False)[source]#

Formats a dictionary into a string with specified formatting rules.

Parameters:

dictionary (dict) – The dictionary to format.
dict_name (str, optional) – The name of the dictionary, by default ‘Container’.
max_char (int, optional) – The maximum number of characters for each value before truncating, by default 50.
include_message (bool, optional) – Whether to include a remainder message at the end, by default False.

Returns:

The formatted string representation of the dictionary.

Return type:

str

Examples

>>> example_dict = {
...     'key1': 'short value',
...     'key2': 'a much longer value that should be truncated for readability purposes',
...     'key3': 'another short value',
...     'key4': 'value'
... }
>>> print(format_dict_result(example_dict, dict_name='ExampleDict', max_char=30))
ExampleDict({
    key1: short value,
    key2: a much longer value that s...,
    key3: another short value,
    key4: value,
})

Notes

The function calculates the required indentation based on the length of the dictionary name and the maximum key length. If a value exceeds the specified maximum length, it truncates the value and appends an ellipsis (”…”).

pycsamt.api.util.count_functions(module_name, include_class=False, return_counts=True, include_private=False, include_local=False)[source]#

Count and list the number of functions and classes in a specified module.

Parameters:

module_name (str) – The name of the module to inspect, in the format package.module.
include_class (bool, optional) – Whether to include classes in the count and listing. Default is False.
return_counts (bool, optional) – Whether to return only the count of functions and classes (if include_class is True). If False, returns a list of functions and classes in alphabetical order. Default is True.
include_private (bool, optional) – Whether to include private functions and classes (those starting with _). Default is False.
include_local (bool, optional) – Whether to include local (nested) functions in the count and listing. Default is False.

Returns:

If return_counts is True, returns the count of functions and classes (if include_class is True). If return_counts is False, returns a list of function and class names (if include_class is True) in alphabetical order.

Return type:

int or list

Notes

This function dynamically imports the specified module and analyzes its Abstract Syntax Tree (AST) to count and list functions and classes. It provides flexibility to include or exclude private and local functions based on the parameters provided.

The process can be summarized as:

\[ext{total\_count} = ext{len(functions)} + ext{len(classes)}\]

where:

:math:` ext{functions}` is the list of functions found in the module.
:math:` ext{classes}` is the list of classes found in the module (if include_class is True).

Examples

>>> from fusionlab.api.util import count_functions_classes
>>> count_functions_classes('fusionlab.api.util', include_class=True,
                            return_counts=True)
10

>>> count_functions('fusionlab.api.util', include_class=True,
                            return_counts=False)
['ClassA', 'ClassB', 'func1', 'func2', 'func3']

>>> count_functions('fusionlab.api.util', include_class=False,
                            return_counts=True, include_private=True)
15

>>> count_functions('fusionlab.api.util', include_class=False,
                            return_counts=False, include_private=True)
['_private_func1', '_private_func2', 'func1', 'func2']