{"id":13835757,"url":"https://github.com/ribosomeprofiling/ribograph","last_synced_at":"2025-07-10T12:32:44.472Z","repository":{"id":65054528,"uuid":"581306673","full_name":"ribosomeprofiling/ribograph","owner":"ribosomeprofiling","description":"Interactive browser for Ribo files","archived":false,"fork":false,"pushed_at":"2024-03-03T22:14:50.000Z","size":1657,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-07-01T18:34:24.997Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ribosomeprofiling.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-12-22T20:29:08.000Z","updated_at":"2023-06-06T20:16:24.000Z","dependencies_parsed_at":"2023-01-13T15:23:11.994Z","dependency_job_id":"b0da4ec7-8ca2-4ff3-a4a0-ccef9c7b81fd","html_url":"https://github.com/ribosomeprofiling/ribograph","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ribosomeprofiling%2Fribograph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ribosomeprofiling%2Fribograph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ribosomeprofiling%2Fribograph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ribosomeprofiling%2Fribograph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ribosomeprofiling","download_url":"https://codeload.github.com/ribosomeprofiling/ribograph/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":213924053,"owners_count":15657934,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T15:00:18.716Z","updated_at":"2024-08-04T15:00:55.230Z","avatar_url":"https://github.com/ribosomeprofiling.png","language":"Python","funding_links":[],"categories":["Data Resources and Visualisation Environments"],"sub_categories":[],"readme":"# RiboGraph\n \n\u003ca href=\"https://github.com/ribosomeprofiling/ribograph\"\u003e\u003cimg width=\"30%\" src=\"docs/ribograph_logo.png\" alt=\"RiboGraph\"\u003e\u003c/a\u003e\n \nRiboGraph is an interactive, web-based visualization platform for analyzing ribosome profiling datasets. Users can upload ribosome profiling data using [ribo files](https://ribopy.readthedocs.io/en/latest/ribo_file_format.html) directly through the tool’s interface. These files are generated with [Riboflow](https://github.com/ribosomeprofiling/riboflow), part of a suite of applications found within a [software ecosystem](https://ribosomeprofiling.github.io/) designed to work with ribosome profiling data.\n\nRiboGraph provides immediate access to quality control (QC) visualizations, including read length distributions, regional RNA sequence counts, and metagene plots. Additionally, it offers detailed coverage maps for individual genes, and enabling comparative analysis between experiments. \n \n \n**RiboGraph** has been tested on Firefox and Safari and usage of these browsers are highly encouraged for RiboGraph.\n\n## Table of contents\n  - [Installation](#installation)\n  - [Usage](#usage)\n    - [Adding a Project](#adding-a-project)\n    - [Upload Ribo File](#upload-ribo-file)\n    - [QC Plots](#qc-plots)\n    - [Coverage Plots](#coverage-plots)\n    - [P-Site Correction](#p-site-correction)\n    - [Adding References](#adding-references)\n    - [More Files](#more-files)\n  - [Reference Compatibility](#reference-compatibility)\n  - [Development](#development)\n    - [Docker Compose Files](#docker-compose-files)\n    - [Linting and formatting](#linting-and-formatting)\n    - [References](#references)\n  - [Implementation Notes](#implementation-notes)\n    - [Django HTTPS API](#django-https-api)\n \n## Installation\nRiboGraph requires [Docker](https://docs.docker.com/install/). Here is a [tutorial for installing it on Ubuntu](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-18-04). If you're running into permission issues and being forced to run with sudo, [you might need to add yourself to the docker user group](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user).\n \nRiboGraph runs entirely within a Docker container, and local development should happen within this running container. All other dependencies, including required Python packages and Node.js, are installed inside the container.\n\nFirst, clone this repository.\n```\ngit clone https://github.com/ribosomeprofiling/ribograph.git --config core.autocrlf=input\n```\nThe config option ensures Unix style line endings. If you opt not to add this option, you may run into problems with building the Docker image on Windows devices.\n\nGo to the Docker folder.\n\n```\ncd ribograph/Docker/\n```\n\nMake sure that the docker-compose file is in the working folder.\n```\nls docker-compose_local.yml\n```\n \nBuild the container. This may take a while.\n```\ndocker compose -f docker-compose_local.yml build\n```\n \nOnce the container is ready, you can run the container.\n```\ndocker compose -f docker-compose_local.yml up\n```\n\nBy default, RiboGraph will store the ribo files under the current working directory under the folder named `ribo_folder`.\n\nNote you might run into issues on Windows when attempting to start the container due to Windows CRLF style line endings. Change the line endings for the .sh and .yml files in the Docker and Docker/web directory from CRLF to LF to fix these.\n\nWe recommend using \u003ca href=\"https://www.mozilla.org/\"\u003eFirefox\u003c/a\u003e for Ribograph. \u003ca href=\"https://www.mozilla.org/\"\u003e\n\u003cimg width=\"5%\" src=\"/docs/Firefox_logo,_2019.svg\" alt=\"Firefox\"\u003e\u003c/a\u003e\n\nOn your browser, go to the URL: [http://localhost:8000/](http://localhost:8000/). \nIf the container is built successfully, you should see a welcome prompt asking you to create a username and password.\n\n![Welcome Screen](/docs/screenshots/welcome.jpg?raw=true)\n \n\n## Usage\n\nAfter the docker instance is started, on first time use you will be prompted to create an admin user account. After this, login and you'll be able to add other users through the admin panel, as well as add projects and references.\n\n### Adding a Project\n\nClick on the \"+\" icon on the bottom right.\n\n![Add New Project](/docs/screenshots/add_project.jpg?raw=true)\n\nFill out the form. You can leave description box empty.\n\n![New Project Form](/docs/screenshots/project_creation_form.jpg?raw=true)\n\n### Upload Ribo File\n\nUpload your ribo file. If you don't have any, you can download a sample file: [GSM3323389.ribo](https://github.com/ribosomeprofiling/ribograph_sampledata/raw/main/human/GSM3323389.ribo). After you select your file and upload, the system will ask you to select experiments and confirm.\n\n![Ribo File Upload](/docs/screenshots/ribo_file_upload.jpg?raw=true)\n\n### QC Plots\n\nClick on the experiment name to go to the QC page.\n![Go to QC](/docs/screenshots/go_to_qc.jpg?raw=true)\n\nYou can use the slider to view a range of ribosome footprints.\n![QC Page](/docs/screenshots/qc_page.jpg?raw=true)\n\n\n### Coverage Plots\n\nFor individual transcripts, you can view the ribosome footprint coverage.\n\n![Go to coverage](/docs/screenshots/go_to_coverage.jpg?raw=true)\n\nYou can select transcripts or search them and see their coverage.\n\n![Coverage page](/docs/screenshots/coverage_page.jpg?raw=true)\n\n### P-Site Correction\nUsers can select offsets for P-Site Correction for each read length. These offsets can then be used for the coverage plot. Offsets for each experiment are kept in the user's browser local storage.\n\n![Go to offsets](/docs/screenshots/go_to_offsets.jpg?raw=true)\n\nYou can adjust the offset of each footprint length. Then you can save the offsets to use in the coverage.\n\n![Offsets](/docs/screenshots/offset_page.jpg?raw=true)\n\n![Using gOffsets](/docs/screenshots/use_offsets.jpg?raw=true)\n\n### Adding References\n\nTo be able to view nucleotide sequences in the coverage plot, you need to associate the experiment with a reference.\n\n![Reference Page](/docs/screenshots/reference_page.jpg?raw=true)\n\nReference files must be gzipped fasta files with the \"`fa.gz`\" extension. If you have the reference file you used for the ribo file, upload it, or if you downloaded and used the sample ribo file `GSM3323389.ribo`, then [download the corresponding refeerence file here](https://github.com/ribosomeprofiling/ribograph_sampledata/raw/main/human/appris_human_v2_selected.fa.gz).\n\nUpload the reference file and give a name to this entry.\n![Reference Page](/docs/screenshots/upload_reference.jpg?raw=true)\n\nGo back to the coverage page and match the experiment with the reference uploaded.\n\n![Reference Page](/docs/screenshots/select_reference.jpg?raw=true)\n\nClick on the \"Sequence\" to view the nucleotide sequences.\n\n![Reference Page](/docs/screenshots/view_nucleotides.jpg?raw=true)\n\n### More Files\n\nYou can find additional ribo files and references in the following GitHub repository:\n[https://github.com/ribosomeprofiling/ribograph_sampledata](https://github.com/ribosomeprofiling/ribograph_sampledata).\n\n## Reference Compatibility\n \nWhen an experiment is created in the system, an md5 hash sum of the reference of that experiment is also\nstored as an attribute of the experiment. This hash sum is obtained by computing the md5 sum of the string S1 + S2, where `+` stands for string concatenation. **S1** is the concatenation of the transcript names in the ribo file in the existing order and\n**S2** is the concatenation of the corresponding transcript lengths. The names and lengths are separated by `,` in concatenation.\n \nThe references of two experiments are called compatible if the hash sum of their references are the same. In practice, this means that\nthe two experiments are coming from the same transcriptomic reference and therefore their coverages can be viewed together.\n \nReference hash sum is an experiment attribute and it is stored in the `reference_digest` attribute.\n \n\n\n## Development \n\n### Docker Compose Files\nRibograph is composed of both a Django backend and a Vue frontend. With the `docker-compose_local.yml` file, the Django development server is started, but not the Vue development server. If you'd like a live reloading development server for the Vue files, use the `docker-compose_local_dev.yml` file.\n\n### Linting and formatting\nWe use [black](https://black.readthedocs.io/en/stable/) to format Python files and [djlint](https://www.djlint.com/) to format Django templates.\n \nTo reformat python files:\n```\nblack .\n```\n \nTo lint template files:\n```\ndjlint .\n```\n \nTo reformat template files:\n```\ndjlint . --reformat\n```\n \n\n\n### References\nWhen a ribo file is uploaded, a hash sum is computed for the transcript names and their corresponding lengths. More precisely, the transcript names and their lengths are concatenated and a single md5 sum of the entire string is computed. This value is used to compare two experiments to conclude whether they have the same transcriptome reference or not.\n\nWhen  there is an attempt of matching an experiment with a reference, transcript names and lengths are compared one-by-one and if the first mismatch is reported. This way users can clearly see why their reference does not match that of the experiment.\n\n## Implementation Notes\nRiboGraph is implemented as a Django web app that uses Vue supplementally to provide reactivity on the front-end. During development (when running [docker-compose_local_dev.yml](Docker/docker-compose_local_dev.yml)), both the Django dev server and the hot reloading Vue dev server are run in parallel.\n\nSince most users of RiboGraph will not be developing it, the [docker-compose_local.yml](Docker/docker-compose_local.yml) file will build the Vue project into static assets that are served through Django. This logic is implemented in the [vue_app](ribograph/browser/templates/browser/vue_app.html) Django template. Because of this, the Vue dev server will not need to be started, which will save system resources.\n \n### Django HTTPS API\nThe Vue app interfaces with the Django backend through [an HTTP API](ribograph/browser/api.py) defined in [api.py](ribograph/browser/api.py). \nThis API provides the front-end with the data required to render charts. Generally, each chart pulls its data from\na different endpoint, so that visualizations can be shown to the user as soon as the appropriate data is ready.\n\nFunctions that define endpoints are decorated with either `@register_experiment_api` or `@register_project_api`, which takes\ncare of registering the URL (by default, the function's name), serializing responses as JSON, and caching \nresults for around 10 minutes for faster results and a smoother user experience. Documentation for these API endpoints \ncan be found in the docstring for the respective function. Most APIs pull data from a single experiment, such as metagene counts or coverage data, but some APIs pull data from multiple experiments, like the gene correlation analysis. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fribosomeprofiling%2Fribograph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fribosomeprofiling%2Fribograph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fribosomeprofiling%2Fribograph/lists"}