fix(plotting): refactor combi_plot with improved visual API

README.md

@@ -27,6 +27,36 @@ Or using [uv](https://docs.astral.sh/uv/):
 uv pip install sdcpy
 ```
 
+## Usage
+
+```python
+import numpy as np
+import pandas as pd
+from sdcpy import SDCAnalysis
+
+# Synthetic signal with transient pattern between indices 63-169
+def tc_signal(i):
+    error = np.random.normal()
+    if 63 <= i <= 169:
+        return np.sin(2 * np.pi * (1 / 37) * i) + 0.6 * error
+    return error
+
+np.random.seed(42)
+ts1 = pd.Series([tc_signal(i) for i in range(250)])
+ts2 = pd.Series([tc_signal(i) for i in range(250)])
+
+# Run SDC analysis
+sdc = SDCAnalysis(ts1, ts2, fragment_size=50, n_permutations=99)
+
+# Generate combination plot
+fig = sdc.combi_plot(xlabel="TS1", ylabel="TS2")
+fig.savefig("sdc_plot.png", dpi=150, bbox_inches="tight")
+```
+
+<img src="sdc_example.png" width="500" />
+
+See [examples/basic_usage.py](examples/basic_usage.py) for a complete example with synthetic data showing transient correlations.
+
 ## Development
 
 To set up a local development environment:

examples/basic_usage.py

@@ -0,0 +1,35 @@
+"""Example script demonstrating SDCAnalysis with synthetic data."""
+
+import numpy as np
+import pandas as pd
+
+from sdcpy import SDCAnalysis
+
+
+def tc_signal(i):
+    """Synthetic signal from original SDC paper (Rodriguez-Arias & Rodó, 2004).
+
+    Creates a time series with a transient sinusoidal pattern
+    embedded in noise between indices 63-169.
+    """
+    error = np.random.normal()
+    if i < 63 or i > 169:
+        return error
+    else:
+        return np.sin(2 * np.pi * (1 / 37) * i) + 0.6 * error
+
+
+if __name__ == "__main__":
+    np.random.seed(42)
+
+    # Generate two synthetic time series with transient correlations
+    ts1 = pd.Series([tc_signal(i) for i in range(250)], name="ts1")
+    ts2 = pd.Series([tc_signal(i) for i in range(250)], name="ts2")
+
+    # Run SDC analysis with fragment size of 50
+    sdc = SDCAnalysis(ts1, ts2, fragment_size=50, n_permutations=99)
+
+    # Generate combination plot
+    fig = sdc.combi_plot(xlabel="$TS_1$", ylabel="$TS_2$")
+    fig.savefig("sdc_example.png", dpi=300, bbox_inches="tight")
+    print("Saved: sdc_example.png")

sdcpy/__init__.py

@@ -7,15 +7,15 @@
 # Public API
 from sdcpy.core import compute_sdc, generate_correlation_map, shuffle_along_axis
 from sdcpy.io import load_from_excel, save_to_excel
-from sdcpy.plotting import plot_two_way_sdc
+from sdcpy.plotting import combi_plot
 from sdcpy.scale_dependent_correlation import SDCAnalysis
 
 __all__ = [
     "SDCAnalysis",
     "compute_sdc",
     "generate_correlation_map",
     "shuffle_along_axis",
-    "plot_two_way_sdc",
+    "combi_plot",
     "save_to_excel",
     "load_from_excel",
 ]