Commit c48ec9a8 authored by Bruno López Trigo's avatar Bruno López Trigo

Modificado README

parent 527a4dd9
......@@ -14,59 +14,69 @@ made available under the Secondary License when the conditions
for such availability set forth in the Eclipse Public License, v. 2.0
are satisfied: GNU General Public License, version 2 with the GNU
Classpath Exception which is available at GNU General Public License, either version 2
of the License, or (at your option) any later version
of the License, or (at your option) any later version
available at https://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.
## WHAT IS THIS PROJECT?
In recent years, artificial intelligence is integrated into many systems whose needs go beyond the technical aspects. Within these needs, we find the ethical and legal aspects related to interaction of users with intelligent systems. Many intelligent systems, in particular almost all those that are learned automatically from data, use a black box model where users rely on the decisions taken by these systems, without worrying about how such decisions were made. Thus arises the paradigm of Explicable Artificial Intelligence (eXplainable Artificial Intelligence, JHA) that makes reference to the construction of intelligent systems able to provide information on how they make their decisions. Even for intelligent systems that use a white box model, it is necessary the intervention of an expert to interpret this model, so it is interesting to apply the XAI paradigm to obtain a self-explanatory system. According to the ACM Code of Ethics, the explanation is a basic principle to guarantee the transparency of the algorithms and the responsibility of the institutions of the decisions taken by the mentioned algorithms. In addition, the recent application of the new European General Data Protection Regulation emphasizes the "right to explanation" for European citizens, regardless of whether decisions are made by people or intelligent systems. In this context, ExpliClas aims to address the problem of generating explanations for a smart system. In particular, the intelligent systems of classification, using a white box model, and more specifically the decision-tree-based systems. ExpliClas studies the generation of explanations through Natural Language Generation trying to reach explanations capable of clarifying to the user how the classification systems make decisions. In addition, the purpose of these explanations is not only reduced to make the system more understandable, but also increase the user's confidence in the system itself and its reliability. Another relevant aspect of the explanation is the user interactivity with the system, which will be reflected in the variation of the explanations according to the actions executed by the user in the system. ExpliClas service is currently operative and deployed in the URL: https://demos.citius.usc.es/ExpliClas/. The corresponding ExpliClas API is available in: https://demos.citius.usc.es/ExpliClasAPI/.
## WHERE IS THE CODE LOCATED
ExpliClas code is available on the following repositories: https://gitlab.citius.usc.es/bruno.lopez.trigo/ExpliClas-TFG and https://forxa.mancomun.org/scm/browser.php?group_id=419.
ExpliClas code is available on: https://gitlab.citius.usc.es/bruno.lopez.trigo/ExpliClas-TFG
The demo web service code is available under /codigo/expliclas.
The API REST code is available under /codigo/expliclas-api.
## HOW TO BUILD
## HOW TO BUILD AND DEPLOY
### Prerequisites
- Install NetBeans IDE (version 8.2)
- Install Apache Tomcat (version 9.0.12)
- Install NodeJS (version 10.13)
- Install NPM (version 6.4.1)
### Building and deploying the API
1. Add Apache Tomcat server to NetBeans IDE http://wiki.netbeans.org/AddExternalTomcat
2. Open [ExpliClas API Maven Project](/codigo/expliclas-api) on NetBeans IDE.
3. Run the project with NetBeans. By default API will be deployed at http://localhost:8080/api.
In order to build API service be sure to follow the next steps:
If you wish to change the default API base URL:
1. In order to change the API base URL you should go [web.xml](/codigo/expliclas-api/src/main/java/webapp/WEB-INF/web.xml) file and modify the servlet mapping.
1. Download and install Netbeans IDE (version 8 or greater)
2. Download and install Apache Tomcat Server (version 8 or greater)
3. Open [ExpliClas API](/codigo/expliclas-api) project on Netbeans
4. Be sure [Swagger index.html](/codigo/expliclas-api/src/main/webapp/index.html) contains correct API URL in order to correctly deploy API documentation.
```xml
<servlet-mapping>
<servlet-name>ExpliClas</servlet-name>
<url-pattern>/api/*</url-pattern> <!-- CHANGE API BASE URL -->
</servlet-mapping>
```
2. Then change at [index.html](/codigo/expliclas-api/src/main/webapp/index.html) the URL pointing the API documentation.
```javascript
const ui = SwaggerUIBundle({
url: "http://localhost:8080/api/swagger.json", // CHANGE THIS LINE
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
})
url: "http://localhost:8080/api/openapi.json", // CHANGE API DOCUMENTATION FILE LOCATION
dom_id: "#swagger-ui",
deepLinking: true,
presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
plugins: [SwaggerUIBundle.plugins.DownloadUrl],
layout: "StandaloneLayout",
apisSorter: "method"
});
```
Run project with Netbeans, by default API will be deployed at http://localhost:8080/api/
In order to deploy demo web service:
1. Download and install NodeJS (version 8 or greater).
2. Download and install npm (version 3 or greater).
3. Go to [ExpliClas Web Demo](/codigo/expliclas) directory
4. Run ```npm install``` to correctly download and install dependencies.
5. Run ```npm start``` to directly run web service. Optionally, you can run ```npm run build``` if you want to create a web service ready to production. After create production application you will see a build folder that contains production files. If you want to put in production the service you will need to install a Node server so install 'serve' package via: ```npm install -g serve```. Finally, you can execute application with ```serve -s -l PORT build``` where PORT is your desired port to deploy the web.
### Building and deploying the demo web service
Be sure to establish correct URLs for web service under [config file](/codigo/expliclas/src/config.js)
If you have changed the API base URL, the go to the [demo config](/codigo/expliclas/src/config.js) to be sure API URL's match.
```javascript
export const API_ROOT = 'http://localhost:8080/api'; // API URL
export const API_DOC = 'http://localhost:8080/'; // API DOCUMENTATION URL
export const HOME = 'http://localhost:3000/'; // WEB SERVICE URL
```
\ No newline at end of file
export const API_ROOT = "http://localhost:8080/api";
export const API_DOC = "http://localhost:8080/";
```
1. Go to [ExpliClas Web Demo](/codigo/expliclas) and run `npm install` to get all dependencies.
2. Run `npm install -g serve` to install a NodeJS server for deployment.
3. Run `npm run build` to generate a web service ready to production.
4. Run `serve -s -l PORT build` to run the web service in the specified PORT.
# ExpliClas
Copyright (C) 2018 Bruno López Trigo <bruno.lopez.trigo@rai.usc.es>
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.
Portions of this software are made available under the
terms of the Eclipse Public License 2.0 which is available at
https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.txt. These portions may also be
made available under the Secondary License when the conditions
for such availability set forth in the Eclipse Public License, v. 2.0
are satisfied: GNU General Public License, version 2 with the GNU
Classpath Exception which is available at GNU General Public License, either version 2
of the License, or (at your option) any later version
available at https://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.
## WHAT IS THIS PROJECT?
In recent years, artificial intelligence is integrated into many systems whose needs go beyond the technical aspects. Within these needs, we find the ethical and legal aspects related to interaction of users with intelligent systems. Many intelligent systems, in particular almost all those that are learned automatically from data, use a black box model where users rely on the decisions taken by these systems, without worrying about how such decisions were made. Thus arises the paradigm of Explicable Artificial Intelligence (eXplainable Artificial Intelligence, JHA) that makes reference to the construction of intelligent systems able to provide information on how they make their decisions. Even for intelligent systems that use a white box model, it is necessary the intervention of an expert to interpret this model, so it is interesting to apply the XAI paradigm to obtain a self-explanatory system. According to the ACM Code of Ethics, the explanation is a basic principle to guarantee the transparency of the algorithms and the responsibility of the institutions of the decisions taken by the mentioned algorithms. In addition, the recent application of the new European General Data Protection Regulation emphasizes the "right to explanation" for European citizens, regardless of whether decisions are made by people or intelligent systems. In this context, ExpliClas aims to address the problem of generating explanations for a smart system. In particular, the intelligent systems of classification, using a white box model, and more specifically the decision-tree-based systems. ExpliClas studies the generation of explanations through Natural Language Generation trying to reach explanations capable of clarifying to the user how the classification systems make decisions. In addition, the purpose of these explanations is not only reduced to make the system more understandable, but also increase the user's confidence in the system itself and its reliability. Another relevant aspect of the explanation is the user interactivity with the system, which will be reflected in the variation of the explanations according to the actions executed by the user in the system. ExpliClas service is currently operative and deployed in the URL: https://demos.citius.usc.es/ExpliClas/. The corresponding ExpliClas API is available in: https://demos.citius.usc.es/ExpliClasAPI/.
## WHERE IS THE CODE LOCATED
ExpliClas code is available on: https://gitlab.citius.usc.es/bruno.lopez.trigo/ExpliClas-TFG
The demo web service code is available under /codigo/expliclas.
The API REST code is available under /codigo/expliclas-api.
## HOW TO BUILD AND DEPLOY
### Prerequisites
- Install NetBeans IDE (version 8.2)
- Install Apache Tomcat (version 9.0.12)
- Install NodeJS (version 10.13)
- Install NPM (version 6.4.1)
### Building and deploying the API
1. Add Apache Tomcat server to NetBeans IDE http://wiki.netbeans.org/AddExternalTomcat
2. Open [ExpliClas API Maven Project](/codigo/expliclas-api) on NetBeans IDE.
3. Run the project with NetBeans. By default API will be deployed at http://localhost:8080/api.
If you wish to change the default API base URL:
1. In order to change the API base URL you should go [web.xml](/codigo/expliclas-api/src/main/java/webapp/WEB-INF/web.xml) file and modify the servlet mapping.
```xml
<servlet-mapping>
<servlet-name>ExpliClas</servlet-name>
<url-pattern>/api/*</url-pattern> <!-- CHANGE API BASE URL -->
</servlet-mapping>
```
2. Then change at [index.html](/codigo/expliclas-api/src/main/webapp/index.html) the URL pointing the API documentation.
```javascript
const ui = SwaggerUIBundle({
url: "http://localhost:8080/api/openapi.json", // CHANGE API DOCUMENTATION FILE LOCATION
dom_id: "#swagger-ui",
deepLinking: true,
presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
plugins: [SwaggerUIBundle.plugins.DownloadUrl],
layout: "StandaloneLayout",
apisSorter: "method"
});
```
### Building and deploying the demo web service
If you have changed the API base URL, the go to the [demo config](/codigo/expliclas/src/config.js) to be sure API URL's match.
```javascript
export const API_ROOT = "http://localhost:8080/api";
export const API_DOC = "http://localhost:8080/";
```
1. Go to [ExpliClas Web Demo](/codigo/expliclas) and run `npm install` to get all dependencies.
2. Run `npm install -g serve` to install a NodeJS server for deployment.
3. Run `npm run build` to generate a web service ready to production.
4. Run `serve -s -l PORT build` to run the web service in the specified PORT.
......@@ -30,7 +30,7 @@
<servlet-mapping>
<servlet-name>ExpliClas</servlet-name>
<url-pattern>/api/*</url-pattern>
<url-pattern>/api/*</url-pattern> <!-- CHANGE API BASE URL -->
</servlet-mapping>
</web-app>
......@@ -40,7 +40,7 @@
// Build a system
const ui = SwaggerUIBundle({
url: "http://localhost:8080/api/openapi.json",
url: "http://localhost:8080/api/openapi.json", // CHANGE API DOCUMENTATION FILE LOCATION
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
......
......@@ -30,7 +30,7 @@
<servlet-mapping>
<servlet-name>ExpliClas</servlet-name>
<url-pattern>/api/*</url-pattern>
<url-pattern>/api/*</url-pattern> <!-- CHANGE API BASE URL -->
</servlet-mapping>
</web-app>
......@@ -40,7 +40,7 @@
// Build a system
const ui = SwaggerUIBundle({
url: "http://localhost:8080/api/openapi.json",
url: "http://localhost:8080/api/openapi.json", // CHANGE API DOCUMENTATION FILE LOCATION
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment