README.md

This project has been migrated to Raphtory/Raphtory. Please go there for future developments

🌍 Website   📖 Docs   Pometry   🐛 Report a Bug   Join Slack

What is Doc Brown? 🥼

Doc Brown is the Rust prototype for the next version of Raphtory, rethinking several aspects of the underlying graph model and algorithm API.

Please checkout the issues for the core features to be included in this version, along with their proposed semantics.

Below is a diagram of how Doc Brown works:

GraphDB is the overarching manager for the graph. A GraphDB instance can have N number of shards. These shards (also called TemporalGraphParts) store fragments of a graph. If you have used the Scala/Python version of Raphtory before, the notion of shards is similar to partitions in Raphtory, where parts of a graph are stored into partitions. When an edge or node is added to the graph in Doc Brown, GraphDB will search for an appropriate place inside a shard to place these. In this diagram, there are 4 shards (or partitions) labelled as S1, S2, S3, S4. Altogether they make up the entire temporal graph, hence the name "TemporalGraphPart" for each shard.

Shards are used for performance and distribution reasons. Having multiple shards running in parallel speeds up things a lot in Raphtory. In a matter of seconds, you are able to see your results from your temporal graph analysis. Furthermore, you can run your analysis across multiple machines (e.g. one shard per machine).

Running Doc Brown 👨🏼‍🔬

The API's are currently in...Flux

However, here is a quick start guide if you would like to test out the Raphtory Rust prototype.

Running the LOTR example 🧙🏻‍♂️

Prerequisites

Make sure you have Rust installed on your OS. Here is a guide to install Rust.

1. Set up Doc Brown

Clone the Doc Brown Repository and find the examples directory where you can find the Lord of the Rings Example. Create a folder named "Data" under examples/lotr and download the LOTR CSV data into this folder. You can download the raw csv here.

2. Run Doc Brown

Build Doc Brown by running this command to make sure it compiles and builds:

cargo build

If you have any linker errors please build with the following command:

cargo build --no-default-features

Next run the main function in main.rs which creates a graph from the LOTR csv file, showing the different character interactions throughout the book. To do this, you will need to be in the lotr folder, the file path to this from root is ./examples/src/bin/lotr. Once you are here run this command to run the LOTR example:

cargo run --bin lotr

You should see output that looks something like this with information about the edges and vertices below:

Loaded graph from encoded data files ./examples/src/bin/lotr/data/graphdb.bincode with 139 vertices, 701 edges which took 0 seconds

Gandalf exists = true

Congratulations, you have run your first Raphtory graph in Rust!

3. Running Tests

To run tests in Doc Brown, go back into your root folder and run this command:

cargo test

Code Example

// Create your GraphDB object and state the number of shards you would like, here we have 2
let graph = GraphDB::new(2);

// Add vertex and edges to your graph with the respective properties
graph.add_vertex(
  src_id,
  time,
  &vec![("name".to_string(), Prop::Str("Character".to_string()))],
);

graph.add_vertex(
  dst_id,
  time,
  &vec![("name".to_string(), Prop::Str("Character".to_string()))],
);

graph.add_edge(
  src_id,
  dst_id,
  time,
  &vec![(
      "name".to_string(),
      Prop::Str("Character Co-occurrence".to_string()),
  )],
);

// We calculate a hash for the string "Gandalf" to be used as a unique identifier for Gandalf
let gandalf = utils::calculate_hash(&"Gandalf");

// Get the in-degree, out-degree and degree of Gandalf
let in_degree = graph.degree_window(gandalf, 0, i64::MAX, Direction::IN);
let out_degree = graph.degree_window(gandalf, 0, i64::MAX, Direction::OUT);
let degree = graph.degree_window(gandalf, 0, i64::MAX, Direction::BOTH);

Documentation

DocBrown has Documentation with tutorials, explanations and rust docs. It can be found here on ReadTheDocs

Contributing

• Install Rust from install guide
• Install Python 3.10 (virtual/conda environment is recommended).
• Install pip packages needed to build/test

pip install maturin pytest

Community

Join the growing community of open-source enthusiasts using Raphtory to power their graph analysis projects!

• Follow for the latest Raphtory news and development

• Join our to chat with us and get answers to your questions!

Articles and Talks about Raphtory

• Raphtory on the Alan Turing Institute Blog
• Talk on Raphtory at AI UK 2022
• Talk on Raphtory at KGC 2022
• Talk on Raphtory at NetSciX 2022

Contributors

Since Doc Brown is still a prototype, we are open to any contributions. If you find any issues or would like to work on some issues yourself, visit the issues page. Join our Slack if you're having any issues or would like to find out more about how you can get stuck in with Raphtory.

License

Raphtory is licensed, check out our LICENSE file.