Troubleshooting

This section provides solutions to common issues encountered when using CBR-FoX.

Installation Issues

ModuleNotFoundError: No module named ‘cbr_fox’

Problem: Python cannot find the cbr_fox module after installation.

Solution:

Verify the package is installed:

pip list | grep CBR-FoX

If not listed, reinstall:

pip install CBR-FoX

Ensure you’re using the correct Python environment:

which python
python --version

ImportError: cannot import name ‘cbr_fox’

Problem: Import fails even after installation.

Solution:

Check if the package is correctly installed:

pip show CBR-FoX

Try importing from the correct path:

from cbr_fox.core import cbr_fox
from cbr_fox.builder import cbr_fox_builder

If still failing, reinstall in development mode:

git clone https://github.com/aaaimx/CBR-FoX.git
cd CBR-FoX
pip install -e .

Dependency Conflicts

Problem: Version conflicts with NumPy, SciPy, or other dependencies.

Solution:

Create a clean virtual environment:

python -m venv cbr_fox_env
source cbr_fox_env/bin/activate  # Linux/Mac
cbr_fox_env\\Scripts\\activate    # Windows

Install with specific versions:

pip install numpy==2.0.2 scipy==1.13.1
pip install CBR-FoX

Runtime Errors

ValueError: shapes not aligned

Problem: Array shape mismatch during fit or predict.

Solution:

Ensure your data has the correct shape:

# Correct shapes:
training_windows.shape     # [n_windows, window_len, n_features]
target_training_windows.shape  # [n_windows, n_features]
forecasted_window.shape    # [window_len, n_features]
prediction.shape           # [n_features]

Example fix:

# If target_training_windows is 1D
if target_training_windows.ndim == 1:
    target_training_windows = target_training_windows.reshape(-1, 1)

# If prediction is 1D with single feature
if prediction.ndim == 0:
    prediction = np.array([prediction])

NaN values in correlation results

Problem: correlation_per_window contains NaN values.

Solution:

Check for NaN in input data:

print(np.isnan(training_windows).any())
print(np.isnan(forecasted_window).any())

Remove or impute NaN values:

training_windows = np.nan_to_num(training_windows, nan=0.0)
forecasted_window = np.nan_to_num(forecasted_window, nan=0.0)

Verify data ranges (avoid extreme values):

print(f"Training range: {training_windows.min()} to {training_windows.max()}")

Memory Errors with Large Datasets

Problem: MemoryError when processing large time series.

Solution:

Reduce the number of windows:

# Use a subset of windows
training_windows = training_windows[:1000]  # First 1000 windows
target_training_windows = target_training_windows[:1000]

Process in batches:

batch_size = 500
for i in range(0, len(training_windows), batch_size):
    batch = training_windows[i:i+batch_size]
    # Process batch

Use a smaller window length or fewer features

Metric-Specific Issues

DTW is extremely slow

Problem: Dynamic Time Warping takes too long.

Solution:

Use DTW with window constraint:

cbr = cbr_fox(metric="dtw", kwargs={"window": 0.1})

Consider faster alternatives:

# Euclidean is much faster
cbr = cbr_fox(metric="euclidean")

Reduce data dimensionality first

Custom metric not working

Problem: Custom callable metric throws errors.

Solution:

Ensure your custom metric follows the correct signature:

def custom_metric(input_data_dictionary, **kwargs):
    """
    Custom distance metric.

    Parameters
    ----------
    input_data_dictionary : dict
        Contains 'training_windows', 'forecasted_window', etc.
    **kwargs : dict
        Additional parameters

    Returns
    -------
    np.ndarray
        Shape [n_windows, 1] with distance values
    """
    n_windows = input_data_dictionary['windows_len']
    # Your computation here
    distances = np.random.rand(n_windows, 1)  # Example
    return distances

Test it before using:

# Create test input
test_input = {
    'training_windows': np.random.randn(10, 12, 2),
    'forecasted_window': np.random.randn(12, 2),
    'windows_len': 10,
    'components_len': 2
}

result = custom_metric(test_input)
assert result.shape == (10, 1), f"Wrong shape: {result.shape}"

Visualization Problems

Plots not showing

Problem: visualize_pyplot() doesn’t display plots.

Solution:

In Jupyter notebooks, use:

%matplotlib inline
builder.visualize_pyplot()

In scripts, add:

import matplotlib.pyplot as plt
builder.visualize_pyplot()
plt.show()  # Force display

Save plots instead:

figs = builder.visualize_pyplot()
for i, (fig, ax) in enumerate(figs):
    fig.savefig(f'plot_{i}.png')

Empty or incomplete plots

Problem: Plots appear but show no data.

Solution:

Verify data was fitted and predicted:

print(f"Best windows: {len(cbr.best_windows_index)}")
print(f"Analysis report: {cbr.analysisReport is not None}")

Check num_cases value:

# Ensure num_cases isn't too large
max_cases = len(cbr.best_windows_index)
cbr.predict(prediction, num_cases=min(5, max_cases))

Performance Issues

Slow execution with large datasets

Problem: CBR-FoX takes too long to process data.

Solutions:

Use faster metrics:

# Fast: euclidean, squared
# Medium: pearson
# Slow: dtw, edr, erp

Reduce smoothness iterations:

cbr = cbr_fox(metric="euclidean", smoothness_factor=0.1)  # Less smoothing

Parallel processing (for multiple techniques):

from concurrent.futures import ProcessPoolExecutor

def fit_technique(technique):
    technique.fit(train_w, target_w, forecast_w)
    return technique

with ProcessPoolExecutor() as executor:
    results = executor.map(fit_technique, techniques)

High memory usage

Problem: Process uses too much RAM.

Solution:

# Clear intermediate results
del cbr.concaveSegments
del cbr.convexSegments
import gc
gc.collect()

Docker Issues

Container fails to start

Problem: Docker container exits immediately.

Solution:

Check if tests exist:

docker run cbr_fox ls tests/

Run without tests:

docker run cbr_fox python -c "from cbr_fox.core import cbr_fox; print('OK')"

Check logs:

docker logs <container_id>

Image size too large

Problem: Docker image is several GB.

Solution:

Use the slim Dockerfile:

docker build -f Dockerfile -t cbr_fox:slim .
docker images cbr_fox:slim

Platform-Specific Issues

Windows: DLL load failed

Problem: Import fails with DLL errors on Windows.

Solution:

Install Microsoft Visual C++ Redistributable
Use conda instead of pip:

conda create -n cbr_fox python=3.11
conda activate cbr_fox
conda install -c conda-forge numpy scipy scikit-learn
pip install CBR-FoX

macOS: SSL Certificate errors

Problem: Cannot download packages due to SSL errors.

Solution:

/Applications/Python\\ 3.11/Install\\ Certificates.command
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org CBR-FoX

Linux: Permission denied errors

Problem: Cannot write to installation directory.

Solution:

# Install for user only
pip install --user CBR-FoX

# Or use virtual environment
python -m venv venv
source venv/bin/activate
pip install CBR-FoX

Getting Help

If you encounter issues not covered here:

Check GitHub Issues: https://github.com/aaaimx/CBR-FoX/issues
Ask in Discussions: https://github.com/aaaimx/CBR-FoX/discussions
Email Support: jerryperezperez@hotmail.com

When reporting issues, please include:

CBR-FoX version: pip show CBR-FoX
Python version: python --version
Operating system
Full error traceback
Minimal reproducible example

Common Error Messages

Quick reference for error messages:

For additional help, see the API Documentation or Examples.