README.md 4.05 KB
Newer Older
MANOLESCU Ioana's avatar
MANOLESCU Ioana committed
1
# Download
MERABTI Tayeb's avatar
MERABTI Tayeb committed
2

MANOLESCU Ioana's avatar
MANOLESCU Ioana committed
3
A clone of this repository includes: 
MERABTI Tayeb's avatar
MERABTI Tayeb committed
4

MANOLESCU Ioana's avatar
MANOLESCU Ioana committed
5
6
7
8
9
  1. The `core` folder which provides:
     
   - the jar file `connection-lens-core-full-1.1-SNAPSHOT.jar`, 
   - the python `scripts` folder (these implement an entity extraction based on Flair),
   - a `properties` file which allow controlling multiple parameters related to the execution. 
MERABTI Tayeb's avatar
MERABTI Tayeb committed
10

MANOLESCU Ioana's avatar
MANOLESCU Ioana committed
11
12
13
14
15
  2. The `gui` folder with the file `gui.war` that allows to run the web app. 
   
  3. The `data` folder with a few sample datasets  (RDF, JSON, XML etc.)
   
  4. The `models` folder which provides linguistic models used by the TreeTagger and StanfordNLP tools we build upon.
MERABTI Tayeb's avatar
MERABTI Tayeb committed
16

MANOLESCU Ioana's avatar
MANOLESCU Ioana committed
17
#  Install
MERABTI Tayeb's avatar
MERABTI Tayeb committed
18

MANOLESCU Ioana's avatar
MANOLESCU Ioana committed
19
## Software prerequisites
MERABTI Tayeb's avatar
MERABTI Tayeb committed
20
21
22
23
24
25
Required: 
- Java >= 1.8
- PostgreSQL (tested with v.9.6)
- Python 3
- Tomcat >=8.*

MANOLESCU Ioana's avatar
MANOLESCU Ioana committed
26
Optional: 
MERABTI Tayeb's avatar
MERABTI Tayeb committed
27
28
29
30

- [Graphviz (DOT)](https://www.graphviz.org/) 


MANOLESCU Ioana's avatar
MANOLESCU Ioana committed
31
##  Installation instructions
MERABTI Tayeb's avatar
MERABTI Tayeb committed
32

MANOLESCU Ioana's avatar
MANOLESCU Ioana committed
33
34
ConnectionLens can be run in two modes: *text* (command-line like), using the **jar**;  and *graphical* (with the help of a GUI), by deploying the **war** in a Web server (we tested with Tomcat).
The respective installation instructions are: 
MERABTI Tayeb's avatar
MERABTI Tayeb committed
35

MERABTI Tayeb's avatar
save    
MERABTI Tayeb committed
36
- [ConnectionLens-Core installation instructions](core_install.md)
MERABTI Tayeb's avatar
MERABTI Tayeb committed
37

MERABTI Tayeb's avatar
save    
MERABTI Tayeb committed
38
- [ConnectionLens-Gui installation instructions](gui_install.md)
MERABTI Tayeb's avatar
MERABTI Tayeb committed
39
40


MANOLESCU Ioana's avatar
MANOLESCU Ioana committed
41
42
## Example
The example below ingests 5 small data sources of different formats into a graph. It also shows how to query the graph and visualize the results. 
MERABTI Tayeb's avatar
save    
MERABTI Tayeb committed
43

MANOLESCU Ioana's avatar
MANOLESCU Ioana committed
44
#### Creeating a small graph
MANOLESCU Ioana's avatar
MANOLESCU Ioana committed
45
From the main folder, call the jar in the `core` folder with the following options:
MERABTI Tayeb's avatar
MERABTI Tayeb committed
46

MERABTI Tayeb's avatar
MERABTI Tayeb committed
47
```
48
java -jar core/connection-lens-core-full-1.1-SNAPSHOT.jar -DRDBMSDBName=cl_myinstance -i data/poc/2/deputes.json,data/poc/2/fb-etienne-chouard.txt,data/poc/2/medias.txt,data/poc/2/tweet-Ruffin.json,data/poc/2/rt-wikipedia.txt
MERABTI Tayeb's avatar
MERABTI Tayeb committed
49
```
MERABTI Tayeb's avatar
MERABTI Tayeb committed
50

51
52
![image_3.png](./image_3.png)

53

MANOLESCU Ioana's avatar
MANOLESCU Ioana committed
54
55
56
57
58
59
60
61
62
63
### Querying

A ConnectionLens query is a set of keywords; an answer is a subtree of the graph, that connects one node matching each keyword.
To ask that a node matches more than one keyword, include those keywords within quotes. 

#### Command-line queries

First, we can query the graph using an interactive, command-line interface.
After having loaded the graph as explained above, call the code with the following options:

MERABTI Tayeb's avatar
MERABTI Tayeb committed
64
```
MERABTI Tayeb's avatar
MERABTI Tayeb committed
65
java -jar core/connection-lens-core-full-1.1-SNAPSHOT.jar -DRDBMSDBName=cl_myinstance -n -v -a
MERABTI Tayeb's avatar
MERABTI Tayeb committed
66
```
MERABTI Tayeb's avatar
MERABTI Tayeb committed
67

MERABTI Tayeb's avatar
MERABTI Tayeb committed
68
The `query>` indicates that the shell is ready to accept queries.
MERABTI Tayeb's avatar
MERABTI Tayeb committed
69

70
![image_2.png](./image_2.png)
MERABTI Tayeb's avatar
MERABTI Tayeb committed
71
72


MANOLESCU Ioana's avatar
MANOLESCU Ioana committed
73
#### Gathering statistics about queries
MERABTI Tayeb's avatar
MERABTI Tayeb committed
74

MANOLESCU Ioana's avatar
MANOLESCU Ioana committed
75
Assuming a set of queries are written in a query file (one query per line), the following call:
MERABTI Tayeb's avatar
MERABTI Tayeb committed
76

MERABTI Tayeb's avatar
MERABTI Tayeb committed
77
78
79
80
```
java -jar core/connection-lens-core-full-1.1-SNAPSHOT.jar -DRDBMSDBName=cl_myinstance -n -qs -Q core/data/poc/2/demo.queries

```
MANOLESCU Ioana's avatar
MANOLESCU Ioana committed
81
82
83

will yield a set of statistics on each query: how long it took, how many answers were found, how long before the first answer was found etc.

MERABTI Tayeb's avatar
MERABTI Tayeb committed
84
 
MANOLESCU Ioana's avatar
MANOLESCU Ioana committed
85
#### Sample queries on the small example   
MERABTI Tayeb's avatar
MERABTI Tayeb committed
86

MANOLESCU Ioana's avatar
MANOLESCU Ioana committed
87
88
89
90
91
92
93

- Russie - 1 answer
- Ruffin - 13 answers
- Poutine - 1 answer
- Assemblée - 3 answers
- Soral Toulon - 2 answers
- Briand Halluin Tonolli - 1 answer
MERABTI Tayeb's avatar
MERABTI Tayeb committed
94
95


MERABTI Tayeb's avatar
MERABTI Tayeb committed
96
#### Visualization
MERABTI Tayeb's avatar
MERABTI Tayeb committed
97

MANOLESCU Ioana's avatar
MANOLESCU Ioana committed
98
- Drop the `gui.war` into the `webapps` directory under the Tomcat installation.
MERABTI Tayeb's avatar
MERABTI Tayeb committed
99

MANOLESCU Ioana's avatar
MANOLESCU Ioana committed
100
- Point a browser at the address `http://localhost:8080/gui/`.
MERABTI Tayeb's avatar
MERABTI Tayeb committed
101

MANOLESCU Ioana's avatar
MANOLESCU Ioana committed
102
- Select the `myinstance` database in the header drop-down menu. 
MERABTI Tayeb's avatar
MERABTI Tayeb committed
103

MANOLESCU Ioana's avatar
MANOLESCU Ioana committed
104
- Ask a query, e.g., one of the above, directly on the keyword search bar.  For example, the following figure shows the result of the query: `Briand Halluin Tonolli`.
MERABTI Tayeb's avatar
MERABTI Tayeb committed
105

106
![image_4.png](./image_4.png)
MERABTI Tayeb's avatar
MERABTI Tayeb committed
107
108


MERABTI Tayeb's avatar
MERABTI Tayeb committed
109
110
111
112
# Contributing to ConnectionLens

If you found a bug or issue with ConnectionLens please let us know. You can report bugs on the [issue](https://gitlab.inria.fr/cedar/connectionlens/-/issues) tracker.

MERABTI Tayeb's avatar
MERABTI Tayeb committed
113
114
## How to report an issue

MANOLESCU Ioana's avatar
MANOLESCU Ioana committed
115
- Log in https://gitlab.inria.fr. If you need to create an account and do not work at Inria,  please send an email to `connection-lens-admin@inria.fr` to help you establish an account.
MERABTI Tayeb's avatar
MERABTI Tayeb committed
116

MANOLESCU Ioana's avatar
MANOLESCU Ioana committed
117
- Create a new issue on https://gitlab.inria.fr/cedar/connectionlens/-/issues, giving as much information as possible (what did you succeed in doing, what is not working etc.)
MERABTI Tayeb's avatar
MERABTI Tayeb committed
118

MANOLESCU Ioana's avatar
MANOLESCU Ioana committed
119
## About
MERABTI Tayeb's avatar
MERABTI Tayeb committed
120

MANOLESCU Ioana's avatar
MANOLESCU Ioana committed
121
ConnectionLens development starteed in 2018. See the [about us](about_us.md) page for a list of all authors.