About dgraphconnect
DataGraph includes a command utility called dgraphconnect. This program is a Unix executable that connects to DataGraph and allows scripts to open and modify a DataGraph file. It is intended for shell scripts or scripting programs like Python.
Suggested uses are scripting and real time data data coming from non-graphical applications. For GUI applications, the framework might be easier to use.
This feature is under development and suggestions are welcome. You should be able to do basically anything through this command line interface. Some things will not be supported, but you can always send in requests.
Streaming interface for DataGraph
The dgraphconnect utility is in the application wrapper of program that is downloaded from Visual Data Tools (i.e., not included in the macApp store version of DataGraph).
There are two ways to activate dgraphconnect:
- Launch DataGraph from the command line and pipe in something to standard in.
- A simpler way is to use the dgraphconnect command line utility to communicate with DataGraph. This means that DataGraph needs to be running at the time, but the command line can issue commands.
The actions will mimic the UI actions. The key concept is that the command line interface keeps a focus state. That is, at the top is the file, inside that the focus is either on a graph, column or variable. If you are focused on a graph, you can also be focused on a command inside that graph. For commands, you can focus further on one of the composite entries like a line in a bars graph or a mask line. Once you have focus, you can set key-value properties to change column selectors, menu entries, text fields etc. The current state is displayed in the lower right corner and updated automatically. You can also add/delete entries.
If you are using a version of DataGraph downloaded from the Visual Data Tools web site, you can access dgraphconnect from the DataGraph application wrapper. Go to (Shift-⌘-G):
/Applications/DataGraph.app/Contents/Library/
Issuing Commands
Commands have a natural language feel, and instead of saying “delete plot 2 in graph 2” you need to first set focus on graph 2 with “focus on graph 2” and then do “delete plot 2” on the next line.
The available commands are listed in the dgraphconnect debug window. Open the debug window by issuing the debug command:
/Applications/DataGraph.app/Contents/Library/dgraphconnect debug
From the terminal, you can issue any of the available commands.
When a connection is made to a file, the list of available commands is much longer.
To end the dgraphconnect process from the terminal, type control-C at the command line.
The data streams in asynchronously, so you can use the UI as a remote application that is feeding in data. It can be thought of as additional fingers, and if you delete entries that the stream expects to be there you will get a lot of error messages.
The dgraphconnect utility can be called multiple times, and you can hand it arguments to set up things. For example, if you want to open the DataGraph file /Users/david/file.dgraph and append a text file to the columns x and y, you can do that by
cat /tmp/text | dgraphconnect -file /Users/david/file.dgraph -append x,y
To append more data to x,y:
cat /tmp/moretext | dgraphconnect -append x,y
This works since the dgraphconnect does not loose the state information, namely the current file.
Future Development
This interface is intended for more advances users. Please let us know if anything is unclear or you need a particular functionality. The future development of this functionality will depend on user feedback.