return data class instead of dictionary

[zslade]

Type of PR

• BUG
• FEAT
• MAINT
• DOC

Is your Pull Request linked to an existing Issue or Pull Request?

#1677 and #1806

Give a brief description for the solution you have provided

Following user feedback, the _compute_graph_metrics() method has been updated to return a data class, instead of a dictionary of splink dataframes.

• This provides a more familiar API syntax, e.g. compute_graph_metrics.nodes
• A repr description has been included to give a useful print out to the user
• Can be unpacked like a tuple (instructions included in the repr)

I have tested on the fake_100 dataset. To reproduce:

    from splink.datasets import splink_datasets
    from splink.duckdb.blocking_rule_library import block_on, exact_match_rule
    from splink.duckdb.comparison_library import (
        exact_match,
        levenshtein_at_thresholds,
    )
    from splink.duckdb.linker import DuckDBLinker
    
    import ssl
    
    ssl._create_default_https_context = ssl._create_unverified_context
    
    df = splink_datasets.fake_1000
    
    settings = {
        "probability_two_random_records_match": 0.01,
        "link_type": "dedupe_only",
        "blocking_rules_to_generate_predictions": [
            block_on(["first_name"]),
            exact_match_rule("surname"),
        ],
        "comparisons": [
            levenshtein_at_thresholds("first_name", 2),
            exact_match("surname"),
            exact_match("dob"),
            exact_match("city", term_frequency_adjustments=True),
            exact_match("email"),
        ],
        "retain_intermediate_calculation_columns": True,
        "additional_columns_to_retain": ["cluster"],
        "max_iterations": 10,
        "em_convergence": 0.01,
    }
    
    
    linker = DuckDBLinker(df, settings)
    
    linker.estimate_u_using_random_sampling(target_rows=1e6)
    
    
    blocking_rule = "l.first_name = r.first_name and l.surname = r.surname"
    linker.estimate_parameters_using_expectation_maximisation(blocking_rule)
    
    
    blocking_rule = "l.dob = r.dob"
    linker.estimate_parameters_using_expectation_maximisation(blocking_rule)
    
    
    df_predict = linker.predict()
    df_clustered = linker.cluster_pairwise_predictions_at_threshold(df_predict, 0.9)
    
    df_graph_metrics = linker._compute_graph_metrics(
        df_predict=df_predict, df_clustered=df_clustered, threshold_match_probability=0.9
    )
    
    node_metrics, edge_metrics, cluster_metrics = (
        df_graph_metrics.nodes,
        df_graph_metrics.edges,
        df_graph_metrics.clusters,
    )

    node_metrics.as_pandas_dataframe()

PR Checklist

• Added documentation for changes
• Added feature to example notebooks or tutorial (if appropriate)
• Added tests (if appropriate)
• Updated CHANGELOG.md (if appropriate)
• Made changes based off the latest version of Splink
• Run the linter

[ADBond]

Looks good - definitely think this is a bit nicer to use.

Couple of comments, but happy for you to decide what to do with them. If you do decide to implement the iteration will be happy to have another look over after

[ADBond]

I think that the suggestion was to be able to unpack directly, node_metrics, edge_metrics, cluster_metrics = df_graph_metrics, or more likely in practice:

node_metrics, edge_metrics, cluster_metrics = linker.compute_graph_metrics(...)

so that you can immediately bypass the class itself if you want. Might want to check with Tom though if that's what he meant.

I'm personally not massively fussed about this feature though, so happy to leave if it's going to be too fiddly

[zslade]

I'm happy to leave for now and implement at a later date if the user need becomes apparent :)

[ADBond]

Just personal preference but I always find it weird having multi-line strings that mess with the indentation like this - I think that using implicit continuation and explicit newline "\n" characters reads clearer (see for example SplinkDataFrame.__repr__).

But not a big deal at all, so am fine if I'm in the minority on this

[zslade]

This is really useful feedback! It looks icky to me too so have updated 👍