-
Notifications
You must be signed in to change notification settings - Fork 4
Adding a Private Project
Welcome to iModulonDB! To see the public site, click here.
All websites have a "server side" and "client side". The client side consists of code that runs in the browser -- this is everything from the HTML that describes the features on the page to the JavaScript that provides basic responsiveness functionality. The server side sends all necessary data to the client side, and also can receive data (such as account information, data uploads, etc) and process it with more advanced coding languages.
When we built iModulonDB, the goal was to obtain a functioning database for our public data. Since the public data is not going to change except when new projects are added, we opted for the simplest type of server side stack possible: github pages. GHPages allows us to host the site for free (taking care of a lot of maintenance and security frustrations), but it will not let us run any code on the server side. This means we cannot verify the identities of people who visit the site, for example by creating accounts for them. Everything on the site is public to everyone, so unpublished data should not be uploaded to it.
iModulonDB is a powerful tool that could help labmembers with the early stages of iModulon characterization, so we have written this wiki to guide you through a method to use the site for your own yet-to-be-published iModulon characterization without adding anything to the public site. You will download all necessary files to host the site on your own computer such that only you can view it. Then you will add your own data to your private version of the site. This way, you can update the information in your browser instantaneously whenever you make a change to a file, and only you will be able to see all of the information until it is ready for the world. If you'd like to share it before then with someone in the lab, you can copy your folders and share them with that person, then they can use the same localhost strategy here to view your dashboards.
Please reach out to Kevin Rychel (krychel@eng.ucsd.edu) if you have any issues or questions!
In this section, we will get the version of the site that is public running on your own private computer.
Prerequisites:
- Jupyter notebooks (Python 3)
- Pymodulon and all required packages
- Terminal that can run python (either python 2 or 3)
- Not necessary, but recommended: Git or Github Desktop
In this subsection, we'll get you started with the basic folder structure.
- Create a folder on your local computer and call it 'iModulonDB' (or whatever you want). This will be the home of your private version of iModulonDB.
- Clone this repository into your iModulonDB folder. Use git or github desktop to do so. If you are new to git/github, you can simply download the repository and unzip it here, but that is not recommended because continual improvements will be made to the site and git will allow you to merge them into your local version. You might also want to create your own branch, since you could eventually push this site to master for publication.
The iModulonDB codebase contains ajax queries, which requires that the site's pages be hosted on a server (as opposed to very simple HTML pages, which can be opened in a browser without a server). In this subsection, we'll get a local host server running and make sure the public site works from it.
Every time you want to access your website, you must have this server running.
- Open a terminal. This must be on your local machine, even if you typically use remote access. If you are using windows and are not used to using the windows shell, I recommend Cygwin because it accepts linux commands.
- Navigate to your folder. For example:
cd C:/Users/kevin/'Dropbox (UCSD SBRG)'/iModulonDB - Start the server using a single line of python code. This will depend on the version of python you have installed in the terminal you are using. After a few moments, the terminal should print "Serving HTTP on 0.0.0.0 port 8000 ..."
- Python 2:
python -m SimpleHTTPServer - Python 3:
python -m http.server
- Python 2:
- In your browser, go to 'localhost:8000'. You should see the iModulonDB splash page and be able to navigate everything exactly like the public site.
- At any time, you can close the terminal window or use ctrl+C to stop running the server. localhost:8000 will refuse to connect to your browser if the server is not running.
Now that you have the website on your machine, it's time to add your data.
See the pymodulon tutorial for advice on how to add your data to the pymodulon data structure. At a minimum, you must have the following:
- M matrix (part of initial ICA output)
- A matrix (part of initial ICA output)
- X matrix (log_tpm.csv) -- initial data, preferably not normalized to the base condition.
- Sample_table containing:
- Either a column labeled 'sample' or an index (leftmost column) that serves the purpose of sample labels. These should be unique to each sample (no duplicates in the entire table), and it must match the columns of A and X.
- A column labeled 'project' -- this is the largest grouping of samples; they may be downloaded from the same original paper or contain a set of samples/experiments with a common theme. The contents of this column will appear on the X axis when zoomed all the way out in the activity bar graphs on iModulonDB.
- A column labeled 'condition' -- this groups samples such that all biological replicates have the same condition name. Samples in the same project with matching conditions will be grouped into a single bar in the activity bar graphs. If you'd like to re-use condition names across different projects (for example, giving each project a 'control' condition), that is okay.
The more additional information you have (gene_table, trn, imodulon_table, etc), the more informative the website will become.
Follow the instructions in the template. This will generate all files necessary for the site. If you run into an issue with this step, contact Kevin.
The last step is to add a small amount of HTML code, which will be generated by the jupyter notebook, into 'iModulonDB/index.html'. This will create a link on the main page of localhost, which should be highlighted in red as a private dataset. Once this is done, the site should be up and running for you!
If you change any files, be sure to re-run the export function. Each time you refresh the page on your localhost, it should update with the new files. If for some reason it doesn't, try using Ctrl+Shift+R in your browser, which should force it to re-request the data files.