use std::io::Write;
use anyhow::Result;
use clap::ValueEnum;
use pixelfold_core::Network;
use pixelfold_core::rin::{Edge, Node, RinAnalysis};
use serde::Serialize;
use serde_json::{Value, json};
const TOP_HUBS: usize = 10;
const TOP_COMPONENTS: usize = 10;
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, ValueEnum)]
pub enum GraphFormat {
#[default]
Json,
Graphml,
Tsv,
}
pub fn write<W: Write + ?Sized>(out: &mut W, network: &Network, format: GraphFormat) -> Result<()> {
match format {
GraphFormat::Json => write_json(out, network),
GraphFormat::Graphml => write_graphml(out, network),
GraphFormat::Tsv => write_tsv(out, network),
}
}
pub fn write_analysis<W: Write + ?Sized>(
out: &mut W,
network: &Network,
analysis: &RinAnalysis,
) -> Result<()> {
let over = match network.models {
1 => String::new(),
models => format!(" over {models} models"),
};
writeln!(
out,
"Residue interaction network{over}: {} residues, {} edges, {} components",
network.nodes.len(),
network.edges.len(),
analysis.components.len()
)?;
writeln!(out, "\nConnected components (largest first):")?;
if analysis.components.is_empty() {
writeln!(out, " (none)")?;
} else {
for (rank, component) in analysis.components.iter().take(TOP_COMPONENTS).enumerate() {
writeln!(out, " {}. {} residues", rank + 1, component.len())?;
}
let extra = analysis.components.len().saturating_sub(TOP_COMPONENTS);
if extra > 0 {
writeln!(out, " ... and {extra} more")?;
}
}
writeln!(out, "\nTop hubs by betweenness centrality:")?;
let mut ranked: Vec<usize> = (0..network.nodes.len()).collect();
ranked.sort_by(|&a, &b| {
analysis.betweenness[b]
.total_cmp(&analysis.betweenness[a])
.then(network.nodes[b].degree.cmp(&network.nodes[a].degree))
});
writeln!(
out,
" {:<10} {:<5} {:<3} {:>6} {:>12}",
"residue", "resn", "ss", "degree", "between"
)?;
for &i in ranked.iter().take(TOP_HUBS) {
let node = &network.nodes[i];
writeln!(
out,
" {:<10} {:<5} {:<3} {:>6} {:>12.2}",
node.id, node.resn, node.ss, node.degree, analysis.betweenness[i]
)?;
}
writeln!(
out,
"\nArticulation points ({} cut residues):",
analysis.articulation_points.len()
)?;
if analysis.articulation_points.is_empty() {
writeln!(out, " (none)")?;
} else {
let residues: Vec<String> = analysis
.articulation_points
.iter()
.map(|&i| format!("{} {}", network.nodes[i].id, network.nodes[i].resn))
.collect();
writeln!(out, " {}", residues.join(", "))?;
}
Ok(())
}
pub fn write_path<W: Write + ?Sized>(
out: &mut W,
network: &Network,
from_id: &str,
to_id: &str,
route: Option<&[usize]>,
) -> Result<()> {
match route {
None => writeln!(
out,
"No path between {from_id} and {to_id}: they are in different components"
)?,
Some(path) => {
writeln!(
out,
"Shortest path {from_id} \u{2192} {to_id}: {} steps, {} residues",
path.len().saturating_sub(1),
path.len()
)?;
for &node in path {
let node = &network.nodes[node];
writeln!(out, " {} {} [{}]", node.id, node.resn, node.ss)?;
}
}
}
Ok(())
}
pub fn write_mvsj<W: Write + ?Sized>(
out: &mut W,
network: &Network,
url: &str,
format: &str,
models: &[usize],
title: &str,
) -> Result<()> {
let residues: Vec<Value> = network
.nodes
.iter()
.map(|node| {
let mut expr = serde_json::Map::new();
expr.insert("auth_asym_id".to_string(), json!(node.chain));
expr.insert("auth_seq_id".to_string(), json!(node.resi));
if let Some(icode) = node.icode {
expr.insert("pdbx_PDB_ins_code".to_string(), json!(icode.to_string()));
}
Value::Object(expr)
})
.collect();
let mut components = vec![component(json!("polymer"), "cartoon", "#8a8a99")];
if !residues.is_empty() {
components.push(component(json!(residues), "ball_and_stick", "#ffb454"));
}
let structures: Vec<Value> = models
.iter()
.map(|&index| {
json!({
"kind": "structure",
"params": { "type": "model", "model_index": index },
"children": components
})
})
.collect();
let scene = json!({
"metadata": { "version": "1", "title": title },
"root": { "kind": "root", "children": [
{ "kind": "download", "params": { "url": url }, "children": [
{ "kind": "parse", "params": { "format": format }, "children": structures }
]}
]}
});
serde_json::to_writer_pretty(&mut *out, &scene)?;
writeln!(out)?;
Ok(())
}
fn component(selector: Value, representation: &str, color: &str) -> Value {
json!({
"kind": "component",
"params": { "selector": selector },
"children": [{
"kind": "representation",
"params": { "type": representation },
"children": [{ "kind": "color", "params": { "color": color } }]
}]
})
}
fn round_2dp(value: f32) -> f32 {
((value as f64 * 100.0).round() / 100.0) as f32
}
fn round_3dp(value: f32) -> f32 {
((value as f64 * 1000.0).round() / 1000.0) as f32
}
#[derive(Serialize)]
struct JsonNetwork<'a> {
models: usize,
nodes: Vec<JsonNode<'a>>,
edges: Vec<JsonEdge<'a>>,
}
#[derive(Serialize)]
struct JsonNode<'a> {
id: &'a str,
chain: &'a str,
resi: i32,
icode: Option<char>,
resn: &'a str,
ss: char,
degree: usize,
}
#[derive(Serialize)]
struct JsonEdge<'a> {
source: &'a str,
target: &'a str,
kind: &'a str,
count: usize,
min_distance: f32,
interchain: bool,
energy: f32,
models: usize,
frequency: f32,
}
fn json_node(node: &Node) -> JsonNode<'_> {
JsonNode {
id: &node.id,
chain: &node.chain,
resi: node.resi,
icode: node.icode,
resn: &node.resn,
ss: node.ss,
degree: node.degree,
}
}
fn json_edge<'a>(network: &Network, edge: &'a Edge) -> JsonEdge<'a> {
JsonEdge {
source: &edge.source,
target: &edge.target,
kind: edge.kind.label(),
count: edge.count,
min_distance: round_2dp(edge.min_distance),
interchain: edge.interchain,
energy: round_2dp(edge.energy),
models: edge.models,
frequency: round_3dp(network.frequency(edge)),
}
}
fn write_json<W: Write + ?Sized>(out: &mut W, network: &Network) -> Result<()> {
let json = JsonNetwork {
models: network.models,
nodes: network.nodes.iter().map(json_node).collect(),
edges: network
.edges
.iter()
.map(|edge| json_edge(network, edge))
.collect(),
};
serde_json::to_writer_pretty(&mut *out, &json)?;
writeln!(out)?;
Ok(())
}
fn write_tsv<W: Write + ?Sized>(out: &mut W, network: &Network) -> Result<()> {
writeln!(out, "{}", EDGE_COLUMNS.join("\t"))?;
for edge in &network.edges {
writeln!(out, "{}", edge_cells(network, edge).join("\t"))?;
}
Ok(())
}
const EDGE_COLUMNS: [&str; 9] = [
"source",
"target",
"kind",
"count",
"min_distance",
"interchain",
"energy",
"models",
"frequency",
];
fn edge_cells(network: &Network, edge: &Edge) -> [String; 9] {
[
edge.source.clone(),
edge.target.clone(),
edge.kind.label().to_string(),
edge.count.to_string(),
format!("{:.2}", round_2dp(edge.min_distance)),
edge.interchain.to_string(),
format!("{:.2}", round_2dp(edge.energy)),
edge.models.to_string(),
format!("{:.3}", round_3dp(network.frequency(edge))),
]
}
pub fn write_tsv_aligned<W: Write + ?Sized>(out: &mut W, network: &Network) -> Result<()> {
let rows: Vec<[String; 9]> = network
.edges
.iter()
.map(|edge| edge_cells(network, edge))
.collect();
let mut widths = EDGE_COLUMNS.map(str::len);
for row in &rows {
for (w, cell) in widths.iter_mut().zip(row) {
*w = (*w).max(cell.len());
}
}
write_padded_row(out, &EDGE_COLUMNS.map(String::from), &widths)?;
for row in &rows {
write_padded_row(out, row, &widths)?;
}
Ok(())
}
fn write_padded_row<W: Write + ?Sized>(
out: &mut W,
cells: &[String; 9],
widths: &[usize; 9],
) -> Result<()> {
const GUTTER: usize = 2;
let last = cells.len() - 1;
for (i, (cell, &width)) in cells.iter().zip(widths).enumerate() {
if i == last {
write!(out, "{cell}")?;
} else {
let pad = width + GUTTER;
write!(out, "{cell:<pad$}")?;
}
}
writeln!(out)?;
Ok(())
}
const KEYS: &str = concat!(
r#" <key id="g_models" for="graph" attr.name="models" attr.type="int"/>"#,
"\n",
r#" <key id="v_chain" for="node" attr.name="chain" attr.type="string"/>"#,
"\n",
r#" <key id="v_resi" for="node" attr.name="resi" attr.type="int"/>"#,
"\n",
r#" <key id="v_icode" for="node" attr.name="icode" attr.type="string"/>"#,
"\n",
r#" <key id="v_resn" for="node" attr.name="resn" attr.type="string"/>"#,
"\n",
r#" <key id="v_ss" for="node" attr.name="ss" attr.type="string"/>"#,
"\n",
r#" <key id="v_degree" for="node" attr.name="degree" attr.type="int"/>"#,
"\n",
r#" <key id="e_kind" for="edge" attr.name="kind" attr.type="string"/>"#,
"\n",
r#" <key id="e_count" for="edge" attr.name="count" attr.type="int"/>"#,
"\n",
r#" <key id="e_distance" for="edge" attr.name="min_distance" attr.type="double"/>"#,
"\n",
r#" <key id="e_interchain" for="edge" attr.name="interchain" attr.type="boolean"/>"#,
"\n",
r#" <key id="e_energy" for="edge" attr.name="energy" attr.type="double"/>"#,
"\n",
r#" <key id="e_models" for="edge" attr.name="models" attr.type="int"/>"#,
"\n",
r#" <key id="e_frequency" for="edge" attr.name="frequency" attr.type="double"/>"#,
);
fn write_graphml<W: Write + ?Sized>(out: &mut W, network: &Network) -> Result<()> {
writeln!(out, r#"<?xml version="1.0" encoding="UTF-8"?>"#)?;
writeln!(
out,
r#"<graphml xmlns="http://graphml.graphdrawing.org/xmlns">"#
)?;
writeln!(out, "{KEYS}")?;
writeln!(out, r#" <graph edgedefault="undirected">"#)?;
writeln!(out, r#" <data key="g_models">{}</data>"#, network.models)?;
for node in &network.nodes {
writeln!(out, r#" <node id="{}">"#, escape(&node.id))?;
data(out, "v_chain", &escape(&node.chain))?;
data(out, "v_resi", &node.resi.to_string())?;
if let Some(icode) = node.icode {
data(out, "v_icode", &escape(&icode.to_string()))?;
}
data(out, "v_resn", &escape(&node.resn))?;
data(out, "v_ss", &node.ss.to_string())?;
data(out, "v_degree", &node.degree.to_string())?;
writeln!(out, " </node>")?;
}
for edge in &network.edges {
writeln!(
out,
r#" <edge source="{}" target="{}">"#,
escape(&edge.source),
escape(&edge.target),
)?;
data(out, "e_kind", edge.kind.label())?;
data(out, "e_count", &edge.count.to_string())?;
data(
out,
"e_distance",
&format!("{:.2}", round_2dp(edge.min_distance)),
)?;
data(out, "e_interchain", &edge.interchain.to_string())?;
data(out, "e_energy", &format!("{:.2}", round_2dp(edge.energy)))?;
data(out, "e_models", &edge.models.to_string())?;
data(
out,
"e_frequency",
&format!("{:.3}", round_3dp(network.frequency(edge))),
)?;
writeln!(out, " </edge>")?;
}
writeln!(out, " </graph>")?;
writeln!(out, "</graphml>")?;
Ok(())
}
fn data<W: Write + ?Sized>(out: &mut W, key: &str, value: &str) -> Result<()> {
writeln!(out, r#" <data key="{key}">{value}</data>"#)?;
Ok(())
}
fn escape(text: &str) -> String {
let mut out = String::with_capacity(text.len());
for ch in text.chars() {
match ch {
'&' => out.push_str("&"),
'<' => out.push_str("<"),
'>' => out.push_str(">"),
'"' => out.push_str("""),
'\'' => out.push_str("'"),
_ => out.push(ch),
}
}
out
}
#[cfg(test)]
mod tests {
use super::*;
use pixelfold_core::InteractionKind;
use pixelfold_core::rin::{Edge, Network, Node};
fn network() -> Network {
Network {
nodes: vec![
Node {
id: "A/1".into(),
chain: "A".into(),
resi: 1,
icode: None,
resn: "LYS".into(),
ss: 'H',
degree: 1,
},
Node {
id: "A/2".into(),
chain: "A".into(),
resi: 2,
icode: Some('B'),
resn: "GLU".into(),
ss: 'E',
degree: 1,
},
],
edges: vec![Edge {
source: "A/1".into(),
target: "A/2".into(),
kind: InteractionKind::SaltBridge,
count: 1,
min_distance: 3.456,
interchain: false,
energy: InteractionKind::SaltBridge.contact_energy_kj(),
models: 1,
}],
models: 3,
}
}
fn rendered(format: GraphFormat) -> String {
let mut out = Vec::new();
write(&mut out, &network(), format).expect("writing to a vec cannot fail");
String::from_utf8(out).expect("utf8")
}
#[test]
fn json_is_node_link_and_rounds_the_distance() {
let parsed: serde_json::Value =
serde_json::from_str(&rendered(GraphFormat::Json)).expect("valid json");
assert_eq!(parsed["models"], 3);
assert_eq!(parsed["edges"][0]["models"], 1);
assert_eq!(parsed["edges"][0]["frequency"], 0.333);
assert_eq!(parsed["nodes"][1]["icode"], "B");
assert_eq!(parsed["edges"][0]["kind"], "salt-bridge");
assert_eq!(parsed["edges"][0]["min_distance"], 3.46);
assert_eq!(parsed["edges"][0]["interchain"], false);
assert_eq!(
parsed["edges"][0]["energy"],
InteractionKind::SaltBridge.contact_energy_kj()
);
}
#[test]
fn the_aligned_edge_list_lines_up_columns_under_the_header() {
let mut net = network();
net.edges.push(Edge {
source: "A/100".into(),
target: "A/2".into(),
kind: InteractionKind::HydrogenBond,
count: 1,
min_distance: 3.0,
interchain: false,
energy: 20.0,
models: 3,
});
let mut out = Vec::new();
write_tsv_aligned(&mut out, &net).expect("write");
let text = String::from_utf8(out).expect("utf8");
let lines: Vec<&str> = text.lines().collect();
assert_eq!(lines[0].find("target"), Some(8));
assert!(lines[1][8..].starts_with("A/2"), "row 1 target aligns");
assert!(lines[2][8..].starts_with("A/2"), "row 2 target aligns");
assert!(!text.contains('\t'));
}
#[test]
fn the_tsv_edge_list_has_a_header_and_a_row_per_edge() {
let text = rendered(GraphFormat::Tsv);
let lines: Vec<&str> = text.lines().collect();
assert_eq!(
lines[0],
"source\ttarget\tkind\tcount\tmin_distance\tinterchain\tenergy\tmodels\tfrequency"
);
assert_eq!(
lines[1],
"A/1\tA/2\tsalt-bridge\t1\t3.46\tfalse\t17.00\t1\t0.333"
);
}
#[test]
fn graphml_is_well_formed_and_declares_its_keys() {
let text = rendered(GraphFormat::Graphml);
assert!(text.starts_with(r#"<?xml version="1.0" encoding="UTF-8"?>"#));
assert!(
text.contains(r#"<key id="e_kind" for="edge" attr.name="kind" attr.type="string"/>"#)
);
assert!(text.contains(r#"<node id="A/1">"#));
assert!(text.contains(r#"<edge source="A/1" target="A/2">"#));
assert!(text.contains("<data key=\"e_kind\">salt-bridge</data>"));
assert!(
text.contains(
r#"<key id="e_energy" for="edge" attr.name="energy" attr.type="double"/>"#
)
);
assert!(text.contains("<data key=\"e_energy\">17.00</data>"));
assert!(text.contains(
r#"<graph edgedefault="undirected">
<data key="g_models">3</data>"#
));
assert!(text.contains("<data key=\"e_models\">1</data>"));
assert!(text.contains("<data key=\"e_frequency\">0.333</data>"));
assert!(text.contains("<data key=\"v_icode\">B</data>"));
assert_eq!(
text.matches("<node ").count(),
text.matches("</node>").count()
);
assert_eq!(
text.matches("<edge ").count(),
text.matches("</edge>").count()
);
}
#[test]
fn xml_metacharacters_in_a_value_are_escaped() {
let mut net = network();
net.nodes[0].resn = "A<&B".into();
let mut out = Vec::new();
write(&mut out, &net, GraphFormat::Graphml).expect("write");
let text = String::from_utf8(out).expect("utf8");
assert!(text.contains("A<&B"));
assert!(!text.contains("A<&B"));
}
}