Metadata-Version: 2.4
Name: tgraph
Version: 1.0.0
Summary: Implementation of the t-graph package presented in the paper 'CallMine: Fraud Detection and Visualization of Million-Scale Call Graphs'.
Author-email: Mirela Cazzolato <mirelac@usp.br>
License-Expression: MIT
Project-URL: Homepage, https://github.com/mtcazzolato/callmine
Keywords: tgraph,tgraph-spot,callmine,callmine-focus
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: plotly
Requires-Dist: networkx
Dynamic: license-file

# Tgraph: A static and temporal graph analysis tool

This is an implementation/publishing of the tgraph module used in the paper 'CallMine: Fraud Detection and Visualization of Million-Scale Call Graphs'.

For more information see [Callmine: Fraud Detection and Visualizaion of Million-Scale Call Graphs](https://namyongpark.github.io/assets/pdf/CallMine-CIKM2023.pdf).

## Installation

You can install this package from [PyPI](https://pypi.org/):

```bash
pip install tgraph
```

## Usage

The package offers three main feature sets: Creating static/temporal graphs from edgelists (and outputting their features), generating useful plots from features,
and automatically joining CSV files resulting from graph features.

### Creating static/temporal graphs from edgelists

#### Creating a static graph

In order to create a static graph, the user must provide a CSV file containing the following expected headers:

- "source": The source node.
- "destination": The destination node.
- "measure": A value expressing the measure of connection from source to destination.

This can either be done through the terminal (in which case tgraph performs a simple print and outputs the features if the flag -v is set):

```bash
staticgraph path/to/my/file

# or

staticgraph -v path/to/my/file
```

Or inside a python script:

```python
from tgraph import static_graph

my_graph = static_graph.StaticGraph("path/to/my/file")

# Will perform a print of the adjacency dataframe
my_graph.my_print()

# Will print the graph features as csv
my_graph.print_to_csv("/path/to/output/file")
# ...
```

#### Creating a temporal graph

In order to create a static graph, the user must provide a CSV file containing the following expected headers:

- "source": The source node.
- "destination": The destination node.
- "measure": A value expressing the measure of connection from source to destination.
- "timestamp": A value expressing the timestamp associated with this connection.

This can either be done through the terminal (in which case tgraph performs a simple print and outputs the features if the flag `-v` is set):

```bash
temporalgraph path/to/my/file

# or

temporalgraph -v path/to/my/file
```

Or inside a python script:

```python
from tgraph import temporal_graph

my_graph = temporal_graph.TemporalGraph("path/to/my/file")

# Will perform a print of the adjacency dataframe
my_graph.my_print()

# Will print the graph features as csv
my_graph.print_to_csv("/path/to/output/file")
# ...
```

### Generating plots from graph features

The `nd_cloud` class provides a number of automatically generated visualizations and plots from graph feature datasets. The user is encouraged to check the source-code from the [github page](https://github.com/mtcazzolato/callmine/tree/main/tgraph) in order to find their desired functionality.

The module can be called from the terminal using:

```bash
ndcloud path/to/my/file
```

With the following optional flags:

- **-v | --verbose**: Enables output verbosity. Default = False
- **-m | --min_row_sum**: Drop rows with smaller sum. Default = 0
- **-p | --print**: Print to png. Default = False

It can also be used inside a Python script:

```python
from tgraph import nd_cloud

ndc = nd_cloud.nd_cloud("path/to/my/file")

# Will simply print the headers
ndc.print_headers()

# Will produce ALL the plots
# You can set verbose to 0, print_flag to False and min_row_sum to 0 to get default behavior
ndc.kitchen_sink(verbose, print_flag, min_row_sum)

# Check out the nd_cloud class in the github repository for additional methods
```

### Joining feature files

In order to join CSV feature files generated by the static and temporal graphs, the user can call the module from the terminal (with the optional `-v` flag):

```bash
joinfeaturefiles /path/to/static/file/ /path/to/temporal/file

# or

joinfeaturefiles -v /path/to/static/file/ /path/to/temporal/file
```

Alternatively, the module can also be used inside a Python script:

```python
from tgraph import join_feature_files

jf = join_feature_files.JoinFeatures("path/to/static/file", "path/to/temporal/file")

jf.print_to_csv("path/to/output/file")

```

