# py-graspi

Python-Igraph is a graph-based library contender for the library that works with the GraSPI package. 

This repository contains the implementation to test basic algorithm requirements that need to be met for this package to work similarly to GraSPI.
The basic algorithm requirements include:
  -  Construction of graphs
  -  Graph Filtering
  -  Determine the number of connected components
  -  Determine the shortest path from some meta-vertices to all specified vertices
  -  Provide a list of descriptors
  -  Graph visualization

## Installation
Download the packages found in requirements.txt after you have set up your virtual environment. 
Cone the repo by:
```
git clone https://github.com/owodolab/py-graspi.git
```
**Note: You'd need git installed on your system first**
<br />
<br />
  If you do not have git installed or run into issues with git, please visit: https://github.com/git-guides/install-git
<br />
<br />
Next, you'd need to navigate to the cloned repo using terminal. An example would be:
```
cd /path/py-graspi
```
Once navigated to the branch, access the following directory:
```
cd graspi_igraph
```
Next, the downloads needed can be found in requirements.txt and can be installed by:
```
pip install notebook
```
Install the graspi_igraph package by:
```
pip install graspi-igraph
```
Once installed, to utilize the package remember to import the package:
```
import graspi_igraph as ig
```

**Note: you must have Python and pip installed onto your system**
<br />
<br />
  If you do not have Python installed, please visit: https://www.python.org/downloads/
<br />
<br />
  If you do not have pip installed or are running into issues with pip, please visit: https://pip.pypa.io/en/stable/installation/
<br />
<br />
  If there are any other issues with installation, please visit: https://python.igraph.org/en/stable/ 

## Running All 33 Morphologies Tests (JZ)
To run the morphologies tests, return to the previous directory of "/py-graspi" by running:
```
cd ..
```
Next, make sure you're on bash first by running:
```
bash
```
Next, run the following:
```
chmod +x run.sh
```
Finally, run the following: 
```
./run.sh <file_type>
```
Substitute <file_type> with either txt or pdf for the desired output type.
## 33 Morphologies Output (JZ)
After running the command, the automatic report generation will begin. 
<br />
<br /> 
The following will print when the report generation begins:
```
Generating PDF (If on pdf mode)
Generating Text Files
```
As the script is running, the following will print for which microstructure it is on
```
Executing <test_file>
```
After a few minutes, the following will print once the report has been created
```
Text Files Generated
PDF Generated (If on pdf mode)
```
## Viewing 33 Morphologies Output (JZ)
For text files, navigate to the results directory by using the following command:
```
cd graspi_igraph/results
```
Use the following command to view the list of text files generated:
```
ls
```
To view the result in each file, run the following command:
```
cat <result_file_name>
```
Replace <result_file_name> with any of the files outputted by "ls"
<br />
<br />
If using pdf mode, the pdf should automattically open upon completion.
<br />
<br />
If the pdf does not automatically pop up, use the following commands:
### On Windows
```
start graspi_igraph/test_results.pdf
```
### On MacOS
```
open graspi_igraph/test_results.pdf
```
### On Linux
```
evince graspi_igraph/test_results.pdf
```
If evince is not installed, run this first:
```
sudo apt install evince
```
## To Test Algorithms

To **generate graphs**, call the generateGraph(_file_) function which takes in a input-file name
  -  returns a graph and a bool of whether it's a 2D graph
```
ig.generateGraph("2D-testFile/testFile-10-2D.txt")   # utilizing the test file found in 2D-testFiles folder as an example
```

To **filter graphs**, call filterGraph(_graph_) function which takes in a graph object 
  -  can pass a graph generated by generateGraph(_file_)
  -  returns a filtered graph
```
g, is_2D = ig.generateGraph("2D-testFile/testFile-10-2D.txt")     # utilizing the test file found in 2D-testFiles folder as an example
fg = ig.filterGraph(g)
```

To **determine the connected components** of the filtered graph, call connected_components() function
```
print(ig.connectedComponents(fg))
```
The number of connected components can be found by taking the length of the result produced by the connected_components function 
```
print(len(ig.connectedComponents(fg))) 
```

The **shortest path** between some meta-vertices to all specified vertices calling the function shortest_path(_fiteredGraph_, _specifiedVertices_, _metaVertex_, _fileName_)
  -  stores the distance of the paths to from the _metaVertex_ to every single _specified Vertices_ in a text file called _fileName_

Example:
  - the example below finds the shortest path between all black vertices to the blue meta-vertex and stores it in the text file, black_to_blue_paths.txt
```
ig.shortest_path(fg,'black','blue',"black_to_blue_paths.txt")    #fg is a filtered graph object
```

### To get list of descriptors (WZ)

A **descriptors stored in a dictionary** can be found by calling the function descriptors(_graph_)

```
ig.descriptors(g)      # g is a graph object
```
A **list of descriptors in a text file** can be found by calling the function descriptorsToTxt(_dictionary_,_filename_)
  -  _dict_ is a dictionary of descriptors that is returned by calling ig.descriptors(g)
```
ig.descriptorsToTxt(dict,"descriptors_list.txt") 
```

### To visualize graphs

To visualize graphs, call visualize(_graph_, _is_2D_)
  -  _graph_ is a graph object
  -  _is_2D_ is a bool of whether a graph is 2D, also a return value when _generateGraph()_ is called
```
g, is_2D = ig.generateGraph("2D-testFile/testFile-10-2D.txt")     # utilizing the test file found in 2D-testFiles folder as an example
ig.visual2D(g, is_2D)
```

## Testing from Command Line (Kevin)


Now that we have cloned the REPO lets talk about testing.

\*\*\*First and foremost make sure you are in te py-graspi directory. If not you may run into some errors\*\*\*

In this GitHub Repo, all the tests are in the test directory. Furthermore, within this directory are two more directories: 2D-testFile and 3D-testFile.
Inside these directories, some files hold information about either 2d or 3d graphs based on the directory name. 
When running from command lines you will need to know the complete pathname of the test file you are trying to run.

There are 2 type of input file formats: *.txt & *.graphe
### _*.txt input format:_


The command line input to run a graph creation for *.txt files will have the following format:
```
python graspi_igraph/igraph_testing.py {total pathname of test file}
```
If you have the same test directories as this GitHub Repo you should be able to run the following command line argument to output a 2D 10x10 graph.
```
python graspi_igraph/igraph_testing.py graspi_igraph/tests/2D-testFile/testFile-10-2D.txt 
```
### _*.graphe input format:_
*.graphe input format is not that different, only extra parameter you need to input is a 'g' before the total pathname of the test file.

The command line input to run a graph creation for *.graphe files will have the following format:
````
python graspi_igraph/igraph_testing.py -g {total pathname of test file} 
````
If you have the same test directories as this GitHub Repo you should be able to run the following command line argument to output a 2D 4x3 graph.
```
python graspi_igraph/igraph_testing.py g graspi_igraph/tests/2D-testFile/data_4_3.graphe
```
### _Running with Periodicity:_
We include the option of running any test case with periodicity turned on ONLY for *.txt input files. This 
is done with an added '-p' parameter. This parameter is added first before inputting the test case
format.

For example, for *.txt cases with periodicity turned on will look like the following:
```
python graspi_igraph/igraph_testing.py -p {total pathname of test file}
```

To test this out run the example test case above but with the added '-p' parameter
to turn periodicity on.

## Generate and Run Files for py-graspi API (ML)
In order to generate an API using sphinx, you need to follow the installation of py-graspi:

Cloning the repository:
```
git clone https://github.com/owodolab/py-graspi.git
```

**Make sure your current directory is py-graspi**

In order to create an API with sphinx, you need to download sphinx with this command in the command line interface:
```
pip install sphinx
```
Additional dependencies needed for installed Sphinx Extension:
```
pip install sphinxcontrib-details-directive
```
Provides additional details (dropdowns) for each submodle listed.
```
pip install sphinx_rtd_theme
```
Uses the rtf theme for the API
```
pip install --upgrade setuptools
```
Used by python to handle resources and files

In the command line interface, run this command:
```
sphinx-build -b html ./docs/source/ ./docs/ 
```
* **sphinx-build**: This is the main command for building Sphinx documentation. It generates documentation from reStructuredText (.rst) or Markdown (.md) source files.
* **-b html**: This specifies the output format. Here, -b html tells Sphinx to build the documentation in HTML format, which is typically used for web-based documentation.
* **./docs/source/**: This is the path to the source directory where Sphinx looks for the documentation source files. In this example, it’s in the source subdirectory inside docs.
* **./docs/**: This is the output directory where the built HTML files will be saved. In this example, it’s the main docs folder. After running this command, you’ll find the generated HTML files here.

In order to see the py-graspi API, run this command in the command line interface:

**FOR WINDOWS:**
```
start docs/index.html
```

**FOR MACOS:**
```
open docs/index.html
```
This would create a local view. You can see the official API on Github pages at: https://owodolab.github.io/py-graspi/

## 2D & 3D Morphologies Tests
To run the 2d and 3d morphologies you will need to setup notebook and pip install the graspi_igraph package.

First you will need to git clone the current repo, make sure that you are in the ""dev branch"":
```
git clone https://github.com/owodolab/py-graspi.git
```
Then, you will need to install the igraph package:
```
pip install graspi-igraph
```
Install jupyter notebook in order to view the test file:
```
pip install notebook
```

Finally, you will be able to use the command:
```
jupyter notebook
```
This will bring you into the testing filing on jupyter.
Navigate to the directory 3d_2d_tests.
Navigate to the file graspi_igraph_notebook.ipynb.

On this file you will be able to run and view the 2d and 3d morphologies for subtask 4, card 104.
