feat: add Explanation.to_markdown() for notebooks and reports (#1)

[DYNOSuprovo]

What

Closes #1

Adds Explanation.to_markdown(k=10) -> str to render explanations as formatted Markdown tables for notebooks, pull request descriptions, and reports.

Why

Currently, Explanation supports to_text(), to_dataframe(), to_dict(), and plot(). When embedding explanations in Markdown documents, reports, or PR descriptions, a native Markdown table is cleaner and more readable than plain text.

How

• Added Explanation.to_markdown(k=10):
  • Reuses _headline() for the summary line.
  • Generates table with feature | value | attribution columns for local explanations, or feature | attribution when feature_values is None (such as in global explanations).
  • Automatically incorporates one column per component method for ConsensusExplanation using normalised attributions via _markdown_component_data().
  • Reuses _extra_text() to append agreement level hints for consensus explanations (or surrogate fit $R^2$).
  • Built by hand without external dependencies (no tabulate).
• Added unit tests in tests/test_explanation.py covering local classification, row limits via k, global explanations, regression, consensus explanations with method columns, and surrogate $R^2$.
• Updated README.md's "The Explanation object" table and CHANGELOG.md under [Unreleased].

Checklist

• Tests added / updated and pytest passes
• ruff check and ruff format --check pass
• Docs / README / CHANGELOG updated where relevant
• Randomness goes through self.rng (reproducible with random_state)

[adaumsilva]

Thanks for implementing this! The tests pass, but the table needs to escape its headers and cell contents before joining them.

For example, a feature named income|monthly introduces an extra column, and a feature value containing a newline breaks the row. This also affects custom consensus method names used as column headers.

Please add a shared Markdown-escaping helper for headers and cells. Handle pipes and backslashes, and convert embedded line breaks into a representation that stays within one table row.

Please add regression tests covering these characters in feature names, feature values, and consensus method headers. Once this is corrected, the implementation should be ready for another review.

[adaumsilva]

@DYNOSuprovo thanks for the work! I requested a few changes before merging the PR. Please address these changes and submit the PR again.

[DYNOSuprovo]

Hi @adaumsilva! 👋 I've implemented the requested Markdown escaping and added comprehensive regression tests:

1. Shared _escape_markdown(text)\ helper:
   • Escapes backslashes (\\) as \\\\\.
   • Escapes table delimiter pipes (|) as \|\ to prevent splitting extra columns.
   • Converts embedded line breaks (\r\n, \r, \n) into <br>\ so rows stay on a single table line.
2. Applied across all headers and cells:
   • Headers (including custom consensus method names).
   • Cell contents (feature names, formatted feature values, attributions, and component contributions).
3. **Regression tests in \ ests/test_explanation.py**:
   • \ est_escape_markdown_helper: unit tests for pipes, backslashes, CRLF/LF newlines, and combined cases.
   • \ est_to_markdown_escapes_special_characters: verifies escaping in feature names (\income|monthly, \path\name), multi-line and special character values (\line1\nline2, \�al|pipe, \�al\slash), and asserts table row counts stay intact.
   • \ est_to_markdown_consensus_escapes_method_headers_and_values: verifies custom consensus headers with pipes, backslashes, and newlines (\custom|method, \�lgo\v2, \method\nwith\nnewline).
4. All 91 unit tests and
   uff check\ pass cleanly.

Ready for your review!

[adaumsilva]

Solid work @DYNOSuprovo ! Thanks for addressing the changes. PR approved and merged. Remember to star the repo if you didn't yet.

[DYNOSuprovo]

Thanks @adaumsilva for merging! Starred the repository — glad to contribute to XAI-framework.