tools 1.0.2__tar.gz → 1.0.4__tar.gz

{tools-1.0.2 → tools-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: tools
-Version: 1.0.2
+Version: 1.0.4
 Summary: python syntax tool
 Home-page: https://github.com/jsyoo61/tools
 Author: JaeSung Yoo
@@ -12,7 +12,7 @@ Requires-Python: >=3.6
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
 
-# tools-jsyoo61
+# tools
 
 (`tools` package was replaced on 2025.04.28. If you're looking for web scraping tools, visit http://pypi.python.org/pypi/weblib)
 
@@ -28,12 +28,10 @@ jsyoo61@unc.edu
 Most useful functions are in `tools.tools` which is loaded to the main module by default. \
 API dependent tools are in their corresponding folders: `tools.API_name` (i.e. `tools.torch.optim`)
 
-Planning to document using chatGPT,
-Not documented yet, so you'll have to look at documents written inside the codes. (Most codes contain explanation)
+Undocumented, so you'll have to look at documents written inside the codes or with help(). (Most codes contain explanation)
+Planning to document with chatGPT.
 
 I'm happy to discuss questions or suggestions, please contact me via email. :)
 
-1.0.1. (2025.5.1.)
-
-- `tools.sklearn.metrics.r2_score()` `multioutput` argument fixed
-- `tools.sklearn.metrics` axis=None returns a single np.float object
+1.0.4. (2025.8.14.)
+- `tools.sklearn.metrics` stable, has proper arguments `axis_ref`, `axis_bias`

{tools-1.0.2 → tools-1.0.4}/README.md

@@ -1,4 +1,4 @@
-# tools-jsyoo61
+# tools
 
 (`tools` package was replaced on 2025.04.28. If you're looking for web scraping tools, visit http://pypi.python.org/pypi/weblib)
 
@@ -14,12 +14,10 @@ jsyoo61@unc.edu
 Most useful functions are in `tools.tools` which is loaded to the main module by default. \
 API dependent tools are in their corresponding folders: `tools.API_name` (i.e. `tools.torch.optim`)
 
-Planning to document using chatGPT,
-Not documented yet, so you'll have to look at documents written inside the codes. (Most codes contain explanation)
+Undocumented, so you'll have to look at documents written inside the codes or with help(). (Most codes contain explanation)
+Planning to document with chatGPT.
 
 I'm happy to discuss questions or suggestions, please contact me via email. :)
 
-1.0.1. (2025.5.1.)
-
-- `tools.sklearn.metrics.r2_score()` `multioutput` argument fixed
-- `tools.sklearn.metrics` axis=None returns a single np.float object
+1.0.4. (2025.8.14.)
+- `tools.sklearn.metrics` stable, has proper arguments `axis_ref`, `axis_bias`

{tools-1.0.2 → tools-1.0.4}/tools/__init__.py

@@ -1,5 +1,5 @@
 
-__version__ = "1.0.2"
+__version__ = "1.0.4"
 from .tools import *
 from . import os
 

tools-1.0.4/tools/dict_operations.py

@@ -0,0 +1,139 @@
+import numpy as np
+import utils as U
+
+# %%
+def add_batch_dim(data):
+    """
+    adds batch dimension (axis=0)
+
+    Parameters
+    ----------
+    data : numpy.ndarray or dict of arrays
+
+    Returns
+    -------
+    data : numpy.ndarray or dict of arrays with axis=0 dimension added
+    """
+    if isinstance(data, dict):
+        data = {k: v[None,...] for k, v in data.items()}
+    else:
+        data = data[None,...]
+    return data
+
+def remove_batch_dim(data):
+    if isinstance(data, dict):
+        data = {k: v.squeeze(0) for k, v in data.items()}
+    else:
+        data = data.squeeze(0)
+    return data
+
+def __eq__(data1, data2):
+    if isinstance(data1, dict) and isinstance(data2, dict):
+        k1, k2 = sorted(list(data1.keys())), sorted(list(data2.keys()))
+        if k1!=k2:
+            return False
+        else:
+            equal_values = [all(data1[k]==data2[k]) for k in k1]
+            return all(equal_values)
+    else:
+        return data1==data2
+
+def __getitem__(data, idx):
+    if isinstance(data, dict):
+        return {k: v[idx] for k, v in data.items()}
+    else:
+        return data[idx]
+
+def __iter__(data):
+    if isinstance(data, dict):
+        iterators = {k: iter(v) for k, v in data.items()}
+        while True:
+            try:
+                yield {k: next(v) for k, v in iterators.items()}
+            except StopIteration:
+                break
+    else:
+        return iter(data)
+
+def __len__(data):
+    if isinstance(data, dict):
+        l_len = [len(v) for v in data.values()]
+        assert U.equal(l_len)
+        return l_len[0]
+
+    else:
+        return len(data)
+
+def array(data, dtype=None):
+    '''
+    data: iterable or iterable of dicts
+    '''
+    if isinstance(data, dict):
+        return {k: np.array(v, dtype=dtype) for k, v in data.items()}
+    else:
+        np.array(data, dtype=dtype)
+
+def astype(data, dtype):
+    if isinstance(data, dict):
+        return {k: v.astype(dtype) for k, v in data.items()}
+    else:
+        data.astype(dtype)
+
+def broadcast_to(data, shape):
+    if isinstance(data, dict):
+        return {k: np.broadcast_to(v, shape=shape) for k, v in data.items()}
+    else:
+        return np.broadcast_to(data, shape=shape)
+
+def shape(data):
+    if isinstance(data, dict):
+        l_shape = [v.shape for v in data.values()]
+        assert U.equal(l_shape), "shape within dict are not equal."
+        return l_shape[0]
+    else:
+        return data.shape
+
+def stack(data, axis):
+    if isinstance(data, dict):
+        return {k: np.stack(v, axis=axis) for k, v in data.items()}
+    else:
+        return np.stack(data, axis=axis)
+
+def nwise(data, n):
+    """
+    Returns n-elements from the data sequentially.
+
+    Returns
+    -------
+    generator object
+
+    See Also
+    --------
+    itertools.pairwise : Same as nwise but with n=2
+
+    Examples
+    --------
+    >>> list(nwise(np.arange(5), n=3))
+    [array([0, 1, 2]), array([1, 2, 3]), array([2, 3, 4])]
+    """
+    if isinstance(data, dict):
+        l_shape = [v.shape for v in data.values()]
+        assert U.equal(l_shape), "shape within dict are not equal."
+        data_shape = l_shape[0]
+        for i in range(data_shape[0]-n+1):
+            yield {k: v[i:i+n] for k, v in data.items()}
+    else:
+        for i in range(len(data)-n+1):
+            yield data[i:i+n]
+
+def concatenate(data, axis):
+    if isinstance(data, dict):
+        return {k: np.concatenate(v, axis=axis) for k, v in data.items()}
+    else:
+        return np.concatenate(data, axis=axis)
+
+def to(data, **kwargs):
+    if isinstance(data, dict):
+        return {k: v.to(**kwargs) for k, v in data.items()}
+    else:
+        return data.to(**kwargs)

tools-1.0.4/tools/plot/__init__.py

@@ -0,0 +1,26 @@
+from .sklearn import *
+from .utils import *
+
+if __name__ == '__main__':
+    pass
+
+def add_colorbar(ax):
+    """
+    Add a colorbar to the given axes.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+
+    Returns
+    -------
+    C : ndarray of shape (n_classes, n_classes)
+        Explanation variable
+    """
+    from matplotlib import cm
+    from mpl_toolkits.axes_grid1 import make_axes_locatable
+
+    divider = make_axes_locatable(ax)
+    cax = divider.append_axes("right", size="5%", pad=0.05)
+    cbar = ax.figure.colorbar(cm.ScalarMappable(norm=ax.images[0].norm, cmap=ax.images[0].cmap), cax=cax)
+    return cbar

tools-1.0.4/tools/sklearn/metrics.py

@@ -0,0 +1,189 @@
+from collections.abc import Iterable
+import warnings
+
+import numpy as np
+from sklearn.metrics import r2_score as r2_score_sklearn
+
+def squared_error(y_true, y_pred, axis=None):
+    """
+    MSE averaging across specified axis.
+    if axis=(), returns entry-by-entry squared error.
+
+    Parameters
+    ----------
+    y_true : np.ndarray
+    y_pred : np.ndarray
+
+    axis : int or iterable of int, default=None
+        Axis to collapse.
+
+    Returns
+    -------
+    score : numpy.ndarray of shape with collapsed axis
+    """
+    if axis is None:
+        axis = tuple(range(y_true.ndim)) # Collapse all dimensions
+    score = (y_true-y_pred)**2
+    score = np.mean(score, axis=axis)
+    return score
+
+def absolute_error(y_true, y_pred, axis=None):
+    """
+    MAE averaging across specified axis.
+    if axis=(), returns entry-by-entry absolute error.
+
+    Parameters
+    ----------
+    y_true : np.ndarray
+    y_pred : np.ndarray
+
+    axis : int or iterable of int, default=None
+        Axis to collapse.
+
+    Returns
+    -------
+    score : numpy.ndarray of shape with collapsed axis
+    """
+    if axis is None:
+        axis = tuple(range(y_true.ndim)) # Collapse all dimensions
+    score = np.abs(y_true-y_pred)
+    score = np.mean(score, axis=axis)
+    return score
+
+def r2_score(y_true, y_pred, axis=None, axis_ref=None, axis_bias=None, multioutput='raw_values', force_finite=True):
+    """
+    R^2 score for multidimensional predictions.
+    collapses all axes except the specified axis.
+
+    Computes 1 - RSS / TSS, where RSS is the residual sum of squares and TSS is the total sum of squares.
+
+    Parameters
+    ----------
+    y_true : np.ndarray
+    y_pred : np.ndarray
+    axis: int or iterable of int, default=None
+        Axis to collapse.
+        If None, collapses all axes.
+        
+    multioutput : Reference to `sklearn.metrics.r2_score`
+        https://scikit-learn.org/stable/modules/generated/sklearn.metrics.r2_score.html
+
+        Note:
+        - default is 'raw_values', which is different from sklearn.
+        - when multioutput is uniform_average or variance_weighted, return value is a single float even if axis is specified.
+          The axis specifies the feature dimensions to average over.
+    
+    Returns
+    -------
+    z : np.ndarray
+        if axis is specified, returns an array of shape (y_true.shape[axis],)
+    """
+
+    # Residual Sum of Squares (RSS) and Total Sum of Squares (TSS)
+    RS = (y_true - y_pred)**2 # Residual Square (RS)
+    RSS = np.sum(RS, axis=axis, keepdims=True)
+
+    if axis_ref is None:
+        axis_ref = axis
+    if axis_bias is None:
+        axis_bias = axis_ref
+
+    axis_ref_set = {axis_ref} if not isinstance(axis_ref, Iterable) else set(axis_ref)
+    axis_set = {axis} if not isinstance(axis, Iterable) else set(axis)
+    axis_bias_set = {axis_bias} if axis_bias is not None and not isinstance(axis_bias, Iterable) else set(axis_bias) if axis_bias is not None else set()
+
+    assert axis_bias_set.issubset(axis_ref_set), f'axis_bias ({axis_bias}) must be a subset of axis_ref ({axis_ref}) because axis_ measure variability' # If axis_bias is not a subset of axis_ref, expand axis_ref to include axis_bias
+
+    # Dimensions of TSS must be smaller than RSS, so mean/sum over axis_ref and axis
+    axis_sum = axis
+    axis_mean = tuple(axis_ref_set - axis_set) # Average over axis_ref - axis
+
+    if not axis_set.issubset(axis_ref_set): # If axis is not a subset of axis_ref, expand axis_ref to include axis
+        warnings.warn(f"axis {axis} is not a subset of axis_ref {axis_ref}, TSS sums over axis {axis_sum} and averages over remaining axis_ref {axis_mean}")
+
+    # axis_bias used to compute the mean of y_true
+    y_mean = np.mean(y_true, axis=axis_bias, keepdims=True)
+    TS = (y_true - y_mean)**2 # Total Square (TS)
+
+    # axis_ref used to aggregate additional dimensions (average) additional to axis
+    TSS = np.mean(TS, axis=axis_mean, keepdims=True)
+    TSS = np.sum(TSS, axis=axis_sum, keepdims=True)
+    
+    score = 1 - RSS / TSS
+    score = np.squeeze(score, axis=axis) # Collapse the axis_ref dimension
+
+    if force_finite:
+        score[np.isnan(score)] = 1
+        score[np.isinf(score)] = 0 # -Inf means no fit, so set to 0
+
+    if axis is None:
+        score = score.item()
+
+    return score
+
+# def r2_score(y_true, y_pred, axis=None, multioutput='raw_values'):
+#     """
+#     R^2 score for multidimensional predictions.
+#     collapses all axes except the specified axis.
+
+#     Parameters
+#     ----------
+#     y_true : np.ndarray
+#     y_pred : np.ndarray
+#     axis: int or iterable of int, default=None
+#         Axis to collapse.
+#         If None, collapses all axes.
+        
+#     multioutput : Reference to `sklearn.metrics.r2_score`
+#         https://scikit-learn.org/stable/modules/generated/sklearn.metrics.r2_score.html
+
+#         Note:
+#         - default is 'raw_values', which is different from sklearn.
+#         - when multioutput is uniform_average or variance_weighted, return value is a single float even if axis is specified.
+#           The axis specifies the feature dimensions to average over.
+    
+#     Returns
+#     -------
+#     z : np.ndarray
+#         if axis is specified, returns an array of shape (y_true.shape[axis],)
+#     """
+#     assert y_true.shape == y_pred.shape, f"y_true and y_pred must have the same shape, received: {y_true.shape} and {y_pred.shape}"
+#     if axis is None:
+#         axis = list(range(y_true.ndim)) # Collapse all dimensions
+#         axis_was_none = True
+#     elif not isinstance(axis, Iterable):
+#         axis = [axis]
+#         axis_was_none = False
+#     else:
+#         axis = list(axis)
+#         axis_was_none = False
+
+#     if len(axis) > y_true.ndim:
+#         raise ValueError("Axis is greater than the number of dimensions of y_true and y_pred")
+
+#     dim_collapse = axis
+#     dim_final = list(set(range(y_true.ndim)).difference(axis))
+#     shape_final = np.array(y_true.shape)[dim_final] if len(dim_final)!=0 else (1,)
+
+#     y_true = np.transpose(y_true, (*dim_collapse, *dim_final)).reshape(-1, np.prod(shape_final)) # Move axis to the end, and flatten the rest
+#     y_pred = np.transpose(y_pred, (*dim_collapse, *dim_final)).reshape(-1, np.prod(shape_final))
+
+#     # score = r2_score_sklearn(y_true, y_pred, multioutput=multioutput)
+#     score = r2_score_sklearn(y_true, y_pred, multioutput='raw_values')
+
+#     if type(score) == float and np.isnan(score).item():
+#         warnings.warn("R2 score is a single NaN, shape matching with NaN")
+#         score = np.full(shape_final, np.nan)
+#         return score
+
+#     if multioutput == 'raw_values':
+#         score = score.reshape(*shape_final) if not axis_was_none else score[0]
+#         return score
+#     elif multioutput == 'uniform_average':
+#         return score.mean()
+#     elif multioutput == 'variance_weighted':        
+#         return np.average(score, weights=np.var(y_true, axis=0))
+#     else:
+#         raise ValueError("multioutput must be one of ['raw_values', 'uniform_average', 'variance_weighted']")
+
+# %%

{tools-1.0.2 → tools-1.0.4}/tools/tools.py

@@ -162,6 +162,21 @@ def unnest_dict(d, format='.'):
             un_d[k] = v
     return un_d
 
+def nest_dict(d, format='.'):
+    '''
+    Convert a 1st order dictionary with format-separated-keys into a nested dictionary.
+    '''
+    n_d = {}
+    for k, v in d.items():
+        keys = k.split(format)
+        d_ = n_d # Start from root
+        for key in keys[:-1]: # Traverse to the last key
+            if key not in d_: # If key does not exist, create a new dict
+                d_[key] = {}
+            d_ = d_[key] # Move to the next dict
+        d_[keys[-1]] = v # Set the value to the last key
+    return n_d
+
 def nestdict_to_list(d, key=None):
     '''
     open 2nd order nested dict to list of dicts.
@@ -187,7 +202,26 @@ def update_ld(ld, d):
 
     return ld
 
-def update_keys(d, d_key, copy=True): # inplace? copy?
+def update_keys(d, d_key, copy=False): # inplace? copy?
+    """
+    Update keys of a dictionary.
+
+    Parameters
+    ----------
+    d : dict
+        Dictionary to update.
+    d_key : dict
+        Dictionary of old and new keys.
+        The keys of d_key are the old keys, and the values are the new keys.
+    copy : bool, default=False
+        If True, a copy of the dictionary is made before updating the keys.
+
+    Returns
+    -------
+    d : dict
+        Updated dictionary with new keys.
+        If copy is True, a new dictionary is returned.
+    """
     if copy:
         d = dcopy(d)
     for k_old, k_new in d_key.items():

{tools-1.0.2 → tools-1.0.4}/tools.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: tools
-Version: 1.0.2
+Version: 1.0.4
 Summary: python syntax tool
 Home-page: https://github.com/jsyoo61/tools
 Author: JaeSung Yoo
@@ -12,7 +12,7 @@ Requires-Python: >=3.6
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
 
-# tools-jsyoo61
+# tools
 
 (`tools` package was replaced on 2025.04.28. If you're looking for web scraping tools, visit http://pypi.python.org/pypi/weblib)
 
@@ -28,12 +28,10 @@ jsyoo61@unc.edu
 Most useful functions are in `tools.tools` which is loaded to the main module by default. \
 API dependent tools are in their corresponding folders: `tools.API_name` (i.e. `tools.torch.optim`)
 
-Planning to document using chatGPT,
-Not documented yet, so you'll have to look at documents written inside the codes. (Most codes contain explanation)
+Undocumented, so you'll have to look at documents written inside the codes or with help(). (Most codes contain explanation)
+Planning to document with chatGPT.
 
 I'm happy to discuss questions or suggestions, please contact me via email. :)
 
-1.0.1. (2025.5.1.)
-
-- `tools.sklearn.metrics.r2_score()` `multioutput` argument fixed
-- `tools.sklearn.metrics` axis=None returns a single np.float object
+1.0.4. (2025.8.14.)
+- `tools.sklearn.metrics` stable, has proper arguments `axis_ref`, `axis_bias`

{tools-1.0.2 → tools-1.0.4}/tools.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ setup.py
 tools/__init__.py
 tools/array.py
 tools/data.py
+tools/dict_operations.py
 tools/exp.py
 tools/modules.py
 tools/os.py

tools-1.0.2/tools/plot/__init__.py

@@ -1,5 +0,0 @@
-from .sklearn import *
-from .utils import *
-
-if __name__ == '__main__':
-    pass

tools-1.0.2/tools/sklearn/metrics.py

@@ -1,112 +0,0 @@
-from collections.abc import Iterable
-import warnings
-
-import numpy as np
-from sklearn.metrics import r2_score as r2_score_sklearn
-
-def squared_error(y_true, y_pred, axis=None):
-    """
-    MSE averaging across specified axis.
-    if axis=(), returns entry-by-entry squared error.
-
-    Parameters
-    ----------
-    y_true : np.ndarray
-    y_pred : np.ndarray
-
-    axis : int or iterable of int, default=None
-        Axis to collapse.
-
-    Returns
-    -------
-    score : numpy.ndarray of shape with collapsed axis
-    """
-    if axis is None:
-        axis = tuple(range(y_true.ndim)) # Collapse all dimensions
-    score = (y_true-y_pred)**2
-    score = np.mean(score, axis=axis)
-    return score
-
-def absolute_error(y_true, y_pred, axis=None):
-    """
-    MAE averaging across specified axis.
-    if axis=(), returns entry-by-entry squared error.
-
-    Parameters
-    ----------
-    y_true : np.ndarray
-    y_pred : np.ndarray
-
-    axis : int or iterable of int, default=None
-        Axis to collapse.
-
-    Returns
-    -------
-    score : numpy.ndarray of shape with collapsed axis
-    """
-    if axis is None:
-        axis = tuple(range(y_true.ndim)) # Collapse all dimensions
-    score = np.abs(y_true-y_pred)
-    score = np.mean(score, axis=axis)
-    return score
-
-def r2_score(y_true, y_pred, axis=None, multioutput='raw_values'):
-    """
-    R^2 score for multidimensional predictions.
-    collapses all axes except the specified axis.
-
-    Parameters
-    ----------
-    y_true : np.ndarray
-    y_pred : np.ndarray
-    axis: int or iterable of int, default=None
-        Axis to collapse.
-        It must be specified if y_true and y_pred dimensions are > 2
-    multioutput : Reference to `sklearn.metrics.r2_score`
-        https://scikit-learn.org/stable/modules/generated/sklearn.metrics.r2_score.html
-    
-    Returns
-    -------
-    z : np.ndarray
-        if axis is specified, returns an array of shape (y_true.shape[axis],)
-    """
-    assert y_true.shape == y_pred.shape, f"y_true and y_pred must have the same shape, received: {y_true.shape} and {y_pred.shape}"
-    if axis is None:
-        axis = list(range(y_true.ndim)) # Collapse all dimensions
-        axis_was_none = True
-    elif not isinstance(axis, Iterable):
-        axis = [axis]
-        axis_was_none = False
-    else:
-        axis = list(axis)
-        axis_was_none = False
-
-    if len(axis) > y_true.ndim:
-        raise ValueError("Axis is greater than the number of dimensions of y_true and y_pred")
-
-    dim_collapse = axis
-    dim_final = list(set(range(y_true.ndim)).difference(axis))
-    shape_final = np.array(y_true.shape)[dim_final] if len(dim_final)!=0 else (1,)
-
-    y_true = np.transpose(y_true, (*dim_collapse, *dim_final)).reshape(-1, np.prod(shape_final)) # Move axis to the end, and flatten the rest
-    y_pred = np.transpose(y_pred, (*dim_collapse, *dim_final)).reshape(-1, np.prod(shape_final))
-
-    # score = r2_score_sklearn(y_true, y_pred, multioutput=multioutput)
-    score = r2_score_sklearn(y_true, y_pred, multioutput='raw_values')
-
-    if type(score) == float and np.isnan(score).item():
-        warnings.warn("R2 score is a single NaN, shape matching with NaN")
-        score = np.full(shape_final, np.nan)
-        return score
-
-    if multioutput == 'raw_values':
-        score = score.reshape(*shape_final) if not axis_was_none else score[0]
-        return score
-    elif multioutput == 'uniform_average':
-        return score.mean()
-    elif multioutput == 'variance_weighted':
-        return np.average(score, weights=np.var(y_true, axis=0))
-    else:
-        raise ValueError("multioutput must be one of ['raw_values', 'uniform_average', 'variance_weighted']")
-
-# %%