Update docstrings (#18)

* update core.py docstring

* formatting

* formatting

* update doc

* change package name

.flake8

@@ -1,2 +1,3 @@
 [flake8]
 max-line-length = 127
+per-file-ignores = setup.py:F821

README.rst

@@ -1,4 +1,4 @@
-Focus-cfe
+CFXplorer
 ==========================================================================
 
 **Deployment & Documentation & Stats & License**
@@ -36,7 +36,7 @@ Focus-cfe
 
 ---------
 
-Focus-cfe generates optimal distance counterfactual explanations of the original data for the instances in tree‐based machine learning models.
+CFXplorer generates optimal distance counterfactual explanations of the original data for the instances in tree‐based machine learning models.
 
 This package is an implementation of `FOCUS: Flexible Optimizable Counterfactual Explanations for Tree Ensembles (Lucic, et at. 2022) <https://arxiv.org/abs/1911.12199>`_.
 
@@ -48,8 +48,8 @@ It is recommended to use **pip** or **conda** for installation. Please make sure
 
 .. code-block:: bash
 
-   pip install focus-cfe            # normal install
-   pip install --upgrade focus-cfe  # or update if needed
+   pip install CFXplorer            # normal install
+   pip install --upgrade CFXplorer  # or update if needed
 
 .. code-block:: bash
 
@@ -69,7 +69,7 @@ Usage
 
 .. code-block:: python
 
-    from focus import Focus
+    from cfxplorer import Focus
     # Initialize Focus instance with default values
     focus = Focus()
 
@@ -90,17 +90,17 @@ Examples
     :scale: 100 %
     :alt: Before and After FOCUS was applied to the features from above example.
 
-Limitations
------------
+Limitations of Focus class
+--------------------------
 
-- Currently, Focus-cfe can only be applied to scikit-learn ``DecisionTreeClassifier``, ``RandomForestClassifier`` and ``AdaBoostClassifier``.
+- Currently, Focus class can only be applied to scikit-learn ``DecisionTreeClassifier``, ``RandomForestClassifier`` and ``AdaBoostClassifier``.
 - While categorical features may be included in the feature set, it is important to note that the interpretation of changes in categorical features, such as transitioning from age 40 to 20, may not provide meaningful insights.
-- The input features should be scaled to the range of 0 and 1 before applying Focus-cfe. Therefore, it is necessary to transform the features prior to using Focus-cfe. However, this scaling process may introduce some additional complexity when interpreting the features after applying Focus-cfe.
+- The input features should be scaled to the range of 0 and 1 before applying Focus-cfe. Therefore, it is necessary to transform the features prior to using Focus. However, this scaling process may introduce some additional complexity when interpreting the features after applying Focus.
 
 Documentation
 -------------
 
-The documentation can be found `here <https://focus-cfe.readthedocs.io/en/latest/>`_.
+The documentation can be found `here <https://cfxplorer.readthedocs.io/en/latest/>`_.
 
 Contributing
 ------------

focus/__init__.py → cfxplorer/__init__.py

@@ -1,4 +1,4 @@
-from .core import Focus
+from cfxplorer.focus.core import Focus
 
 # Let users know if they're missing any of our hard dependencies
 _hard_dependencies = ("tensorflow", "numpy")

focus/core.py → cfxplorer/focus/core.py

@@ -70,9 +70,9 @@ class Focus:
     - Initialize FOCUS with default parameters
     - Generate counterfactual explanations
 
-    focus-cfe = Focus()
+    cfxplorer = Focus()
 
-    cfe_features = focus-cfe.generate(model, X)
+    cfe_features = cfxplorer.generate(model, X)
     """
 
     def __init__(
@@ -341,7 +341,6 @@ def parse_class_tree(tree, X, sigma: float) -> list:
         for i in range(n_nodes):
             cur_node = nodes[i]
             if children_left[i] != children_right[i]:
-
                 if cur_node is None:
                     cur_node = 1.0
 

focus/utils.py → cfxplorer/focus/utils.py

@@ -2,7 +2,7 @@
 import tensorflow as tf
 
 
-def safe_euclidean(matrix_diff, epsilon=10.0 ** -10) -> tf.Tensor:
+def safe_euclidean(matrix_diff, epsilon=10.0**-10) -> tf.Tensor:
     """
     Calculates the Euclidean distance between two matrices with a small epsilon added to prevent singularities.
 
@@ -13,10 +13,10 @@ def safe_euclidean(matrix_diff, epsilon=10.0 ** -10) -> tf.Tensor:
     Returns:
     tf.Tensor: A tensor representing the Euclidean distance between the two matrices
     """
-    return (tf.reduce_sum(matrix_diff ** 2, axis=-1) + epsilon) ** 0.5
+    return (tf.reduce_sum(matrix_diff**2, axis=-1) + epsilon) ** 0.5
 
 
-def safe_cosine(feat_input, perturbed, epsilon=10.0 ** -10) -> tf.Tensor:
+def safe_cosine(feat_input, perturbed, epsilon=10.0**-10) -> tf.Tensor:
     """
     Calculates cosine distance between two input arrays `feat_input` and `perturbed`
     while ensuring numerical stability with `epsilon`.
@@ -42,7 +42,7 @@ def safe_cosine(feat_input, perturbed, epsilon=10.0 ** -10) -> tf.Tensor:
     return dist
 
 
-def safe_l1(matrix_diff, epsilon=10.0 ** -10) -> tf.Tensor:
+def safe_l1(matrix_diff, epsilon=10.0**-10) -> tf.Tensor:
     """
     Calculates the L1 (Manhattan) distance between two tensors with a small epsilon value
     added to prevent division by zero.
@@ -76,7 +76,7 @@ def tf_cov(x_train) -> tf.Tensor:
     return cov_xx
 
 
-def safe_mahal(matrix_diff, x_train, epsilon=10.0 ** -10) -> tf.Tensor:
+def safe_mahal(matrix_diff, x_train, epsilon=10.0**-10) -> tf.Tensor:
     """
     Calculates Mahalanobis distance using TensorFlow
 

focus/tests/test_focus.py → cfxplorer/tests/test_focus.py

@@ -4,7 +4,7 @@
 from sklearn.ensemble import AdaBoostClassifier, RandomForestClassifier
 from sklearn.tree import DecisionTreeClassifier
 
-from focus import Focus
+from cfxplorer import Focus
 
 x_train, y_train = make_classification(
     n_samples=200, n_features=10, n_classes=2, random_state=42

focus/tests/test_utils.py → cfxplorer/tests/test_utils.py

@@ -4,7 +4,7 @@
 import pytest
 import tensorflow as tf
 
-from focus.utils import (
+from cfxplorer.focus.utils import (
     calculate_distance,
     safe_cosine,
     safe_euclidean,
@@ -13,7 +13,7 @@
     tf_cov,
 )
 
-epsilon = 10.0 ** -10
+epsilon = 10.0**-10
 random.seed(42)
 
 covariance_test_data = [
@@ -88,7 +88,7 @@ def test_tf_cov(feat_input_cov, expected_output_cov):
 
 @pytest.mark.parametrize("feat_input, feat_input2", distance_test_data)
 def test_safe_euclidean(feat_input, feat_input2):
-    expected = (np.sum(feat_input2 ** 2, axis=-1) + epsilon) ** 0.5
+    expected = (np.sum(feat_input2**2, axis=-1) + epsilon) ** 0.5
     assert safe_euclidean(feat_input).numpy() == pytest.approx(expected)
 
 

focus/version.py → cfxplorer/version.py

@@ -1,5 +1,5 @@
 """
-``focus-cfe`` is a python package for
+``cfxplorer`` is a python package for
 generating counterfactual explanations for a tree-based model
 """
 # PEP0440 compatible formatted version, see:
@@ -18,4 +18,4 @@
 # Dev branch marker is: 'X.Y.dev' or 'X.Y.devN' where N is an integer.
 # 'X.Y.dev0' is the canonical version of 'X.Y.dev'
 #
-__version__ = "0.0.dev3"  # pragma: no cover
+__version__ = "0.0.dev4"  # pragma: no cover

docs/conf.py

@@ -18,7 +18,7 @@
 
 # -- Project information -----------------------------------------------------
 
-project = "focus-cfe"
+project = "cfxplorer"
 copyright = "2023, Kyosuke Morita"
 author = "Kyosuke Morita"
 

docs/index.rst

@@ -1,10 +1,6 @@
-.. include:: ../README.rst
-
-**Links**: |
-`GitHub repository <https://github.com/kyosek/focus>`__ |
-`PyPI <https://pypi.org/project/focus-cfe/>`__ |
-
-=====================================
+================================
+Welcome to cfepy's documentation
+================================
 
 Contents
 --------
@@ -15,3 +11,9 @@ Contents
    Home <self>
    usage
    api
+
+**Links**: |
+`GitHub repository <https://github.com/kyosek/focus>`__ |
+`PyPI <https://pypi.org/project/focus-cfe/>`__ |
+
+.. include:: ../README.rst

environment.yml

@@ -1,4 +1,4 @@
-name: focus-cfe
+name: cfxplorer
 dependencies:
   - tensorflow
   - numpy

examples/focus_example.py

@@ -8,7 +8,7 @@
     train_decision_tree_model,
 )
 
-from focus import Focus
+from cfxplorer import Focus
 
 
 def run_example():

examples/hyperparameter_tuning_example.py

@@ -6,7 +6,7 @@
     train_decision_tree_model,
 )
 
-from focus import Focus
+from cfxplorer import Focus
 
 
 def objective(trial):
@@ -60,7 +60,6 @@ def objective(trial):
 
 
 if __name__ == "__main__":
-
     study = optuna.create_study(direction="minimize")
     study.optimize(objective, n_trials=100)
 

examples/utils.py

@@ -84,14 +84,14 @@ def prepare_plot_df(model, X, X_focus):
     Args:
         model (object): A trained machine learning model capable of making predictions.
         X (array-like): The input data for which predictions are made.
-        X_focus (array-like): Additional input data used for focus-cfe predictions.
+        X_focus (array-like): Additional input data used for cfxplorer predictions.
 
     Returns:
         tuple: A tuple containing two pandas DataFrames.
             - The first DataFrame contains the PCA-transformed features of `X`
                 and the corresponding predictions.
             - The second DataFrame contains the PCA-transformed features of `X_focus`
-                and the corresponding focus-cfe predictions.
+                and the corresponding cfxplorer predictions.
     """
     pca = PCA(n_components=2)
 

setup.py

@@ -4,13 +4,12 @@
 from setuptools import find_packages, setup
 
 DESCRIPTION = (
-    "FOCUS is a python package for "
-    "generating counterfactual explanations for a tree-based model"
+    "CFXplorer is a python package for " "generating counterfactual explanations"
 )
 
 
 # get __version__ from _version.py
-ver_file = path.join("focus", "version.py")
+ver_file = path.join("cfxplorer", "version.py")
 with open(ver_file) as f:
     exec(f.read())
 
@@ -28,7 +27,7 @@ def readme():
     requirements = f.read().splitlines()
 
 setup(
-    name="focus-cfe",
+    name="CFXplorer",
     version=__version__,
     author="Kyosuke Morita",
     author_email="kq441morita@gmail.com",