diff --git a/.gitignore b/.gitignore index f3d0c71..5094724 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ +venv _build _templates .idea \ No newline at end of file diff --git a/README.md b/README.md index b6e9bfb..6f45da0 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,22 @@ This project contains the complete user manual for GraphSpace. While the manual sources are maintained in GitHub, the document is actually assembled, formatted, and staged by the ReadTheDocs.org site. ReadTheDocs presents online and PDF versions, and we will use both. + +## Building GraphSpace User Manual Locally + +The following steps needs to be followed in order to build the Manual locally. + +1. Download the GraphSpace User Manual Source by running `git clone https://github.com/adbharadwaj/graphspace-manual.git`. +2. Navigate to GraphSpace User Manual directory: `cd graphspace-manual` +3. Create a virtual environment for the project: `virtualenv venv` +4. Start using the virtual environment: `source venv/bin/activate` +5. Install all dependencies: `pip install -r requirements.txt` +6. Navigate to docs directory: `cd docs` +7. To build HTML files run the command: make html +8. Navigate to builds/html directory: `cd _build/html` +9. Open `index.html` on a web browser like Google Chrome or Mozilla Firefox + + ## Editing the Manual To edit manual text, you must first check out this repository and use a text editor on your workstation. (You can use GitHub's native Markdown editor, too, for small edits.) @@ -26,4 +42,3 @@ The "latest" manual is automatically rebuilt by ReadTheDocs when the GitHub repo The rebuild can be observed by logging into the ReadTheDocs account (see me for credentials) and choosing the "graphspace" project. To see the build log, click on the grey Builds button. You can watch the progress of the build by manually refreshing your browser window until the build status shows either Passed or Failed - a build can take anywhere from 3 minutes to 10 minutes, depending on how busy the build server is. When the build is complete, if the status shows Passed, you can view the build result by clicking on the green View Docs button. The document will also be available via http://manual.graphspace.org/en/latest. - diff --git a/docs/Graph_Version.md b/docs/Graph_Version.md new file mode 100644 index 0000000..fc98bc9 --- /dev/null +++ b/docs/Graph_Version.md @@ -0,0 +1,34 @@ +# Graph Versioning + +The Graph Version feature gives Users the ability to create different versions of Graphs in GraphSpace. The User needs to be signed-in to GraphSpace in order to use this feature. [GraphSpace](http://www.graphspace.org) allows users to create version of a Graph through GraphSpace's REST APIs. + +The following features are available in the Graph Version functionality: + +- [Graph Versions Tab](#graph-versions-tab) +- [Graph Versioning Using REST APIs](#graph-versioning-using-rest-apis) + + +## Graph Versions Tab + +The `Graph Versions` tab displays information about the different versions of the graph in a table format. The table contains following columns: + +1. **Version Name** - Name of the forked graph. +2. **Description** - Tags associated with the forked graph. +3. **Created at** - Email address of the owner of the graph. + +The image below shows an example of Graph Versions Tab when a user clicks on the `Graph Version` tab link: + +![Forked Graphs Tab Image](_static/gifs/gs-screenshot-LocalUser1-graph_version.gif) + + +### Graph Version Dropdown Selection + +Users of GraphSpace can also select available Graph Versions using the Drop-down menu. The Drop-down menu displays the currently selected Graph Version. + + +![Forked Graphs Dropdown Image](_static/images/graph-page/gs-screenshot-LocalUser1-graph-version-dropdown.jpg) + + +## Graph Versioning Using REST APIs + +The User can Create, Update & Delete Graph Versions using the [GraphSpace REST APIs](Programmers_Guide.html#api-reference) diff --git a/docs/Programmers_Guide.md b/docs/Programmers_Guide.md index f2434b9..ee4f746 100644 --- a/docs/Programmers_Guide.md +++ b/docs/Programmers_Guide.md @@ -32,7 +32,7 @@ The GraphSpace REST API is served over HTTP. In case you are ### API Reference - + ## graphspace-python diff --git a/docs/Quick_Tour_of_GraphSpace.md b/docs/Quick_Tour_of_GraphSpace.md index 1f077aa..a1c9dc9 100644 --- a/docs/Quick_Tour_of_GraphSpace.md +++ b/docs/Quick_Tour_of_GraphSpace.md @@ -34,19 +34,23 @@ The user can log-in to [GraphSpace](http://www.graphspace.org) by following the ![Log In](_static/gifs/gs-screenshot-user1-logging-in-with-caption.gif) -For the rest of the tutorial, we assume that the user has already created an account. We also assume that the user belongs to a group with shared networks or that the user uploaded networks via the [upload page](/Uploading_Graphs.html#upload-page) or the [RESTful API](/Programmers_Guide.html#api-reference). The tutorial specifically steps through how ``user1@example.com`` interacts with GraphSpace after logging in. +For the rest of the tutorial, we assume that the user has already created an account. We also assume that the user belongs to a group with shared networks or that the user uploaded networks via the [upload page](Uploading_Graphs.html#upload-page) or the [RESTful API](Programmers_Guide.html#api-reference). The tutorial specifically steps through how ``user1@example.com`` interacts with GraphSpace after logging in. ### Upload a graph The user can upload a graph on [GraphSpace](http://www.graphspace.org) by following the given steps: 1. Go to the [Upload Graph Page](http://www.graphspace.org/upload) by clicking on the `Upload Graph` button on [Home Page](http://www.graphspace.org/). -2. Enter a [unique name](/Uploading_Graphs.html#graph-name) for the new graph. -3. Select a [CYJS file](/GraphSpace_Network_Model.html#cyjs-format) which contains the graph information. -4. Select a [JSON file](/GraphSpace_Network_Model.html#stylesheet-json-format) which contains the style information for the graph. (Optional Step) +2. Enter a [unique name](Uploading_Graphs.html#graph-name) for the new graph. +3. Select a [CYJS file](GraphSpace_Network_Model.html#cyjs-format) which contains the graph information. +4. Select a [JSON file](GraphSpace_Network_Model.html#stylesheet-json-format) which contains the style information for the graph. (Optional Step) 5. Click on `Submit` button to upload the graph using the selected files. 6. Once the graph has been uploaded, [GraphSpace](http://www.graphspace.org) will provide a unique URL through which the user may interact with the graph represented by the uploaded files. +You can use the following sample files to learn how to upload graphs to GraphSpace: +- [Sample network file](_static/sample_graph.cyjs) +- [Sample style file](_static/sample_stylesheet.json) + ![Upload a graph](_static/gifs/gs-screenshot-user1-upload-graph-with-caption.gif) ### List of uploaded graphs @@ -62,12 +66,12 @@ In this example, the user owns 33 graphs, can access 64 public graphs and 33 gra ## Searching within Multiple Graphs -The search interface in GraphSpace allows a user to search for networks that have a specific attribute or tag and contain one or more nodes using [simple syntax](/Searching_Graphs.html#query-semantics) on [Graphs Page](http://www.graphspace.org/graphs/) by following the given steps: +The search interface in GraphSpace allows a user to search for networks that have a specific attribute or tag and contain one or more nodes using [simple syntax](Searching_Graphs.html#query-semantics) on [Graphs Page](http://www.graphspace.org/graphs/) by following the given steps: 1. Enter the name of the graph/node or specific network attribute mapping you are searching for in the search bar. 2. Press `Enter` key or click on the `Search` button. -In this example, the user searches for the list for graphs that contain the protein (node) `CTNNB1` (the symbol for β-catenin, a transcriptional regulator in the Wnt signaling pathway). The reduced list of graphs are the graphs where protein (node) ``name``, ``label`` or ``aliases`` contain `CTNNB1` as a substring. The match is case-insenstive. In the following example, There are six graphs owned by the user and thirty-two public graphs that contain this protein. Each link in the `Graph Name` column will take the user to a specific graph with the search term [highlighted](/Viewing_Graphs.html#highlighted-graph-elements). In this example, the user clicks on the graph with the name `KEGG-Wnt-signaling-pathway` and reaches the graph for the Wnt pathway with the searched node [highlighted](/Viewing_Graphs.html#highlighted-graph-elements). +In this example, the user searches for the list for graphs that contain the protein (node) `CTNNB1` (the symbol for β-catenin, a transcriptional regulator in the Wnt signaling pathway). The reduced list of graphs are the graphs where protein (node) ``name``, ``label`` or ``aliases`` contain `CTNNB1` as a substring. The match is case-insenstive. In the following example, There are six graphs owned by the user and thirty-two public graphs that contain this protein. Each link in the `Graph Name` column will take the user to a specific graph with the search term [highlighted](Viewing_Graphs.html#highlighted-graph-elements). In this example, the user clicks on the graph with the name `KEGG-Wnt-signaling-pathway` and reaches the graph for the Wnt pathway with the searched node [highlighted](Viewing_Graphs.html#highlighted-graph-elements). ![Searching within Multiple Graphs](_static/gifs/gs-screenshot-user1-searching-withing-multiple-graphs-with-caption.gif) @@ -75,23 +79,23 @@ In this example, the user searches for the list for graphs that contain the prot The user can search for node or edges within a given graph on [GraphSpace](http://www.graphspace.org/) by following the given steps: -1. Enter the name of the node or an edge you are searching for in the [search bar](/Interacting_with_Graphs.html#search). -2. The nodes or edges are [highlighted](/Viewing_Graphs.html#highlighted-graph-elements) automatically as you type in the name of the node or edge in the search bar. +1. Enter the name of the node or an edge you are searching for in the [search bar](Interacting_with_Graphs.html#search). +2. The nodes or edges are [highlighted](Viewing_Graphs.html#highlighted-graph-elements) automatically as you type in the name of the node or edge in the search bar. -In the following example, the user searches for the graph for two proteins (nodes) `CTNNB1` and `WNT` using the query `ctnnb1, wnt`. This search query [highlights](/Viewing_Graphs.html#highlighted-graph-elements) the proteins where protein (node) ``name``, ``label`` or ``aliases`` contains `CTNNB1` or `WNT` as a substring (case-insensitive). In the following example, the graph contains four nodes which match the given query. +In the following example, the user searches for the graph for two proteins (nodes) `CTNNB1` and `WNT` using the query `ctnnb1, wnt`. This search query [highlights](Viewing_Graphs.html#highlighted-graph-elements) the proteins where protein (node) ``name``, ``label`` or ``aliases`` contains `CTNNB1` or `WNT` as a substring (case-insensitive). In the following example, the graph contains four nodes which match the given query. ![Searching nodes within a Single Graph](_static/gifs/gs-screenshot-user1-searching-nodes-within-a-single-graphs-with-caption.gif) -In the following example, the user [searches the graph for edges](/Searching_Graphs.html#query-semantics) from `Wnt` to `Fzd` using the query `Wnt::Fzd`. GraphSpace -[highlights](/Viewing_Graphs.html#highlighted-graph-elements) any edge whose tail node matches ``wnt`` and whose head node matches ``fzd``. In the following example, the graph contains three edges which match the given query. +In the following example, the user [searches the graph for edges](Searching_Graphs.html#query-semantics) from `Wnt` to `Fzd` using the query `Wnt::Fzd`. GraphSpace +[highlights](Viewing_Graphs.html#highlighted-graph-elements) any edge whose tail node matches ``wnt`` and whose head node matches ``fzd``. In the following example, the graph contains three edges which match the given query. ![Searching edges within a Single Graph](_static/gifs/gs-screenshot-user1-searching-edges-within-a-single-graphs-with-caption.gif) ## Interacting with a Graph -In this section, we examine [different ways to interact with an individual network](/Interacting_with_Graphs.html) on its page. The information that appears in following examples must be included in the JSON files that are uploaded by the network owner, as described in the [Network Model](/GraphSpace_Network_Model.html) section. An individual network page is designed to access features like: +In this section, we examine [different ways to interact with an individual network](Interacting_with_Graphs.html) on its page. The information that appears in following examples must be included in the JSON files that are uploaded by the network owner, as described in the [Network Model](GraphSpace_Network_Model.html) section. An individual network page is designed to access features like: - [Graph Information](#graph-information) - [Edge and Node Information](#edge-and-node-information) @@ -101,20 +105,20 @@ In this section, we examine [different ways to interact with an individual netwo ### Graph Information -As its name suggests, the `Graph Information` panel displays information about the entire graph, e.g., a legend of node and edge shapes and colors. The ``description`` attribute in the [JSON for the network](/GraphSpace_Network_Model.html#graph-data-attributes) specifies this content. The user can go to `Graph Information` panel by clicking on the `Graph Information` link above the graph. +As its name suggests, the `Graph Information` panel displays information about the entire graph, e.g., a legend of node and edge shapes and colors. The ``description`` attribute in the [JSON for the network](GraphSpace_Network_Model.html#graph-data-attributes) specifies this content. The user can go to `Graph Information` panel by clicking on the `Graph Information` link above the graph. ![Graph Details](_static/gifs/gs-screenshot-user1-graph-information-with-caption.gif) -Please refer to [this section](/Viewing_Graphs.html#graph-information-tab) for more information. +Please refer to [this section](Viewing_Graphs.html#graph-information-tab) for more information. ### Edge and Node Information -Clicking on a node or edge pops up a panel with information on that node or edge. The ``popup`` attribute for the node in the [network JSON](/GraphSpace_Network_Model.html#cyjs-format) specifies this content. +Clicking on a node or edge pops up a panel with information on that node or edge. The ``popup`` attribute for the node in the [network JSON](GraphSpace_Network_Model.html#cyjs-format) specifies this content. ![Edge and Node Information](_static/gifs/gs-screenshot-user1-node-edge-pop-up-with-caption.gif) -Please refer to [this section](/Viewing_Graphs.html#node-and-edge-popups) for more information. +Please refer to [this section](Viewing_Graphs.html#node-and-edge-popups) for more information. ### Export Graph @@ -124,7 +128,7 @@ In the following example, the user is exporting the graph as an image in PNG for ![Export Graph](_static/gifs/gs-screenshot-user1-export-graph-png-with-caption.gif) -Please refer to [this section](/Interacting_with_Graphs.html#export) for more information. +Please refer to [this section](Interacting_with_Graphs.html#export) for more information. ### Change Layout @@ -142,7 +146,7 @@ In the following example, the user selects to view the layout titled "manual-top ![Change Layout](_static/gifs/gs-screenshot-user1-change-layout-with-caption.gif) -Please refer to [this section](/Interacting_with_Graphs.html#change-layout) for more information. +Please refer to [this section](Interacting_with_Graphs.html#change-layout) for more information. ### Share Layout @@ -159,5 +163,5 @@ Note: The icons next to each layout name allow the user to (i) change its name, ![Share Layout](_static/gifs/gs-screenshot-user1-share-layout-with-caption.gif) -Please refer to [this section](/Sharing_Graphs.html#sharing-layouts-with-group-s) for more information. +Please refer to [this section](Sharing_Graphs.html#sharing-layouts-with-group-s) for more information. diff --git a/docs/Uploading_Graphs.md b/docs/Uploading_Graphs.md index eee4efa..7b6380a 100644 --- a/docs/Uploading_Graphs.md +++ b/docs/Uploading_Graphs.md @@ -4,7 +4,7 @@ 1. Users may create their own [JSON files](GraphSpace_Network_Model.html) and upload networks one-by one via the [web interface](#upload-page) at http://graphspace.org/upload. -2. Cytoscape users may export their visually-coded networks from Cytoscape and [import them directly into GraphSpace](Uploading_Graphs.html#style-file). This functionality works as follows. Since v3.1, Cytoscape has supported export of the structure of networks into JSON files and the visual elements of networks in JSON-based style files. GraphSpace can import [both these types of files](GraphSpace_Network_Model.html) at http://graphspace.org/upload. Moreover, users can import a Cytoscape style file when they are [editing the layout](Editing_Layouts.html) of a network in GraphSpace. In the future, we intend to develop a Cytoscape app to make the integration between the two systems seamless. +2. Cytoscape users may seamlessly export their visually-coded networks from Cytoscape directly to GraphSpace using the new [CyGraphSpace App](http://apps.cytoscape.org/apps/cygraphspace). The app works by exporting the structure of networks to JSON (CYJS) and the visual elements of networks to JSON-based style files and then uploads them to GraphSpace using the REST API. Cytoscape users may also manually export the network structure and style files and upload them to GraphSpace at http://graphspace.org/upload. Moreover, users can import a Cytoscape style file when they are [editing the layout](Editing_Layouts.html) of a network in GraphSpace. In the future, we intend to update the Cytoscape app to sync different styles/layouts with Cytoscape. 3. A comprehensive [RESTful API](Programmers_Guide.html#graphspace-rest-api) and a [Python module](Programmers_Guide.html#graphspace-python) called “graphspace_python” facilitate bulk uploads of networks. Both the API and the module are easy to integrate into software pipelines. Please refer to the [Programmer's Guide](Programmers_Guide.html) for more information. diff --git a/docs/_static/gifs/gs-screenshot-LocalUser1-graph_version.gif b/docs/_static/gifs/gs-screenshot-LocalUser1-graph_version.gif new file mode 100644 index 0000000..dbe65c5 Binary files /dev/null and b/docs/_static/gifs/gs-screenshot-LocalUser1-graph_version.gif differ diff --git a/docs/_static/images/graph-page/gs-screenshot-LocalUser1-graph-version-dropdown.JPG b/docs/_static/images/graph-page/gs-screenshot-LocalUser1-graph-version-dropdown.JPG new file mode 100644 index 0000000..ddc2b62 Binary files /dev/null and b/docs/_static/images/graph-page/gs-screenshot-LocalUser1-graph-version-dropdown.JPG differ diff --git a/docs/_static/images/graph-page/gs-screenshot-LocalUser1-graph_version.png b/docs/_static/images/graph-page/gs-screenshot-LocalUser1-graph_version.png new file mode 100644 index 0000000..6311fca Binary files /dev/null and b/docs/_static/images/graph-page/gs-screenshot-LocalUser1-graph_version.png differ diff --git a/docs/_static/sample_graph.cyjs b/docs/_static/sample_graph.cyjs new file mode 100644 index 0000000..59d5bda --- /dev/null +++ b/docs/_static/sample_graph.cyjs @@ -0,0 +1,57 @@ +{ + "format_version": "1.0", + "generated_by": "graphspace-2.0.0", + "target_cytoscapejs_version": "~2.7", + "elements": { + "nodes": [ + { + "data": { + "id": "P4314611", + "k": 0, + "name": "P4314611", + "label": "Sample Node 1", + "aliases": [], + "popup": "Popup for node 1
A string that will be displayed in a popup window when the user clicks the node/edge.
This string can be HTML-formatted information, e.g., Gene Ontology annotations and database links for a protein; or types, mechanism, and database sources for an interaction." + }, + "position": { + "x": 297.5, + "y": 277.5 + } + }, + { + "data": { + "id": "P0810711", + "k": 0, + "name": "P0810711", + "label": "Sample Node 2", + "aliases": [], + "popup": "Popup for node 2
A string that will be displayed in a popup window when the user clicks the node/edge.
This string can be HTML-formatted information, e.g., Gene Ontology annotations and database links for a protein; or types, mechanism, and database sources for an interaction." + }, + "position": { + "x": 892.5, + "y": 277.5 + } + } + ], + "edges": [ + { + "data": { + "target": "P0810711", + "k": 0, + "source": "P4314611", + "is_directed": 1, + "id": "P4314611-P0810711", + "name": "Sample Edge", + "popup": "Popup for edge
A string that will be displayed in a popup window when the user clicks the node/edge.
This string can be HTML-formatted information, e.g., Gene Ontology annotations and database links for a protein; or types, mechanism, and database sources for an interaction." + } + } + ] + }, + "data": { + "description": "Description of graph.. can also point to an image hosted elsewhere", + "name": "Graph Name", + "tags": [ + "tutorial" + ] + } +} \ No newline at end of file diff --git a/docs/_static/sample_stylesheet.json b/docs/_static/sample_stylesheet.json new file mode 100644 index 0000000..009649e --- /dev/null +++ b/docs/_static/sample_stylesheet.json @@ -0,0 +1,51 @@ +{ + "format_version": "1.0", + "generated_by": "graphspace-2.0.0", + "target_cytoscapejs_version": "~2.7", + "style": [ + { + "selector": "node[name='P4314611']", + "style": { + "border-color": "#888", + "text-halign": "center", + "text-valign": "center", + "border-width": "2px", + "height": "50px", + "width": "50px", + "shape": "ellipse", + "background-blacken": "0.1", + "background-color": "yellow" + } + }, + { + "selector": "node[name='P0810711']", + "style": { + "text-halign": "center", + "text-valign": "center", + "text-outline-color": "#888", + "text-outline-width": "2px", + "border-color": "black", + "border-width": "5px", + "height": "150px", + "shape": "ellipse", + "color": "black", + "border-style": "double", + "text-wrap": "wrap", + "background-blacken": "0", + "width": "150px", + "background-color": "red" + } + }, + { + "selector": "edge", + "style": { + "curve-style": "bezier", + "line-style": "dotted", + "width": "12px", + "line-color": "blue", + "source-arrow-color": "yellow", + "target-arrow-shape": "triangle" + } + } + ] +} \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 3d08fe4..00abcf2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -21,6 +21,7 @@ GraphSpace 2.0 User Manual Interacting_with_Graphs Searching_Graphs Sharing_Graphs + Graph_Version Editing_Layouts Organizing_Graphs_Using_Tags Programmers_Guide diff --git a/requirements.txt b/requirements.txt index a92c48a..5b2aeab 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,3 @@ sphinx-rtd-theme -sphinx +sphinx==1.6.7 recommonmark \ No newline at end of file