API reference
tareco 1.5.0. Written from the code itself.
Start here
One call from a table to an answer. Every function takes what Graph takes: a CSV or Excel path, a DataFrame, a list of rows.
tareco.show(data, **options)
Draw anything that looks like a graph, in one line.
data is whatever Graph accepts (CSV path, DataFrame, list of pairs, dict...). Loading options (directed, nodes, source, target, node_id) and view options (color, size, label, title, dim...) can be mixed freely.
tareco.save(data, path, **options)
Like show, but writes a standalone HTML file and returns its path.
tareco.explain(data, **options)
What the network in data shows, in plain language (see Graph.explain).
>>> print(tareco.explain("transfers.csv", lang="pt"))tareco.report(data, path=None, **options)
One shareable HTML file about data: findings, tables and the graph (see Graph.report).
tareco.check(data, source=None, target=None, account=None, counterparty=None, amount=None, time=None, lang=None, max_rows=1000000)
What in data would mislead a graph made from it, with how many rows each thing touches.
Takes the same tables and column options as Graph (account/counterparty for statements). Looks for rows without both ends, placeholder ids ("N/A", "0", "UNKNOWN"), links from a node to itself, duplicated rows, ids written two ways ("123" and 123, "ACME " and "acme"), amounts that are text or zero, statements with no money out, and dates that cannot be read.
tareco.load(path)
The graph saved in path by g.save("....tareco").
tareco.records(data, nodes, columns=None, max_rows=1000000)
The rows of data that mention any of nodes, in the table's own format.
data- Spark DataFrame (filtered in the cluster, nothing is collected), pandas or polars DataFrame, CSV/Excel path or rows.
nodes- one node or several: what
similar_to,nearor any finding pointed at. columns- the columns to look in (default: the source and target columns, found as when loading a graph).
>>> tareco.records(spark.table("statements"), found.nodes, columns=["account", "counterparty"])tareco.compare(before, after, lang=None, label=None, top=3)
What changed from before to after, in plain words.
Nodes and links that came and went, the change in total weight, nodes that rose in importance or jumped in connections, groups that formed, vanished or merged, and links that grew the most. Each finding keeps the nodes it is about.
tareco.timeline(data, time, freq='auto', source=None, target=None, directed=False, weight=None, nodes=None, cumulative=False, dayfirst=None, max_rows=1000000, account=None, counterparty=None, amount=None, skip=None)
A network that changes over time, built from a table of timed events.
data- CSV path, pandas/polars/Spark DataFrame or rows; one row per event.
time- the column with when it happened: dates, datetimes, ISO text, dd/mm/yyyy or mm/dd/yyyy text, or plain numbers (steps, years).
freq- "day", "week", "month", "quarter", "year", a number (bin size for numeric times) or "auto" (a sensible number of periods).
weight- column to add up per connection; by default an obvious one (amount, value, or the only number column), otherwise each event counts 1.
nodes- node attributes, like
Graph(nodes=...). cumulative- each snapshot holds everything up to its period.
dayfirst- for slash dates: True for dd/mm, False for mm/dd, None to infer.
account, counterparty, amount- read a bank statement, as in
Graph: money out negative, each transfer counted once even when both statements are in the table. skip- ids to leave out, with every row that has them ("N/A", "UNKNOWN").
tareco.neighborhood(data, start, hops=2, source=None, target=None, directed=False, direction='both', max_nodes=5000, max_rows=1000000)
Everything within hops steps of start, read from an edge table.
data- Spark DataFrame (queries run in Spark), pandas DataFrame, CSV path, or rows.
start- one node or a list of nodes.
direction- "both", "out" (follow edges forward) or "in" (backward).
max_nodes- stop growing at this many nodes; the last hop keeps its most connected nodes and the graph is marked
attrs["truncated"].
Each node gets a hop attribute (0 for the start), handy for show(color="hop").
tareco.project(data, nodes=None, via=None, method='count', min_shared=1, max_item_size=1000, max_rows=1000000, attrs=None)
Link the values of nodes that share values of via.
>>> purchases = [("ana", "rice"), ("bia", "rice"), ("bia", "coffee"), ("caio", "coffee")]
>>> g = project(purchases) # ana - bia (rice), bia - caio (coffee)data- a table: CSV path, pandas/polars/Spark DataFrame, rows or tuples.
nodes, via- column names (default: the first and the second column).
method- edge weight: "count" (shared items), "jaccard" (shared over all items of the pair, 0 to 1) or "newman" (each shared item counts 1/(people who have it - 1), so popular items matter less).
min_shared- drop pairs that share fewer items than this.
max_item_size- items shared by more nodes than this are skipped (a product everybody buys links everybody to everybody, and costs size^2 edges). None keeps them all.
attrs- more node attributes, like
Graph(nodes=...): a table (file, DataFrame, rows) keyed by the node.
Other columns that never change for the same node become node attributes; numeric columns that change are summed into <column>_total.
tareco.settings(reset=False, **changes)
Change the defaults of the investigation tools, or see them.
tareco.settings(name=value, ...) changes them from now on; as a with block, only inside it. tareco.settings() shows them, reset=True puts every one back. weights={"split": 5} changes the weight of one kind of signal and keeps the others. The names (see tareco.tuning.DEFAULTS):
split_limit, split_within, split_count, split_margin- splits: the amount to stay under, the time window, how many amounts make a pile, how close under the limit counts.
unusual_factor, unusual_history, unusual_top- unusual amounts: times the usual amount, transfers needed to judge, share of the largest amounts that can count.
fast_within, fast_share, fast_top- fast moves: time window, share that has to go out again, share of the largest amounts that can count.
misfit_factor, misfit_neighbors- misfits: times above or below the neighbors, neighbors needed.
fan_min, cycle_max, near_hops, shared_max- patterns: smallest fan, longest loop; closeness to a watch list; identifiers shared by more nodes tie nobody.
weights, repeat, repeat_cap- the work list: weight per kind of signal, and what each extra signal of a kind adds, up to a cap.
tareco.set_language(lang)
Language for explanations and the interactive view: "en", "pt" or "es"; None goes back to automatic.
tareco.doctor(spark=None, quick=False)
Run every check that can fail in a new environment and report each one.
Pass the notebook's spark session to check reading from Spark, neighborhoods, exports and timelines there (classic Spark or Spark Connect, as on Databricks serverless). Nothing is written outside memory and the temporary folder. quick skips the bigger graphs.
tareco.read_csv(path, nodes=None, *, directed=False, source=None, target=None, node_id=None)
Graph from a CSV of edges (and optionally a CSV of nodes).
Source/target columns are guessed (source, from, origem...) and fall back to the first two columns; every other column becomes an attribute.
tareco.read_json(path)
Graph from a node-link JSON file (the format to_json writes).
tareco.read_excel(path, sheet=None)
Rows of one sheet as dicts keyed by the header row (the first non-empty row).
sheet is a sheet name or position (default: the first sheet). Dates come back as datetimes, whole numbers as ints.
The graph
Load once, then ask it questions.
tareco.Graph(data=None, *, directed=None, nodes=None, source=None, target=None, node_id=None, weight=None, max_rows=1000000, kind=None, keep=None, account=None, counterparty=None, amount=None, source_kind=None, target_kind=None, skip=None, **attrs)
A graph with attributes on nodes and edges.
data can be almost anything with edges in it: a list of pairs, a dict of neighbors, a CSV/JSON path, a pandas, polars or Spark DataFrame, a networkx graph or another Graph. nodes adds node attributes from the same kinds of sources. Spark DataFrames are streamed to the driver and refused above max_rows rows (aggregate them in Spark first, or pass max_rows=None).
weight names the column that says how strong each connection is (an amount, a count). Without it, a numeric column called weight, amount, value, quantity, total (or peso, valor, quantidade...) is used, or else the only number column. Every algorithm and the view then use it by default.
Tables can say more:
kind- what these links are ("transfer"); tables of other kinds join with
add_links. keep- True (or a list of columns) keeps the rows behind each link, for
rows()and for looking at single transfers. account, counterparty, amount- read a bank statement: one row per entry, money out negative.
source_kind, target_kind- the kinds of node at each end ("account", "device").
skip- ids to leave out, with every row that has them ("N/A", "UNKNOWN"). Placeholders that tie many rows together come with a warning.
>>> g = Graph([("ana", "bia"), ("bia", "caio", 2.5)])
>>> g.shortest_path("ana", "caio")['ana', 'bia', 'caio']
g.add_node(node, **attrs)
Add node (or update its attributes if it already exists).
g.add_nodes(nodes)
Add many nodes: plain ids or (id, {attributes}) pairs.
g.add_edge(u, v, **attrs)
Add an edge u -> v (or update its attributes). Missing nodes are created.
g.add_edges(edges)
Add many edges: (u, v), (u, v, weight) or (u, v, {attributes}).
g.add_links(data, source=None, target=None, *, kind=None, directed=None, keep=None, account=None, counterparty=None, amount=None, source_kind=None, target_kind=None, nodes=None, node_id=None, max_rows=1000000, skip=None)
Add one more table of links, usually of another kind, and return the graph.
>>> g = tareco.Graph(statements, account="account", counterparty="counterparty", kind="transfer")
>>> g.add_links(logins, source="account", target="device", kind="uses")The node kinds come from the column names ("account", "device") unless source_kind/target_kind say otherwise. Links between two different kinds of node have no direction unless directed=True; links between nodes of one kind follow the graph. Ids of different kinds that clash get a prefix ("device:123") and a warning.
g.remove_node(node)
Remove node and every edge touching it.
g.remove_edge(u, v)
g.nodes
g.edges
g.node_count
g.edge_count
g.has_node(node)
g.has_edge(u, v)
g.neighbors(node)
Nodes reachable in one step (successors, for directed graphs).
g.top_neighbors(node, n=5, weight='weight')
The neighbors node is most strongly connected to, as [(neighbor, weight), ...].
"Who buys X also buys", "who talks most to Ana": the heaviest edges first.
g.successors(node)
g.predecessors(node)
g.degree(node=None, weight=None)
Degree of node, or a dict with every node's degree.
With weight (an edge attribute name) the degree is the sum of the weights. Self-loops count twice in undirected graphs.
g.in_degree(node=None, weight=None)
g.out_degree(node=None, weight=None)
g.copy()
g.subgraph(nodes)
A new graph with only nodes and the edges between them.
g.ego(node, radius=1)
The neighborhood of node up to radius steps (ignoring direction).
g.reverse()
Copy with every edge flipped (a plain copy for undirected graphs).
g.to_undirected()
g.to_directed()
Directed copy; each undirected edge becomes two opposite edges.
g.kinds()
How many links and nodes of each kind: {"links": {...}, "nodes": {...}}.
g.only(*kinds)
A copy with just the links of these kinds and the nodes they touch.
g.only("transfer") leaves the logins out; None stands for links loaded without a kind.
g.rows(nodes=None, link=None, kind=None)
The rows behind the links, as they were in your table (needs keep= when loading).
nodes (one or several) keeps the rows that touch them, link=(a, b) the rows behind one link, kind the rows of one kind of link. .to_pandas() turns the result into a DataFrame.
g.shortest_path(source, target, weight=None)
List of nodes from source to target. weight names an edge attribute.
g.distance(source, target, weight=None)
Number of steps (or sum of weights) of the shortest path.
g.distances(source, weight=None)
Distance from source to every node it can reach.
g.diameter()
Longest shortest path, in steps.
g.pagerank(alpha=0.85, weight='weight')
g.betweenness(normalized=True, weight=None, k=None, seed=0, engine='auto')
Bridge score of each node. Pass k (e.g. 500) to estimate it fast on big graphs.
g.max_flow(source, target, capacity='weight')
How much can go from source to target, and the bottleneck edges (min cut).
g.k_shortest_paths(source, target, k=3, weight=None)
The k best loopless routes between two nodes, shortest first.
g.closeness(weight=None)
g.degree_centrality()
g.communities(weight='weight', resolution=1.0, seed=0)
Groups of densely connected nodes (Louvain), biggest first.
g.modularity(communities, weight='weight', resolution=1.0)
g.components()
Connected components (weakly connected, for directed graphs), biggest first.
g.strong_components()
g.is_connected()
g.clustering(node=None)
g.triangles(node=None)
g.core_number()
g.k_core(k=None)
Subgraph where every node has at least k neighbors (default: the innermost core).
g.spanning_tree(weight='weight', maximum=False)
g.topological_sort()
g.find_cycle()
One cycle as a list of nodes, or None. Any length, including a <-> b.
g.has_cycle()
g.suggest_links(node=None, top=10)
Likely missing edges as (u, v, score), best first (Adamic-Adar).
g.transitivity()
g.bfs(source)
g.dfs(source)
g.density()
g.explain(groups=None, lang=None, top=5, label=None, weight='weight')
The main facts about the network, in plain language ("en", "pt" or "es").
Groups, what characterizes each one, the most important nodes, bridges between groups, hubs, one-way flows and where the weight concentrates.
g.profile(groups=None, attrs=None, top=3, lang=None, label=None)
What characterizes each group (communities by default) compared with the whole network.
g.project(nodes, via=None, method='count', min_shared=1, max_item_size=1000)
Link nodes that share neighbors, like customers who share products.
nodes is the side to keep: a node kind ("account"), an iterable of nodes, or a predicate on (node, attrs). via limits what they share to one or more node kinds ("device"). See tareco.project for the methods.
>>> g.project("account", via="device") # accounts linked by the devices they shareg.patterns(kinds=None, lang=None, limit=10, weight='weight', max_cycle=None, label=None, min_fan=None)
Shapes worth a look: loops, fan-ins and fan-outs, relays, chains, stars, cliques.
Each pattern has kind, nodes, score and a plain-language text. Loops, fans, relays and chains need a directed graph.
g.unusual_amounts(factor=None, min_history=None, time=None, lang=None, label=None, limit=10)
Transfers far above what the sender usually sends (needs keep=).
factor- how many times the sender's usual (median) amount (10).
min_history- senders with fewer transfers than this are not judged (5).
Only amounts among the largest 5% of the network count. Each result has the rows of your table behind it. Defaults: tareco.settings.
g.splits(limit=None, within=None, min_count=None, margin=None, time=None, lang=None, label=None, top=10)
Many amounts just under a limit in a short time, by one sender or into one receiver.
>>> g.splits(limit=10_000, within="7 days")limit- the amount to stay under. Without it, amounts piling up just under any round number (1,000, 3,000, 5,000...) count.
within- how close in time ("7 days", "48 hours").
min_count- how many amounts make a pile (3; at least 5 without a limit).
margin- how close counts as "just under": 0.1 is within 10%.
Needs keep= and a date column. Defaults: tareco.settings.
g.fast_moves(within=None, share=None, time=None, lang=None, label=None, limit=10)
Nodes that receive a large amount and pass most of it on to others within a short time.
>>> g.fast_moves(within="3 days")within- how fast ("3 days", "48 hours").
share- how much of what came in has to go out again (0.8: at least 80%).
Only amounts among the largest 10% of the network, and far above what the node usually receives, count. Defaults: tareco.settings.
g.trace(source, target=None, within='30 days', hops=4, time=None, lang=None, label=None, limit=10)
Where money from source could have gone, following transfers in time order (needs keep=).
>>> g.trace("x01", "abroad") # the paths from x01 to abroad
>>> g.trace("x01", within="7 days") # everyone reached within a weekg.entities(via=None, max_share=None, lang=None, label=None)
Groups of nodes tied by identifiers they share (devices, phones, addresses): probably one person.
>>> people = g.entities(via="device")
>>> people.graph().review() # the same questions, per personIdentifiers shared by more than max_share nodes tie nothing.
g.misfits(attrs=None, factor=None, min_neighbors=None, lang=None, label=None, limit=10)
Nodes unlike the ones they deal with: a far lower or higher number, a rare category.
>>> g.misfits("monthly_income")attrs- node attributes to compare (default: every number and category).
factor- for numbers, how many times above or below the neighbors' median (10).
min_neighbors- neighbors with the attribute needed to judge a node (3).
g.near(targets, hops=None, lang=None, label=None, limit=10, kinds=None)
Nodes within hops steps of a list you give, and through whom (paths skip hubs).
>>> g.near(["a017", "a020"]) # or an attribute: g.near("flagged")g.flows(by, direction='to', weight='weight', lang=None, label=None)
How much of the flow goes to each value of an attribute (a country, a segment).
>>> g.flows(by="country")g.why(node, watch=None, lang=None, label=None)
What stands out about one node, in plain words: its flows, group, patterns, unusual amounts, what it shares with others and, with watch, how close it is to a list you give.
g.review(watch=None, limit=None, within=None, top=50, lang=None, label=None)
Every node something stands out about, ranked, with its reasons and the rows behind them.
>>> g.review(watch=["a017"]).to_pandas() # a work list for whoever investigatesg.similar_to(nodes, n=10, lang=None, label=None)
The nodes that behave most like nodes (one or a few known cases), with the reasons.
>>> g.similar_to("a017").nodes # ids to look up in your own tablesg.compare(after, lang=None, label=None, top=3)
What changed from this graph to after (another month, region, version), in words.
g.summary()
Headline numbers about the graph.
g.show(**options)
Open the interactive view (inline in notebooks, in the browser otherwise).
g.save(path, **options)
Write the interactive view to a standalone HTML file, a picture for .svg/.png, or the whole graph for .tareco.
Pictures are drawn in Python, for slides and e-mails: color, size, label, title, width, height, theme ("light", "dark"), labels (how many names to write) and max_nodes. PNG needs Pillow.
A .tareco file keeps everything, the rows behind the links included, to pick the investigation up later with tareco.load(path).
g.to_svg(**options)
A still picture of the graph as SVG text (see save).
g.report(path=None, title=None, lang=None, label=None, **view)
A single HTML file with the findings, group and node tables, and the graph.
Made to be sent to someone. Returns the path, or the HTML when path is None.
g.to_html(**options)
g.to_dict()
g.to_json(path=None, indent=2)
g.to_csv(edges_path, nodes_path=None)
g.to_pandas(metrics=None)
(nodes, edges) as two pandas DataFrames.
metrics adds node columns: any of "degree", "in_degree", "out_degree", "pagerank", "betweenness", "closeness", "clustering", "core", "community", "component".
g.to_spark(spark, metrics=None)
(nodes, edges) as Spark DataFrames (same metrics as to_pandas).
g.to_networkx()
What comes back
Answers print as plain language and turn into tables.
Explanation(profiles, lang, title=None)
What a network shows. Print it, iterate its findings, or render it in a notebook.
Explanation.to_dict()
Explanation.to_pandas()
Patterns()
Found patterns, strongest first within each kind.
Patterns.of(kind)
Patterns.nodes
Every node the patterns talk about, the most telling first, without repeats.
Patterns.rows()
The rows of your table behind all of them (when the graph keeps rows).
Patterns.to_pandas()
Pattern(nodes, score, details, text, rows=None)
A shape or behavior found: kind, nodes, score, details, text, and rows, the rows of your table behind it when the graph keeps them.
Pattern.to_dict()
Review(title='', lang='en', g=None, label=None, id_column=None)
Nodes worth a look, the strongest case first, each with its reasons and the rows behind them.
Review.nodes
Review.table()
One dict per node: node, score, signals, reasons, rows, ids and its attributes.
Review.to_pandas()
Review.to_spark(spark)
The list as a Spark DataFrame, to save next to the data (.write.saveAsTable(...)).
Review.compare(previous)
What changed since an earlier work list: who is new, whose score went up or down, and who left it.
previous is an earlier Review, or the table one was saved as: its to_pandas(), a CSV, a Spark table, a list of dicts. It needs the node and score columns; with signals too, a node that went up shows the reasons that are new.
Changes(up, down, gone, same, lang='en', g=None, label=None)
What changed between two work lists: new, up and down (with the score before), gone (nodes no longer in the list, with the score they had) and same.
Changes.nodes
What to look at now: the new ones, then the ones that went up.
Changes.table()
One dict per node that changed: node, change, score, before and reasons.
Changes.to_pandas()
table() as a pandas DataFrame.
Check(lang='en', rows=0)
What to fix in a table before trusting a graph made from it. Empty means nothing to fix.
Check.ok
Check.to_pandas()
Rows()
Rows of a table, as dicts. to_pandas() makes a DataFrame of them.
Rows.to_pandas()
Rows.column(name)
The values of one column, like the transaction ids.
Entities(g=None, lang='en', label=None)
Groups of nodes tied by shared identifiers, biggest first.
Entities.of(node)
The entity a node belongs to, or None.
Entities.to_pandas()
Entities.graph()
The graph with each entity as one node (E1, E2...), its links and rows added up.
Members keep their ids in the members attribute; links among members and to the identifiers that tie them disappear. Everything else (review, splits, similar_to) then works per entity instead of per node.
Flows(title='', lang='en', direction='to', label=None, g=None)
How the flow splits by an attribute, biggest first.
Flows.to_pandas()
Timeline(freq, directed, cumulative, nodes=None)
Snapshots of a network over time. Index it by period label or position.
Timeline.activity()
Per period: active nodes, connections and total weight.
Timeline.changes(lang=None, label=None, limit=12)
What changed from one period to the next, in plain language.
Timeline.explain(lang=None, label=None, limit=12)
The story of the network over time, then what holds for the whole period.
Timeline.compare(before, after, lang=None, label=None, top=3)
What changed from one period to another: timeline.compare("2026-01", "2026-06").
Timeline.trace(source, target=None, within='30 days', hops=4, lang=None, label=None, limit=10)
Paths from source that follow the events in time order (see Graph.trace).
Timeline.spread(start, since=None)
When each node could first have been reached from start, following events in order.
A path only counts if its events happen one after the other (A meets B, then B meets C). Returns {node: time}, earliest first.
Timeline.to_html(lang=None, label=None, **options)
Timeline.report(path=None, title=None, lang=None, label=None, **view)
Like Graph.report, plus activity per period and the time slider.
Timeline.save(path, **options)
Timeline.show(lang=None, label=None, **options)
The union of all periods, with a time slider to replay it.
Spark
tareco.big: the same questions on edge tables too big for one machine, run in the cluster.
tareco.big.statement_edges(statements, account, counterparty, amount)
Bank statements (one row per entry, money out negative) as edges source, target, amount.
Money out goes from the account to the counterparty; money in, from the counterparty to the account. A transfer between two accounts that both have statements in the table shows up twice and is kept once, from the side it left. Works on Spark (lazily, in the cluster) and pandas DataFrames.
tareco.big.degrees(edges, source=None, target=None, weight=None)
node, out_links, in_links, links (and out_weight, in_weight with weight) per node.
tareco.big.components(edges, source=None, target=None, max_iter=60)
node, component for every node: the separate parts of the network, direction ignored.
Components are numbered by size, 1 for the biggest. Each round every node takes the smallest label around it, until nothing changes.
tareco.big.pagerank(edges, source=None, target=None, weight=None, alpha=0.85, iterations=20)
node, pagerank for every node, following the links' direction (and weight).
tareco.big.communities(edges, source=None, target=None, weight=None, iterations=10)
node, community for every node, by label propagation: each node joins the label its neighbors weigh most. Fast and good on big graphs; on graphs that fit in memory, Graph.communities() (Louvain) is sharper. Communities are numbered by size.