Copyright (c) 2018 Laboratory for Advanced Biomedical Informatics at Louisiana State University in Shreveport. All Rights Reserved. Permission to use, copy, modify, and distribute this software and its documentation for educational, research and non-profit purposes, without fee, and without a written agreement is hereby granted, provided that the above copyright notice, this paragraph and the following three paragraphs appear in all copies. This software program and documentation are copyrighted by the Laboratory for Advanced Biomedical Informatics at Louisiana State University in Shreveport.
THE SOFTWARE PROGRAM AND DOCUMENTATION ARE SUPPLIED "AS IS," WITHOUT ANY ACCOMPANYING SERVICES FROM THE LOUISIANA STATE UNIVERSITY IN SHREVEPORT. FURTHERMORE, LOUISIANA STATE UNIVERSITY IN SHREVEPORT DOES NOT WARRANT THAT THE OPERATION OF THE PROGRAM WILL BE UNINTERRUPTED OR ERROR-FREE. THE END-USER UNDERSTANDS THAT THE PROGRAM WAS DEVELOPED FOR EDUCATIONAL/ RESEARCH PURPOSES AND IS ADVISED NOT TO RELY EXCLUSIVELY ON THE PROGRAM FOR ANY REASON.
IN NO EVENT SHALL LOUISIANA STATE UNIVERSITY IN SHREVEPORT BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF LOUISIANA STATE UNIVERSITY IN SHREVEPORT HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
LOUISIANA STATE UNIVERSITY IN SHREVEPORT SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND LOUISIANA STATE UNIVERS- ITY IN SHREVEPORT HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
This section of the manual describes how to obtain and set up GatewayNet.
GatewayNet and its associated files may be downloaded directly from here:
The programs in this distribution are statically linked to reduce the number of dependencies required. GatewayNet requires the following:
Memory usage is proportional to the number and size of histories in question and can be difficult to estimate, as its memory usage can scale combinatorically with the number of items provided in the item set. With a transaction database consisting of 909,963 transactions and 12 possible items, memory usage was measured to be around 229MiB or 2KiB per history on average. This suggests that a large linear component may be attributed to the transaction database itself. 4GiB is thought to be sufficient for transaction databases containing millions of transactions.
Installation is achieved using GNU make:
$ sudo make install
This command places the software in /usr/local/bin. If a different installation location is desired, set and export the PREFIX environment variable prior to executing the above command.
This section of the manual describes how to use GatewayNet.
The gatewaynet-rules program is responsible for inferring initiation rules from a transaction database. A transaction database is a tab-delimited file that uses a grammar similar to RFC 4180 (i.e., CSV with tab stops instead of commas as field separator) which consists of two integer fields consisting specifying the history ID and a timestamp and with items. To mine the a transaction database named transactions.txns, use the following command:
$ gatewaynet-rules transactions.txns output.rules [output-item-sets]
If the first two arguments are omitted, they are read from standard input and written to standard output respectively; single dashes (-) may also be used to denote that standard input or standard output should be used. Additional options can be supplied to gatewaynet-rules to affect its behavior and may be specified anywhere in the command:
| Short | Long | Description |
|---|---|---|
| -? | --help | Display the built-in help message. |
| -c | --count=i | Set the minimum count necessary for inclusion. |
| -C | --confidence=f | Set the minimum confidence necessary for inclusion. |
| -l | --lift=f | Set the minimum lift necessary for inclusion. |
| -o | --order=i | Set the maximum rule degree to mine. |
| -s | --support=f | Set the minimum support necessary for inclusion. |
| -V | --conviction=f | Set the maximum conviction necessary for inclusion. |
| -v | --verbose | Print additional information while running. |
| -w | --window=i | Set the size of the window for windowed rules. |
The gatewaynet-links program is responsible for producing a gateway network from a ruleset created by gatewaynet-rules. The resulting file is a directed graph in Graphviz's DOT language. To create the gateway network from a ruleset named input.rules, use the following command:
$ gatewaynet-links input.rules output.dot
If the first two arguments are omitted, they are read from standard input and written to standard output respectively; single dashes (-) may also be used to denote that standard input or standard output should be used. Additional options can be supplied to gatewaynet-links to affect its behavior and may be specified anywhere in the command:
| Short | Long | Description |
|---|---|---|
| -? | --help | Display the built-in help message. |
| -c | --count=i | Set the minimum count necessary for inclusion. |
| -C | --confidence=f | Set the minimum confidence necessary for inclusion. |
| -l | --lift=f | Set the minimum lift necessary for inclusion. |
| -s | --support=f | Set the minimum support necessary for inclusion. |
| -t | --certainty=f | Set the minimum certainty necessary for inclusion. |
| -T | --gateway=f | Set the minimum certainty necessary to classify a rule as a gateway rule. |
| -V | --conviction=f | Set the maximum conviction necessary for inclusion. |
| -v | --verbose | Print additional information while running. |
The graph may be rendered with any program that understands Graphviz's DOT language. The fdp program included with Graphviz is recommended. To produce an image of a gateway network contained in input.dot as a scalable vector graphics image, the following command may be used:
$ fdp -Tsvg input.dot > ${SVG}
The gateway-pipeline program is provided to simplify the process of running GatewayNet. For behavior respecting specific programs used by the pipeline, see above. To produce a pipeline for the transaction database transactions.txns and in the directory instance, use the following command:
$ gatewaynet-pipeline transactions.txns instance
This creates a new directory named "instance", hard-links transactions.txns to a file of the same name inside it, and creates two shell scripts: instance.driver and instance.rebuild. To run the pipeline, simply run instance.driver with no arguments; instance.rebuild may be used to rebuild the pipeline if the driver becomes corrupted from editing.
Additional options may be supplied to gateway-pipeline, which are remembered by the pipeline when executing it. These options are as follows:
| Short | Long | Description |
|---|---|---|
| -? | --help | Display the built-in help message. |
| -c | --count=i | Set the minimum count necessary for inclusion. |
| -C | --confidence=f | Set the minimum confidence necessary for inclusion. |
| -l | --lift=f | Set the minimum lift necessary for inclusion. |
| -o | --order=i | Set the maximum rule degree to mine. |
| -s | --support=f | Set the minimum support necessary for inclusion. |
| -V | --conviction=f | Set the maximum conviction necessary for inclusion. |