Installation guidelines

Some of you may need additional guidelines for installing Panache, here is a complement to what is already in the ReadMe.

Run Panache as a Docker container

Make sure you are using your IP in nginx.conf if you wish to make Panache available to other people. "localhost" can be used if you only need it on your personal machine.

In rare cases an Invalid Host header error can show up when running the container and trying to access the web page. This can be bypassed by adding disableHostCheck: true in a vue.config.js file at the root (which tells npm wich port and IP to use, 0.0.0.0 being localhost). See an example below:

Serve Panache with production files

If you wish to use another web server directly with the production version of files instead, here are the steps to follow to create them:

npm install
npm install @vue/cli
npm run build             #Creates the production version files

The production files will be gathered into a new directory called dist, ready to be served.

You are likely to have problems with the paths to the different files in the newly created index.js, which may not have the right root for them. This is because the main path inferred by Vue by default may not match yours if it is in subfolders.

EDIT: This should be easily corrected by adding your desired root within the file vue.config.js, using publicPath. Check out Vue's docs for more details. Below is an exemple of vue.config.js:

module.exports = {
  publicPath : "/test/panache/",   // <-- The app will be served from the subfolder /test/panache/
  configureWebpack: {              // <-- General configuration properties for deployment
    devServer: {
      port: 8080,
      host: '0.0.0.0',
      disableHostCheck: true,
    }
  }
}

Former, deprecated workaround:

You may for example see /css and /js instead of css/ and js/. You may also want to modify this line --> {path:"/ ",name:"Panache",component:xe["default"]} <-- in js/app.{randomID}.js, replacing the root with the directory containing the files to serve. For example, if the subpath hosting the server is called 'bananache' you should write {path:"/bananache/",name:"Panache",component:xe["default"]} instead. Kudos to Philipp Bayer for finding this one. We are looking for ways to correct this behaviour induced by npm.

Use Panache with pre-loaded files

If your goal is to set an instance of Panache that runs with only one set of files, you can use a dedicated version which does not offer the possibility to upload files but works from pre-formatted files instead. Our Banana Genome Hub version works this way, and is based on the alternative bananaGenomeHub branch. Note: as of 1st September 2021 the main branch is ahead of bananaGenomeHub, new changes will be cascaded soon.

Here you'll wish...

1. To pre format your dataset into a json format
2. To preset the store according to these json

Pre-format the datasets

Unfortunately there is no script to pre-format your dataset, yet. We propose two alternatives: copy json from the console, or directly load it as dedicated files (might work better for big files).

A. Extract JSONs from the console

A quick and dirty solution for this however is simply to run the default version of Panache, upload the desired files, and have them printed back as JSON once they are added to the store (ie. once they are fully loaded, parsed and formated into something usable by Panache). If you wish to try it at home I would advise to add the following to the default version:

... within PavFileParser.vue:

1. Look for 'parseDataToJson(loadedFile)', which is the method for the event doing the parsing and sending the new object to the store.
2. Right before or after this.updatePavData(chromGroupedData) which will send the formated object to the store, you can extract the desired JSON
3. One way of doing so is by console.logging this object as a JSON with console.log(JSON.stringify(chromGroupedData));:

... within GffFileParser.vue, similarly:

1. Look for 'parseGffToAnnotationObjects: async function(gffFile)'
2. Right before or after this.updateAnnotationData(groupedAnnot) extract your JSON
3. You can write console.log(JSON.stringify(groupedAnnot));:

... then run Panache, upload both default files within the web app (Pav file, then gff file by clicking the + button to show additional upload options), copy-paste the JSONs from the console into actual files, and voilà!

DISCLAIMER: This solution may not work for biggest files, below is an alternative "unholy solution" proposed by Philipp Bayer that would directly download the JSON without having to print to the console:

B. Download JSONs by modifying the production files

I put this piece of code into the js/app.{randomID}.js directly around this.updatePavData(chromGroupedData) and this.updateAnnotationData(groupedAnnot) as indicated:

const jsonStr = JSON.stringify(c);
const filename='data.json';
let element = document.createElement('a');
element.setAttribute('href', 'data:text/plain;charset=utf-8,' + encodeURIComponent(jsonStr));
element.setAttribute('download', filename);
element.style.display = 'none';
document.body.appendChild(element);
element.click();
document.body.removeChild(element);

(or JSON.stringify(u) for the gene annotation) That makes a fake link and downloads the data directly. [...] Right-click and copy from the console would cause my Firefox to crash with a 100Mb json file. As a reminder, js/app.{randomID}.js is a file located in the dist folder after running npm run build. The script might have to be one one line.

Preset the store

Using the bananaGenomeHub branch as a basis, you will have to modify LocalFilter.vue with the information from your dataset in order to override the data sent to store when the app is mounted. You can follow the example made for the Banana Genome Hub as shown below:

Especially, you will want to use:

updateChromNames to replace the list of chromosome names,

updateSelectedChrom to target from this list the chromosome that should be displayed by default,

updateGenomesInDisplay to list the genome names in the same order they appeared within the original pangenome file

pavDataPromise and gffDataPromise to store your pre-formatted presence absence matrix and gff files, respectively.

Once everything is set, you can run your server with one of the two solution detailed earlier, and try your very own version of Panache. Please note that while actively supported, the bananaGenomeHub branch of Panache is not the main one and may be updated less frequently.

Moreover, feel free to raise any concern you may have while using Panache as it can help us improve this documentation for future users.