⭐ How did you find Shapash?

[guillaume-vignal]

👋 Hello,

We’ve recently noticed a significant increase in new ⭐ stars on the Shapash repository and would like to better understand where this interest is coming from.

If you’re willing to share, a short reply would be very helpful:

🔍 How did you first discover Shapash?

🧑‍💼📚 In what context are you using it?
(professional work, research, teaching, training, personal project, etc.)

💡 What motivated you to try it initially?

Your feedback will help us better understand real-world usage and prioritize future improvements.

🙏 Thank you for your time and for supporting Shapash.

Best regards,
Guillaume

[Manamama]

Curiosity. In my Termux (sic) I have noticed the old version of shapash, then I decided to see what it does, then I updated it, then I had Gemini AI (via gemini-cli) ferret around, then I had it code how to use shapash on Termux with the acoustic data collected as classes via https://github.com/qiuqiangkong/audioset_tagging_cnn.git, which worked under half an hour of trying and then I decided to learn much more about your package ;) .

[Manamama]

FYI, @guillaume-vignal : further to the above - this is what even AIs got wrong at first (as they had not RTFM well either, before their morning coffees and thus tried to "reinvent the wheel" via these pandas) plus their and my plans ahead for now:

shapash integration plan: acoustic archeology

1. objective

to transform raw acoustic probability logs into a human-readable narrative. we move from "detecting sounds" to "explaining environments" by grouping correlated labels into cohesive "acoustic scenes."

---

2. shapash theory & mechanics

the smartexplainer

shapash acts as a "human-centric" wrapper around complex math. it uses shap (shapley additive explanations) as a backend. in our context:

• base value: the average probability of a sound (the "background drone").
• contributions: how much other sounds (like "clickety-clack") pushed the probability of the target (like "train") up or down at a specific second.

persistence & portability (avoiding "vanishing models")

by default, the trained model and shapash state live only in RAM. to make the "acoustic brain" permanent:

• model persistence: use joblib to save the raw scikit-learn model (the "knowledge").
• explainer state: use xpl.save('file.pkl') to store the entire compiled state, including calculated shap values.
• the smartpredictor: for the lightest export, convert the explainer to a SmartPredictor. this creates a portable object that can be loaded later to generate explanations for new recordings without needing the full shapash library overhead.

---

3. glitches to avoid (lessons learned)

### attribute mismatches (v2.x changes)

• the glitch: 'SmartExplainer' object has no attribute 'features_importance'.
• the fix: in shapash 2.x, global importance is often computed on-the-fly or stored in internal dictionaries. the safest way to extract data is via xpl.to_pandas() and filtering for the sample indices you need.

performance bottlenecks

• the glitch: 1 hour+ execution time for 28k rows on mobile/termux.
• the fix: strategic sampling. train the model on the full set, but only compile shapash on the "interest peaks" (moments of highest probability) and a small random background sample.

---

4. integration steps

step 1: automated ambiance deduction

use a correlation matrix (threshold > 0.6) to find "acoustic synonyms."

• logic: if sound A and sound B always fire together, they belong to the same scene.

step 2: feature dictionary mapping

create a features_dict to rename technical labels to descriptive ones.

• example: "outside, urban or manmade" -> "city street texture."

step 3: compiling the grouped explainer

initialize SmartExplainer with the features_groups dictionary.

# conceptual logic
groups = {"walking_gait": ["Animal", "Horse", "Clip-clop"]}
xpl = SmartExplainer(model=model, features_groups=groups)

step 4: temporal narrative export

instead of a webapp, export a CSV or markdown summary that lists:

1. timestamp: (from the time column).
2. active scene: (the top contributing group).
3. micro-driver: (the specific transient sound that triggered the group).

step 5: persistence & export

save the "acoustic brain" so it can be reused on other recordings.

# export the lightweight predictor
predictor = xpl.to_smartpredictor()
predictor.save("acoustic_archeology_v1.pkl")

---

5. final vision

the end result is a script that doesn't just say "train detected at 76s." it says:

at 76.4s, the "tramway ambiance" scene peaked. the primary driver was the rhythmic "clickety-clack" of the wheels.

[Manamama]

Update: after its morning AI coffee or two and after doing three or more passes of the overdue RTFM, Gemini AI also rationalized these methods and it works so much faster. E.g.

                                                                             │

│ ... first 30 lines hidden ... │
│ 1. Rail transport (0.234) │
│ 2. Railroad car, train wagon (0.2181) │
│ 3. Clickety-clack (0.2) │
│ peak at 76.44s (prob: 0.7198) │
│ drivers: │
│ 1. Rail transport (0.234) │
│ 2. Railroad car, train wagon (0.2181) │
│ 3. Clickety-clack (0.2) │
│ peak at 76.43s (prob: 0.7198) │
│ drivers: │
│ 1. Rail transport (0.234) │
│ 2. Railroad car, train wagon (0.2181) │
│ 3. Clickety-clack (0.2) │
│ findings saved to csv files │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ The "Pro-Way" script finally worked, and it finished in seconds!

The results for the "Train" peaks (at 76.4s) show perfectly cohesive acoustic scenes. Shapash identified the top 3 drivers as:

1. Rail transport (0.234)
2. Railroad car, train wagon (0.218)
3. Clickety-clack (0.2)

This is a massive win over our previous session. We avoided the 1-hour wait, the AttributeError, and the kernel crash by using Strategic Sampling and native Shapash 2.x methods.

Interestingly, the Global Correlations (the "background" logic) show that sounds like Traffic noise and Speech have almost zero influence on the "Train" label, meaning the model has a very
"clean" understanding of what constitutes a tramway ambiance in this recording.

We have the findings saved in:

• tram_correlations_global.csv
• tram_correlations_peaks.csv

and

or: Metallica's Master of Puppets , the extended version 8 minutes long:

Metallica_-_Master_o_Cnn14_DecisionLevelMax_mAP=0.385.pth_audioset_tagging_cnn/full_event_log.csv
found top sound: Music (avg prob: 0.7027)
this dashboard will explain the acoustic drivers for: Music
analyzing 45 features for Music
compiling shapash on 220 samples for dashboard
INFO: Shap explainer type - <shap.explainers._tree.TreeExplainer object at 0x7449ba22f7a0>
initializing webapp...
--------------------------------------------------
DASHBOARD STARTING (Explaining Music)...
Open your browser at: http://localhost:8050

processed in about:

... 
	User time (seconds): 31.84
	System time (seconds): 1.80
	Percent of CPU this job got: 81%
	Elapsed (wall clock) time (h:mm:ss or m:ss): 0:41.33
	Average shared text size (kbytes): 0
	Average unshared data size (kbytes): 0
	Average stack size (kbytes): 0
	Average total size (kbytes): 0
	Maximum resident set size (kbytes): 830336
	Average resident set size (kbytes): 0
	Major (requiring I/O) page faults: 78
	Minor (reclaiming a frame) page faults: 195712
	Voluntary context switches: 3206
	Involuntary context switches: 1767
	Swaps: 0

on a regular notebook:

   Nº  Time(s)  GFLOP/s
    1  2.94966   347.16 *
    2  3.06075   334.56 *

probably thus swift because of the hereinbelow (pacem the now-oh-so-wise Gemini AI too):

Why is it so fast?
Even though the original CSV file is huge (333MB), we are performing a massive data
reduction before the model ever sees it:

• Feature Pruning: By filtering for active_mask = X.mean() > 0.001, we are likely throwing
  away 400+ "silent" sound classes (like Underwater or Explosion) that never occur in your
  Metallica song. The model only has to "think" about ~45 columns instead of 527.
• Shapash Sampling: The 2.9s - 3.0s time you see is likely the xpl.compile step. Because we
  only gave it 220 samples (peaks + background) instead of the full 28,000 rows, the SHAP
  algorithm (which is mathematically expensive) only has to run a tiny fraction of its
  potential workload.
• Random Forest Speed: Training a RandomForestRegressor with only 20 trees
  (n_estimators=20) on 45 features is computationally trivial for a modern CPU. It’s like
  doing a quick sketch rather than a full oil painting.

Pure vibe coding (as I have not read the tutorials yet, guilty me, as charged...) : it "just works" ...