Update documentation

CONTRIBUTING.md

@@ -8,49 +8,9 @@ Please note we have a code of conduct, please follow it in all your interactions
 
 1. Ensure any install or build dependencies are removed before the end of the layer when doing a build.
 2. Update the [README.md](/README.md) with details of changes to the interface, this includes new environment variables, exposed ports, useful file locations and container parameters.
-3. Increase the version numbers in any examples files and the [README.md](/README.md) to the new version that this Pull Request would represent. The versioning scheme we use is [SemVer](http://semver.org/).
+3. Increase the version number in [package.json](/package.json) to the new version that this Pull Request would represent and document the change in [CHANGELOG.md](/CHANGELOG.md). The versioning scheme we use is [SemVer](http://semver.org/).
 4. You may merge the Pull Request in once you have the sign-off of two other developers, or if you do not have permission to do that, you may request the second reviewer to merge it for you.
 
 ## Code of Conduct
 
-### Our Pledge
-
-In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience nationality, personal appearance, race, religion, or sexual identity and orientation.
-
-### Our Standards
-
-Examples of behavior that contributes to creating a positive environment include:
-
-- Using welcoming and inclusive language
-- Being respectful of differing viewpoints and experiences
-- Gracefully accepting constructive criticism
-- Focusing on what is best for the community
-- Showing empathy towards other community members
-
-Examples of unacceptable behavior by participants include:
-
-- The use of sexualized language or imagery and unwelcome sexual attention or advances
-- Trolling, insulting/derogatory comments, and personal or political attacks
-- Public or private harassment
-- Publishing others' private information, such as a physical or electronic address, without explicit permission
-- Other conduct which could reasonably be considered inappropriate in a professional setting
-
-### Our Responsibilities
-
-Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
-
-Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
-
-### Scope
-
-This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
-
-### Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
-
-Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
-
-### Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.4, available at [http://contributor-covenant.org/version/1/4](http://contributor-covenant.org/version/1/4/)
+This project adheres to the [Contributor Covenant](https://www.contributor-covenant.org) Code of Conduct. By participating, you are expected to follow it in all your interactions with the project. Please read the full text in [CODE_OF_CONDUCT.md](/CODE_OF_CONDUCT.md), which also documents how to report unacceptable behaviour.

README.md

@@ -1,12 +1,12 @@
-# eFP-Seq-Browser
+# eFP-Seq Browser
 
 The eFP-Seq Browser is an RNA-Seq data exploration tool that shows read map coverage of a gene of interest along with an "electronic fluorescent pictographic" (eFP) image. This web-tool also allows the generation of new datasets if provided with SAM/BAM (with their index files) to allow visualization of any RNA-Seq mapping coverage. Gene expression levels and the similarity is also shown by calculating the Reads per Kilobase per Million reads mapped (RPKM) expression levels and Point Biserial Correlation Coefficient (r<sub>pb</sub>) scores amongst its different splice variants.
 
 Official publication of the [eFP-Seq Browser](https://bar.utoronto.ca/eFP-Seq_Browser/) can be found at [https://doi.org/10.1111/tpj.14468](https://doi.org/10.1111/tpj.14468).
 
 [![Follow on Twitter](https://img.shields.io/twitter/follow/BAR_PlantBio?style=social)](https://twitter.com/BAR_PlantBio)
-[![GitHub repo size](https://img.shields.io/github/repo-size/BioAnalyticResource/eFP-Seq-Browser)](https://github.com/BioAnalyticResource/eFP-Seq-Browser)
-[![GitHub](https://img.shields.io/github/license/BioAnalyticResource/eFP-Seq-Browser)](https://github.com/BioAnalyticResource/eFP-Seq-Browser)
+[![GitHub repo size](https://img.shields.io/github/repo-size/BioAnalyticResource/eFP-Seq_Browser)](https://github.com/BioAnalyticResource/eFP-Seq_Browser)
+[![GitHub](https://img.shields.io/github/license/BioAnalyticResource/eFP-Seq_Browser)](https://github.com/BioAnalyticResource/eFP-Seq_Browser)
 [![Website](https://img.shields.io/website?url=https%3A%2F%2Fbar.utoronto.ca%2FeFP-Seq_Browser%2F)](https://bar.utoronto.ca/eFP-Seq_Browser/)
 
 ## Getting Started
@@ -24,18 +24,18 @@ It is recommended that you use the web version available at <https://bar.utoront
 Clone the repository with git by running the following command:
 
 ```bash
-git clone https://github.com/BioAnalyticResource/eFP-Seq-Browser.git
+git clone https://github.com/BioAnalyticResource/eFP-Seq_Browser.git
 ```
 
-You will need [Node.js](https://nodejs.org/en/) and [Python3](https://www.python.org/downloads/) installed on your system to run the eFP-Seq Browser locally.
+You will need [Node.js](https://nodejs.org/en/), [Python3](https://www.python.org/downloads/) and [R](https://www.r-project.org/) installed on your system to run the eFP-Seq Browser locally.
 
 To set-up and install the prerequisites, run the following commands:
 
 ```bash
 npm run install:all
 ```
 
-which will install all the necessary Node and Python dependencies for the eFP-Seq Browser.
+which will install all the necessary Node, Python and R dependencies for the eFP-Seq Browser.
 
 ## Running locally
 
@@ -64,9 +64,14 @@ To run and test the eFP-Seq Browser code, you can run the following command:
 npm run validate
 ```
 
-Which will run the following commands:
+Which will run the following commands in order:
 
 - Prettier to format the code (`npm run prettier`)
+- ESLint to lint and auto-fix the JavaScript (`npm run eslint`)
+- esbuild to minify the JavaScript and CSS (`npm run minify`)
+- markdownlint to lint the Markdown files (`npm run lint:markdown`)
+- Jest unit tests (`npm run test:jest`)
+- Playwright end-to-end tests in headless mode (`npm run test:playwright:headless`)
 
 ## Known issues
 

SECURITY.MD

@@ -2,7 +2,7 @@
 
 ## Supported Versions
 
-We are actively maintaining and developing on the latest build on the master branch but we are willing to address any issues found.
+We are actively maintaining and developing on the latest build on the main branch but we are willing to address any issues found.
 
 ## Reporting a Vulnerability
 

cgi-bin/Submission_page/XMLgenerator.js

@@ -301,7 +301,7 @@ function correct_ReadMapCount(class_name) {
 
 /**
  * Makes sure a number is an integer
- * @param {Number} input_string Float
+ * @param {String} input_string String containing a number
  * @return {Number} input_string - Integer
  */
 function only_ReadNum(input_string) {
@@ -806,7 +806,7 @@ function determine_svgname(from_svg) {
 /**
  * Determine hexcode based on svgname and its subunit
  * @param {String} which_svg svgname
- * @param {String} which_svg svg_subunit
+ * @param {String} svg_subunit svg subunit
  * @return {String} - hexcode
  * @TODO: Add hex colour for rosettePlusRoot, SenescentLeaf, ShootApexVegetative-Transition, YoungLeaf1-4, Other
  */

cgi-bin/core/custom.js

@@ -150,10 +150,10 @@ const exon_intron_scale =
 
 /**
  * Produces an intermediate HEX colour
- * @param {*} start_color
- * @param {*} end_color
- * @param {*} percent
- * @returns
+ * @param {String} start_color Starting hex colour
+ * @param {String} end_color Ending hex colour
+ * @param {Number} percent Fraction (0-1) of the way from start_color to end_color
+ * @returns {String} Interpolated hex colour (e.g. "#RRGGBB")
  */
 function generate_colour(start_color, end_color, percent) {
 	// strip the leading # if it's there
@@ -1554,7 +1554,7 @@ let moreDetails = 'Show More Details <i class="material-icons detailsIcon">arrow
 let lessDetails = 'Show Less Details <i class="material-icons detailsIcon">arrow_drop_up</i>';
 
 /**
- * Gets the BAM locator XML to create + populate the table. Leeps track of all RNA-Seq calls it will have to make.
+ * Gets the BAM locator XML to create + populate the table. Keeps track of all RNA-Seq calls it will have to make.
  * @param {String | Number} status Index call version
  */
 function populate_table(status) {
@@ -2544,9 +2544,8 @@ let datalist = [];
 let datalist_Title = {};
 
 /**
- * Creates a list of base64 strings that contains XML of user's private datasets
+ * Resets and asynchronously populates the module-level `datalist` with the base64 XML strings of the user's private datasets, then triggers `DatalistXHRCall`.
  * @param {Number} size - How many private datasets the user has
- * @return {List} datalist_Title - Dictionary of base64 strings
  */
 function create_data_list(size) {
 	datalist = []; // Reset
@@ -2966,8 +2965,7 @@ function hideWarning_index(whichWarning) {
 }
 
 /**
- * Download selected file (in document's/index.html "Manage data") as an XML
- * @return {File} XML - Download selected file as an XML
+ * Triggers a browser download of the selected file (in the index.html "Manage data" view) as an XML file.
  */
 function manage_DownloadXML() {
 	const numberOfOptions = title_list.length + 2;
@@ -3153,8 +3151,7 @@ function download_XMLtableCSV() {
 const downloadIndexTable_base =
 	"\t\t<tr>\n\t\t\t<th>Title</th>\n\t\t\t<th>Record Number</th>\n\t\t\t<th>Tissue</th>\n\t\t\t<th>Tissue subunit</th>\n\t\t\t<th>Locus</th>\n\t\t\t<th>bp Length</th>\n\t\t\t<th>bp Start site</th>\n\t\t\t<th>bp End site</th>\n\t\t\t<th>Total number of reads</th>\n\t\t\t<th>Reads mapped to locus</th>\n\t\t\t<th>rpb</th>\n\t\t\t<th>RPKM</th>\n\t\t\t<th>Controls</th>\n\t\t</tr>\n";
 /**
- * Converts and downloads index's (document) main table as an CSV
- * @return {File} CSV
+ * Converts the index's main table to CSV and triggers a browser download via `tableToCSV()`.
  */
 function download_mainTableCSV() {
 	document.getElementById("download_icon").classList.add("progressLoading");

cgi-bin/gDriveMountFast.pl

@@ -1,10 +1,11 @@
 #!/usr/bin/perl
 ################################################################################
-# This program mount the Google Drive file system and run Sam Tools.
+# This program mounts a Google Drive folder as a FUSE file system so its BAM files
+# can be read remotely (e.g. by samtools/bcftools in rnaSeqMapCoverage.cgi).
 # Author: Asher
 # Date: November, 2016
-# Notice: Add Google API key before running
-# To Start: perl gDriveMountFast.pl <google share folder id> <timestamp>
+# Notice: The Google API key is configured in gDriveFast.pm
+# To Start: perl gDriveMountFast.pl <google share folder id> <timestamp> <bam filename>
 # To Stop: fusermount -u /mnt/gDrive/<folderid>_<timestamp> && rmdir mnt/gDrive/<folderid>_<timestamp>
 ################################################################################
 use warnings;
@@ -82,7 +83,7 @@ sub e_open {
     return (0, $fh);
 }
 
-# This is used by samtools mpileup program
+# FUSE read callback, invoked when a program (e.g. samtools/bcftools) reads the mounted file
 sub e_read {
 	# return an error numeric, or binary/text string.  (note: 0 means EOF, "0" will
 	# give a byte (ascii "0") to the reading program)

cgi-bin/get_gene_structures.cgi

@@ -6,7 +6,7 @@ import urllib.request
 from PIL import Image, ImageDraw
 
 print("Access-Control-Allow-Origin: *")
-print("Content-Type: application/json\n")  # HTML is following
+print("Content-Type: application/json\n")  # JSON is following
 
 # ----- CONSTANTS -----
 EXON_IMG_WIDTH = 450

cgi-bin/rnaSeqMapCoverage.cgi

@@ -1,6 +1,8 @@
 #!/usr/bin/python3
 ################################################################################
-# This program return the base64 of the RNA-Seq mapping coverage image.
+# This program returns a JSON object describing the RNA-Seq mapping coverage for a
+# gene, including RPKM (absolute-fpkm), the point biserial correlation (r), reads
+# mapped, and the base64-encoded mapping coverage image (rnaseqbase64).
 #
 # Authors: Asher, Alexander and Priyank
 # Date: January 2016
@@ -135,7 +137,7 @@ def determineReadMapNumber(filedir, filename, readMappedNumber, remoteDrive, bam
         if flagstat is None:
             return "FAILED: determineReadMapNumber-flagstat NONE"
 
-        # Read pileup output
+        # Read flagstat output
         for read in flagstat.splitlines():
             read = str(read.decode("utf-8"))
             if ("mapped" in read) and (
@@ -173,7 +175,7 @@ def makeImage(
     x_bp_vals = []  # Holds nucleotide positions...
     y_reads_values = []  # Holds the valid mapped reads for the position...
 
-    # Call samtools and get mpileup
+    # Call bcftools and get mpileup
     region = chromosome + ":" + str(start) + "-" + str(end)
 
     # Set the environment
@@ -321,7 +323,7 @@ def dumpError(
     Keyword Arguments:
         locus {string} -- The AGI ID of the gene that the RNA-Seq map coverage is interpreting (default: {None})
         record {string} -- The SRA record of the BAM data being interpreted (default: {None})
-        base64img {string} -- The base64 version of the RNA-Seq map coverage image (default: {None})
+        my_base64img {string} -- The base64 version of the RNA-Seq map coverage image (default: {None})
         abs_fpkm {string, integer} -- The absolute FPKM/RPKM value (default: {None})
         r {string, integer} -- The r coefficient value (default: {None})
         totalReadsMapped {string, integer} -- The total number of reads mapped to the gene within the BAM file (default: {None})