The ExpressionMatrix2 code can be started in http server mode as described here. In this mode of operation, ExpressionMatrix2 code maps all of its data structures in virtual memory, then waits for requests from a client, that is, a Web browser. This allows exploring the expression matrix data in a variety of ways, including creating cell similarity graphs.
Keep in mind that the server has no mechanism in place to control access. This means that, when the server is running, your data will be accessible to anybody with access to the local machine, or to any local or remote machine for which firewall rules allow an inbound connection to the server port.
If access to the data being analyzed needs to be limited, firewall rules or other provisions must be deployed to prevent unauthorized access. The easiest way to prevent access to other users is to run the server on a single-user machine with a firewall setup that allows no inbound connections, and then to access the server from a browser running on the same single-user machine.
In the simplest case, the browser runs on the same machine that runs the server. In this case, you can access the server by pointing your browser to http://localhost:17100, where the port number must agree with the port number used in the Python code that started the server.
Alternatively, the browser can run on a different machine (typically a local desktop, laptop, or other device connected to the Internet). In this case the URL must specify, instead of localhost, the name or ip address of the machine running the server. For example, assuming the server is using port 17100:
192.168.1.20:17100 myserver.mycompany:17100Note that, for this mode of operation to work, firewall rules on the machine running the server must allow inbound connections to the port the server is listening to. In this case, THE IMPORTANT SECURITY WARNING IN THE PREVIOUS SECTION APPLIES.
Note that, if the server uses an ipv6 address, the ip address must be enclosed in brackets. For example:
[2001:db8:a0b:12f0::1]:17100
Depending on browser choice and settings, it may be necessary to use an http:// prefix when entering these URLs. For example:
htpp://192.168.1.20:17100 htpp://myserver.mycompany:17100
If the server is running on an Amazon AWS EC2 instance, you must run the browser on your local machine. To access the server, you can use the "IPv4 Public IP" address available in the Amazon AWS console for the instance your server is running on. However, for this to work, you need to authorize inbound connections, on that instance, to the port or ports you will be using. To do this, you must do the following in the Amazon AWS console:
The ExpressionMatrix2 code was developed and tested using Firefox and Chrome as a browser. However most functionality should work with most browsers, including the ones available on cell phones.
Some versions of the Firefox and Chrome browsers, and perhaps other browsers too, make speculative connections to the server to improve performance in some cases. This does not work well with the ExpressionMatrix2 http server, which is single-threaded, and can cause long delays before a server response is seen in the browser. If the server log repeatedly shows the message "Empty request ignored", you can improve response time as follows:
network.http.speculative-parallel-limit to 0.
The http server supports the following types of functionality:
The server has no notion of users. If multiple users access the same server, they all see all of the cell sets and cell similarity graphs created by all users. Also, each is allowed to remove cell sets and graphs created by other users. Server operation is singlke-threaded, so multi-user operations are serialized. In other words, if a user starts a long-run ing operation such as creating a large graph, other users will have to wait for completion of the long-running operation before the server responds to their requests. Depending on network and browser set up, under these circumstances a user could encounter a time out.
You can define a cell set to restrict processing (in particular, the creating of a cell similarity graph) to a subset to all the cells present in a run.
To create a cell set, click on the "Cell Sets" button at the top of the browser window. This presents three ways to define a new cell set: using meta data, by intersection or union of other cell sets, or by randomly downsampling an existing cell set.
By combining these three ways to create cell sets, you have great flexibility in defining a subset of cells to work on. We will also see below that, after a graph has been created, clustering on the graph creates new meta data. That meta data can be used to define cell sets consisting of one or more clusters.
Cell sets are persistent: they exists until removed, even if the server is stopped and then restarted.
Here, you can define a new cell set as the cet of cells for which a specified meta data field matches a regular expression you choose. For example, suppose your cells have a meta data field named "Sample" that contains the name of the sample from which each cell originated. Lets say you want to create a cell set including only the cells for which meta data "Sample" equals "BH22C". To define the cell set you choose a cell set name, pick meta data Sample, and in the regular expression field you just enter "BH22C". After pressing Enter, the newly created cell set will appear in the table of existing cell sets. You can use the button on the last column of that table to remove the cell set.
Regular expressions are very powerful and can do much more complex things than just select a value. For example, to select all the samples that begin with "BH" you could enter the following as the regular expression: "BH.*". See the Wikipedia article for more possibilities.
Here you type the name of the cell set to be created, select "intersection" or "union", and then select two existing cell sets (using the Ctrl key).
You can create any number of cell similarity graphs using different graph creation parameters and cell sets. However, keep in mind that graphs are not persistent, and they disappear if the server is stopped and then restarted.
To create a new graph, click on the "Graphs" button near the top of the browser window. A table appears, showing currently defined graphs. You can create a new graph by filling in the last row of the table then clicking on "Create a new graph". You can also remove an existing graph by clicking on a "Remove graph" button in the last ciolumn of the table. Here is a description of the entries you need to fill in:
After you click on "Create a new graph" you will see a window with some log output created while the graph and its layout are computed, then a Continue button that, when clicked, will bring you back to the table containing all currently defined graph. The table will now include the graph you just created. You can click on the name of the graph in the first column of the table to display the graph.
When a graph is displayed, there are buttons to control the geometry of the display: you can make the graphics smaller or larger, you can zoom and pan, and you can draw vertices larger or smaller, and edges thicker or thinner. You can also control the way the graph is colored. The controls for that should be self-explanatory.