From d33971096d9f0fe3d6f4e2df34091f1842ae00a8 Mon Sep 17 00:00:00 2001 From: Colin Date: Thu, 27 Oct 2022 11:09:10 -0600 Subject: [PATCH] [update docs] Correct link to updated tutorial --- ...20_embedding_jbrowse_01_getting_started.md | 4 +- ...c2020_embedding_jbrowse_02_introduction.md | 4 +- ...cc2020_embedding_jbrowse_03_simple_site.md | 4 +- ...bcc2020_embedding_jbrowse_04_assemblies.md | 4 +- .../bcc2020_embedding_jbrowse_05_tracks.md | 4 +- ...2020_embedding_jbrowse_06_other_options.md | 2 +- ..._embedding_jbrowse_07_creating_the_view.md | 2 +- ...20_embedding_jbrowse_08_default_session.md | 2 +- .../bcc2020_embedding_jbrowse_09_reacting.md | 4 +- ...bcc2020_embedding_jbrowse_10_conclusion.md | 2 +- .../bcc2020_embedding_jbrowse_aliases.md | 4 +- website/docs/tutorials/config_cli.md | 182 +++++++++--------- website/docs/tutorials/config_gui.md | 31 +-- .../embed_linear_genome_view/03_assemblies.md | 46 ++--- .../embed_linear_genome_view/04_tracks.md | 10 +- .../05_other_options.md | 2 +- 16 files changed, 143 insertions(+), 164 deletions(-) diff --git a/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_01_getting_started.md b/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_01_getting_started.md index 92d3b7dfde..ffccdb0bce 100644 --- a/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_01_getting_started.md +++ b/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_01_getting_started.md @@ -4,10 +4,8 @@ title: Getting started --- :::danger Out of date - Please see the -[updated version of this tutorial](../../embed_linear_genome_view/01_introduction). - +[updated version of this tutorial](/docs/tutorials/embed_linear_genome_view/01_introduction) ::: ## Welcome! diff --git a/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_02_introduction.md b/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_02_introduction.md index e3333eed7e..7289f30a36 100644 --- a/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_02_introduction.md +++ b/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_02_introduction.md @@ -4,10 +4,8 @@ title: Introduction --- :::danger Out of date - Please see the -[updated version of this tutorial](../../embed_linear_genome_view/01_introduction). - +[updated version of this tutorial](/docs/tutorials/embed_linear_genome_view/01_introduction) ::: ## What is JBrowse 2 diff --git a/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_03_simple_site.md b/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_03_simple_site.md index f25288be9e..1724fe6f31 100644 --- a/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_03_simple_site.md +++ b/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_03_simple_site.md @@ -4,10 +4,8 @@ title: Beginnings of a simple site --- :::danger Out of date - Please see the -[updated version of this tutorial](../../embed_linear_genome_view/01_introduction). - +[updated version of this tutorial](/docs/tutorials/embed_linear_genome_view/01_introduction) ::: ## Create a simple web page diff --git a/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_04_assemblies.md b/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_04_assemblies.md index 4a14fb1416..1712c19089 100644 --- a/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_04_assemblies.md +++ b/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_04_assemblies.md @@ -4,10 +4,8 @@ title: About assemblies --- :::danger Out of date - Please see the -[updated version of this tutorial](../../embed_linear_genome_view/01_introduction). - +[updated version of this tutorial](/docs/tutorials/embed_linear_genome_view/01_introduction) ::: ## What is an assembly? diff --git a/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_05_tracks.md b/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_05_tracks.md index 38dd674c96..3e08d16db7 100644 --- a/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_05_tracks.md +++ b/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_05_tracks.md @@ -4,10 +4,8 @@ title: About tracks --- :::danger Out of date - Please see the -[updated version of this tutorial](../../embed_linear_genome_view/01_introduction). - +[updated version of this tutorial](/docs/tutorials/embed_linear_genome_view/01_introduction) ::: ## What is a track? diff --git a/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_06_other_options.md b/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_06_other_options.md index 4a9cac6ae2..b834f06365 100644 --- a/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_06_other_options.md +++ b/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_06_other_options.md @@ -6,7 +6,7 @@ title: Other options :::danger Out of date Please see the -[updated version of this tutorial](../../embed_linear_genome_view/01_introduction). +[updated version of this tutorial](/docs/tutorials/embed_linear_genome_view/01_introduction). ::: diff --git a/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_07_creating_the_view.md b/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_07_creating_the_view.md index bd05a8335e..7ec0fdddd7 100644 --- a/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_07_creating_the_view.md +++ b/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_07_creating_the_view.md @@ -6,7 +6,7 @@ title: Creating the view :::danger Out of date Please see the -[updated version of this tutorial](../../embed_linear_genome_view/01_introduction). +[updated version of this tutorial](/docs/tutorials/embed_linear_genome_view/01_introduction). ::: diff --git a/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_08_default_session.md b/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_08_default_session.md index 715ed77e15..fe0aac89ad 100644 --- a/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_08_default_session.md +++ b/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_08_default_session.md @@ -6,7 +6,7 @@ title: Creating a default session :::danger Out of date Please see the -[updated version of this tutorial](../../embed_linear_genome_view/01_introduction). +[updated version of this tutorial](/docs/tutorials/embed_linear_genome_view/01_introduction). ::: diff --git a/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_09_reacting.md b/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_09_reacting.md index c262ec0afc..dc9e523272 100644 --- a/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_09_reacting.md +++ b/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_09_reacting.md @@ -4,10 +4,8 @@ title: Reacting to the view --- :::danger Out of date - Please see the -[updated version of this tutorial](../../embed_linear_genome_view/01_introduction). - +[updated version of this tutorial](/docs/tutorials/embed_linear_genome_view/01_introduction). ::: You can not only control the view, you can react to it as well. By providing an diff --git a/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_10_conclusion.md b/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_10_conclusion.md index 6cb1db7da3..4036dbd301 100644 --- a/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_10_conclusion.md +++ b/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_10_conclusion.md @@ -6,7 +6,7 @@ title: Conclusion :::danger Out of date Please see the -[updated version of this tutorial](../../embed_linear_genome_view/01_introduction). +[updated version of this tutorial](/docs/tutorials/embed_linear_genome_view/01_introduction). ::: diff --git a/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_aliases.md b/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_aliases.md index 0a0a7d35c3..92d1a47395 100644 --- a/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_aliases.md +++ b/website/docs/archive/bcc2020_embedding/bcc2020_embedding_jbrowse_aliases.md @@ -4,10 +4,8 @@ title: GRCh38 Reference Name Aliases --- :::danger Out of date - Please see the -[updated version of this tutorial](../../embed_linear_genome_view/01_introduction). - +[updated version of this tutorial](/docs/tutorials/embed_linear_genome_view/01_introduction). ::: This should be the content of your "GRCh38.aliases.txt" file. diff --git a/website/docs/tutorials/config_cli.md b/website/docs/tutorials/config_cli.md index 3456e12670..ae1702cc1b 100644 --- a/website/docs/tutorials/config_cli.md +++ b/website/docs/tutorials/config_cli.md @@ -13,68 +13,49 @@ the JBrowse CLI. :::note You can also do this configuration with graphical configuration editing -interface built into JBrowse 2. See that guide [here](../config_gui). +interface built into JBrowse 2. See that guide [here](/docs/config_gui). ::: -:::info For admins -If you are an administrator configuring JBrowse on a webserver, you must add the -`--out` command followed by your target directory, e.g. `--out /var/www/html/jbrowse2` -to write each JBrowse CLI configuration command to the `config.json` in that target -directory for your webserver to read from. +:::info +If you are an administrator configuring JBrowse on a webserver, you can add +the `--out` command followed by your target directory, e.g. `--out /var/www/html/jbrowse2` to write each JBrowse CLI configuration command to the +`config.json` in that target directory for your webserver to read from. -See the FAQ for "[what web server do I need](../../faq#what-web-server-do-i-need-to-run-jbrowse-2)" for more information. ::: ## Pre-requisites -- Installed and created your JBrowse environment using the [quickstart CLI guide](../../quickstart_cli) +- Installed and created your JBrowse environment using the [quickstart CLI + guide](/docs/quickstart_cli) - Some bioinformatics tools: - - [Samtools](http://www.htslib.org/) installed e.g. `sudo apt install samtools` or `brew install samtools`, used for creating FASTA index and BAM/CRAM processing - - [Genometools](http://genometools.org/) installed e.g. `sudo apt install genometools` or `brew install genometools`, (further, `brew install brewsci` and `brew install bio`) used for sorting GFF3 for creating tabix GFF - - [tabix](http://www.htslib.org/doc/tabix.html) installed e.g. `sudo apt intall tabix` and `brew install htslib`, used for creating tabix indexes for BED/VCF/GFF files - -## Adding a genome assembly - -First we will configure an assembly, or reference genome, for for JBrowse 2. -This usually means providing a file that describes the reference sequence for -the organism, such as a FASTA or 2BIT file. - -You can add a reference to a remote file as follows, -this example uses an assembly for a simulated organism -_volvox mythicus_: - -```bash -## Make sure you are in the directory where you have downloaded JBrowse 2 -jbrowse add-assembly http://jbrowse.org.s3.amazonaws.com/genomes/volvox/volvox.fa -``` - -`add-assembly` will automatically create a `config.json` file in the present directory (if `--out` is not specified) and populate it with the assembly, in this example, "volvox". + - [Samtools](http://www.htslib.org/) installed e.g. `sudo apt install samtools` or `brew install samtools`, used for creating FASTA index and + BAM/CRAM processing + - [Genometools](http://genometools.org/) installed e.g. `sudo apt install genometools` or `brew install genometools`, (further, `brew install brewsci` and `brew install bio`) used for sorting GFF3 for creating tabix + GFF + - [tabix](http://www.htslib.org/doc/tabix.html) installed e.g. `sudo apt intall tabix` and `brew install htslib`, used for creating tabix indexes + for BED/VCF/GFF files ### Loading a local FASTA file -To use your own local data (in the following, replace "genome.fa" with your FASTA file), you'll have to first create an index with samtools, then add it to the `config.json` using a local reference: +To use your own local data (in the following, replace "genome.fa" with your +FASTA file), you'll have to first create an index with samtools, then add it to +the `config.json` using a local reference: ```bash ## Create an indexed (.fai) FASTA file using samtools samtools faidx genome.fa ## Then, load it using the add-assembly command ## and add your genome assembly to the config -jbrowse add-assembly genome.fa --load copy +jbrowse add-assembly genome.fa --load copy --out /var/www/html/jbrowse ``` -:::info Note -Using `add-assembly` with a FASTA file assumes its index file is `.fai`. If you have an index file with a difference extension, you can manually specify it using the `--index` flag. - -You can run `jbrowse add-assembly --help` to get a list of all the options. -::: +JBrowse 2 also supports other assembly file formats, including bgzip-compressed +indexed FASTA, and 2bit files. See [configuring +assemblies](/docs/config_guide#assembly-config) for more info on formats +supported for the sequence file. -JBrowse 2 also supports other assembly file formats, such as bgzip-compressed -indexed FASTA (e.g. `.fa.gz`, `.fa.gz.fai`, and `.fa.gz.gzi` files) and 2BIT -files. See [configuring assemblies](../../config_guide#assembly-config) for more info -on formats supported for the sequence file. - -If you have your JBrowse 2 -[running as described](../../quickstart_cli/#running-jbrowse-2) in the JBrowse web +If you have your JBrowse 2 [running as +described](/docs/quickstart_cli/#running-jbrowse-2) in the JBrowse web quickstart, you can refresh the page and an add a linear genome view. You will now see your config in the Assembly dropdown. @@ -82,20 +63,25 @@ now see your config in the Assembly dropdown. ## Adding a track -Now we will show you how to add an alignments track and a variant track to JBrowse 2. +Now we will show you how to add an alignments track and a variant track to +JBrowse 2. ### Adding an alignments track For this example we will use a BAM file to add an alignments track. -As with assemblies, you can add a track using local files or remote locations of your files. +As with assemblies, you can add a track using local files or remote locations +of your files. -This example uses the following [BAM](https://jbrowse.org.s3.amazonaws.com/genomes/volvox/volvox.bam) and -[BAM index](https://jbrowse.org.s3.amazonaws.com/genomes/volvox/volvox.bam.bai) files downloaded locally as `/data/volvox.bam` and `/data/volvox.bam.bai` respectively: +This example uses the following +[BAM](https://jbrowse.org.s3.amazonaws.com/genomes/volvox/volvox.bam) and [BAM +index](https://jbrowse.org.s3.amazonaws.com/genomes/volvox/volvox.bam.bai) +files downloaded locally as `/data/volvox.bam` and `/data/volvox.bam.bai` +respectively: ```bash ## Replace with the location of your BAM file -jbrowse add-track /data/volvox.bam --load copy +jbrowse add-track /data/volvox.bam --load copy --out /var/www/html/jbrowse ``` :::note @@ -105,14 +91,14 @@ If you're using your own local BAM file and need to generate an index, use samto ## Create an indexed BAM file using samtools samtools index file.bam ## Add the BAM and BAI files to the JBrowse config -jbrowse add-track file.bam --load copy +jbrowse add-track file.bam --load copy --out /var/www/html/jbrowse ``` ::: This will copy the BAM and BAM index into the JBrowse 2 directory and add a -track pointing at those files to the config file. To see more options adding the -track, such as specifying a name, run `jbrowse add-track --help`. +track pointing at those files to the config file. To see more options adding +the track, such as specifying a name, run `jbrowse add-track --help`. If you don't want to copy your BAM file, you can use `--move` to move the file into the JBrowse 2 directory or `--symlink` to add a symlink to the file to the @@ -121,8 +107,8 @@ JBrowse 2 directory. If you want more control over the location, you can use option because on a traditional server you will need to ensure that the file is in a place where the web server is serving it. -If you have your JBrowse 2 -[running as described](../../quickstart_cli/#running-jbrowse-2) in the JBrowse web +If you have your JBrowse 2 [running as +described](../../quickstart_cli/#running-jbrowse-2) in the JBrowse web quickstart, you can refresh the page and an add a linear genome view of the volvox assembly. Then open track selector, and you will see the alignments track. @@ -134,15 +120,16 @@ track. Adding a variant track is similar to adding an alignments track. For this example, we will use a VCF file for the track. JBrowse 2 expects VCFs to be compressed with `bgzip` and indexed. Similar to the above example, we will -assume the files are at `/data/volvox.vcf.gz` and `/data/volvox.vcf.gz.tbi`. You -can download these file here: +assume the files are at `/data/volvox.vcf.gz` and `/data/volvox.vcf.gz.tbi`. +You can download these file here: [VCF](https://jbrowse.org.s3.amazonaws.com/genomes/volvox/volvox.vcf.gz) and -[VCF index](https://jbrowse.org.s3.amazonaws.com/genomes/volvox/volvox.vcf.gz.tbi). +[VCF +index](https://jbrowse.org.s3.amazonaws.com/genomes/volvox/volvox.vcf.gz.tbi). To add the track, run ```bash -jbrowse add-track /data/volvox.vcf.gz --load copy +jbrowse add-track /data/volvox.vcf.gz --load copy --out /var/www/html/jbrowse ``` :::note @@ -193,13 +180,13 @@ Make use of this [example file](https://jbrowse.org.s3.amazonaws.com/genomes/vol ```bash ## Download bigwig or bigbed file -jbrowse add-track volvox-sorted.bam.coverage.bw --load copy +jbrowse add-track volvox-sorted.bam.coverage.bw --load copy --out /var/www/html/jbrowse ``` ### Adding a GFF3 file with GFF3Tabix -To load a GFF3 file, we can sort and index it with tabix, make sure you have [GenomeTools](http://genometools.org/) (to -install can use `sudo apt install genometools`). +To load a GFF3 file, we can sort and index it with tabix, make sure you have +[GenomeTools](http://genometools.org/) (to install can use `sudo apt install genometools`). ```bash gt gff3 -sortlines -tidy -retainids yourfile.gff > yourfile.sorted.gff @@ -208,7 +195,8 @@ tabix yourfile.sorted.gff.gz jbrowse add-track yourfile.sorted.gff.gz --load copy ``` -As an alternative to `gt gff3 -sortlines`, use `awk` and GNU `sort`, as follows: +As an alternative to `gt gff3 -sortlines`, use `awk` and GNU `sort`, as +follows: ```bash awk '$1 ~ /^#/ {print $0;next} {print $0 | "sort -t\"\t\" -k1,1 -k4,4n"}' file.gff > file.sorted.gff @@ -216,44 +204,46 @@ bgzip file.sorted.gff tabix file.sorted.gff.gz ``` -The `awk` command is inspired by the method in the [tabix documentation](http://www.htslib.org/doc/tabix.html), but avoids subshells and properly sets the -tab delimiter for GNU sort in case there are spaces in the GFF. +The `awk` command is inspired by the method in the [tabix +documentation](http://www.htslib.org/doc/tabix.html), but avoids subshells and +properly sets the tab delimiter for GNU sort in case there are spaces in the +GFF. ### Adding a synteny track -Loading synteny data makes use of all the previous functions we've used so far in this guide. +Loading synteny data makes use of all the previous functions we've used so far +in this guide. -Here, we make use of the [grape](https://s3.amazonaws.com/jbrowse.org/genomes/grape/Vvinifera_145_Genoscope.12X.fa.gz) and [peach](https://s3.amazonaws.com/jbrowse.org/genomes/peach/Ppersica_298_v2.0.fa.gz) genome assemblies, but replace with your own data if applicable. +Here, we make use of the +[grape](https://s3.amazonaws.com/jbrowse.org/genomes/grape/Vvinifera_145_Genoscope.12X.fa.gz) +and +[peach](https://s3.amazonaws.com/jbrowse.org/genomes/peach/Ppersica_298_v2.0.fa.gz) +genome assemblies, but replace with your own data if applicable. -Use [minimap2](https://github.com/lh3/minimap2) to create a PAF file from FASTA files: +Use [minimap2](https://github.com/lh3/minimap2) to create a PAF file from FASTA +files: ```bash ## Use minimap2 to create a PAF from your assemblies -minimap2 grape.fa.gz peach.fa.gz > peach_vs_grape.paf +minimap2 grape.fa peach.fa > peach_vs_grape.paf + ## add each assembly to jbrowse config ## the -n flag names the assemblies explicitly -jbrowse add-assembly grape.fa.gz --load copy -n grape -jbrowse add-assembly peach.fa.gz --load copy -n peach -``` - -As we did [previously](#adding-a-gff3-file-with-gff3tabix) with GFF3 files: - -```bash -## -a establishes an alias for an assembly -jbrowse add-track grape.sorted.gff.gz -a grape --load copy -jbrowse add-track peach.sorted.gff.gz -a peach --load copy +jbrowse add-assembly grape.fa --load copy -n grape --out /var/www/html/jbrowse +jbrowse add-assembly peach.fa --load copy -n peach --out /var/www/html/jbrowse ``` Next, we'll load the synteny "track" from the PAF file. **Order matters here for the `--assemblyNames` parameter:** -If minimap2 is run as `minimap2 grape.fa peach.fa`, then you need to load as `--assemblyNames peach,grape`. +If minimap2 is run as `minimap2 grape.fa peach.fa`, then you need to load as +`--assemblyNames peach,grape`. The order is reversed between the `minimap2` and `jbrowse` tools. ```bash -jbrowse add-track peach_vs_grape.paf --assemblyNames peach,grape --load copy +jbrowse add-track peach_vs_grape.paf --assemblyNames peach,grape --load copy --out /var/www/html/jbrowse ``` ## Indexing feature names for searching @@ -264,26 +254,26 @@ index" so that you can search by genes or other features by their name or ID. To do this we can use the `jbrowse text-index` command: ```bash -jbrowse text-index +jbrowse text-index --out /var/www/html/jbrowse ``` This will index relevant track types e.g. any track with Gff3TabixAdapter (gene names and IDs) or VcfTabixAdapter (e.g. variant IDs). The command will print out a progress bar for each track that it is indexing. -This will also update your `config.json` so that after it completes, you can type a -gene name into the "search box" in the linear genome view or other views and -quickly navigate to genes by gene name. +This will also update your `config.json` so that after it completes, you can +type a gene name into the "search box" in the linear genome view or other views +and quickly navigate to genes by gene name. -See the [text-index](../../cli#jbrowse-text-index) command docs for more info. Also -see the [FAQ entries for text searching](../../faq#text-searching) +See the [text-index](/docs/cli#jbrowse-text-index) command docs for more info. +Also see the [FAQ entries for text searching](../../faq#text-searching) ## Conclusion Now that you have JBrowse configured with an assembly and a couple of tracks, you can start customizing it further. Check out the rest of the docs for more -information, especially the [JBrowse CLI](../../cli) docs for more details on some of -the steps shown here. +information, especially the [JBrowse CLI](/docs/cli) docs for more details on +some of the steps shown here. ## Miscellaneous tips @@ -292,26 +282,28 @@ You can use `--subDir` to organize your data directory: ```bash mkdir my_bams ## Copies .bam and .bai files to my_bams folder -jbrowse add-track myfile.bam --subDir my_bams --load copy +jbrowse add-track myfile.bam --subDir my_bams --load copy --out /var/www/html/jbrowse ``` -If you are in a directory without a `config.json` file, you can add the `--out` paramter, and the -track or assembly will load into that `config.json` file, as follows: +You can upgrade your JBrowse release to the latest version with: ```bash -jbrowse add-track /path/to/my/file.bam --out /path/to/my/jbrowse2 --load copy +jbrowse upgrade ``` -Make sure to upgrade your JBrowse release often: +The above command downloads the latest jbrowse-web from github. + +To upgrade the CLI tools, you can re-run the install command ```bash -jbrowse upgrade +npm install -g @jbrowse/CLI ``` -If you have or desire multiple configs files, you can specify which one you'd like to add configuration options to: +You can use filenames that are different than config.json, and put them in +subfolders too ```bash ## The following adds an assembly to the alt_config.json file specified -## To run JBrowse using this alt_config.json, navigate to http://localhost/jbrowse2/?config=alt_config.json -jbrowse add-assembly mygenome.fa --out /path/to/my/jbrowse2/alt_config.json --load copy +## To run JBrowse using this alt_config.json, navigate to http://localhost/jbrowse2/?config=subfolder/alt_config.json +jbrowse add-assembly mygenome.fa --out /path/to/my/jbrowse2/subfolder/alt_config.json --load copy ``` diff --git a/website/docs/tutorials/config_gui.md b/website/docs/tutorials/config_gui.md index cf787a43f8..d854e75094 100644 --- a/website/docs/tutorials/config_gui.md +++ b/website/docs/tutorials/config_gui.md @@ -46,8 +46,8 @@ lets you: All of these changes will be written by the server to the JBrowse config file (usually `config.json`) located in the JBrowse instance. This is something that -can only be done while the `admin-server` is running, which again, is **only meant -to be temporary!** +can only be done while the `admin-server` is running, which again, is **only +meant to be temporary!** To start the `admin-server`, navigate into your JBrowse 2 directory and run: @@ -71,7 +71,8 @@ in your application:
-As an example, let's add the hg38 human reference genome to our JBrowse 2 application. +As an example, let's add the hg38 human reference genome to our JBrowse 2 +application. Press the "Add New Assembly" button, and enter the necessary information in the form: @@ -129,7 +130,8 @@ The following file formats are supported in core JBrowse 2: - 2bit - .hic (Hi-C contact matrix visualization) -Additional data formats can be supported via plugins; checkout the [plugin store](/plugin_store). +Additional data formats can be supported via plugins; checkout the [plugin +store](/plugin_store). For tabix files, TBI or CSI indexes are allowed. CSI or BAI is allowed for BAM. Only CRAI is allowed for CRAM. The index will be inferred for BAI or TBI files @@ -138,23 +140,22 @@ index file explicitly. ### Editing a track -First, open a Linear Genome View using the navigation bar -(`File > Add > Linear Genome View`), and click on the "Select Tracks" button. +First, open a Linear Genome View using the navigation bar (`File > Add > Linear Genome View`), and click on the "Select Tracks" button. The configuration settings are accessible by clicking on the ellipses by each track.
-Open the configuration editor for the track by clicking on the "Settings" button -shown above. You can use the configuration editor to live-edit any configurable -value for a given track. +Open the configuration editor for the track by clicking on the "Settings" +button shown above. You can use the configuration editor to live-edit any +configurable value for a given track. ## Setting a default session -It is also possible to use the graphical admin server to set the default session -of your JBrowse 2 instance. This is the session that will appear when JBrowse 2 -is first visited. To do so, open the form to set the default session +It is also possible to use the graphical admin server to set the default +session of your JBrowse 2 instance. This is the session that will appear when +JBrowse 2 is first visited. To do so, open the form to set the default session (`Admin > Set default session`):
@@ -165,9 +166,9 @@ select the currently open session, or any of your previously saved sessions. ## Additional resources There are a number of additional features for configuring JBrowse 2. Make sure -to refer to the [config guide](../../config_guide) for topics such as -[adding tracks](../../config_guide/#track-configurations) or -[adding an assembly with the CLI](../../config_guide/#adding-an-assembly-with-the-cli). +to refer to the [config guide](/docs/config_guide) for topics such as [adding +tracks](/docs/config_guide/#track-configurations) or [adding an assembly with +the CLI](/docs/config_guide/#adding-an-assembly-with-the-cli). ## Conclusion diff --git a/website/docs/tutorials/embed_linear_genome_view/03_assemblies.md b/website/docs/tutorials/embed_linear_genome_view/03_assemblies.md index f51fbbfcbf..4d40ddc5f6 100644 --- a/website/docs/tutorials/embed_linear_genome_view/03_assemblies.md +++ b/website/docs/tutorials/embed_linear_genome_view/03_assemblies.md @@ -6,11 +6,11 @@ title: About assemblies ## What is an assembly? An assembly in JBrowse 2 is a collection of information that describes the -organism you are working with, such as its name and its reference sequence. This -is what JBrowse 2 uses to set up the coordinate system for the genome browser -and keep tracks organized. In JBrowse Web, you are able to have multiple -assemblies on screen at the same time. JBrowse Linear Genome View, however, is -more focused and allows just one assembly. +organism you are working with, such as its name and its reference sequence. +This is what JBrowse 2 uses to set up the coordinate system for the genome +browser and keep tracks organized. In JBrowse Web, you are able to have +multiple assemblies on screen at the same time. JBrowse Linear Genome View, +however, is more focused and allows just one assembly. These are the options you can specify for an assembly: @@ -40,8 +40,8 @@ assembly. ### Installing JBrowse CLI The JBrowse 2 CLI is designed to set up a configuration file for JBrowse Web, -but since JBrowse Linear Genome View is based on the same code, we can use it to -generate what we need as well. +but since JBrowse Linear Genome View is based on the same code, we can use it +to generate what we need as well. The instructions for installing JBrowse CLI are on the "[Introduction](../01_introduction)" page. After installing, if you run the @@ -56,9 +56,7 @@ want to install it, you can also do all of the things we will do in this tutorial by replacing `jbrowse` in any commands with `npx @jbrowse/cli`. For example, to get the help output you would run -```sh -npx @jbrowse/cli --help -``` +`sh npx @jbrowse/cli --help ` Using this command will create a temporary copy of the JBrowse CLI that doesn't get installed. @@ -67,17 +65,17 @@ get installed. ### Gathering files -Let's use a human GRCh38 assembly as our example. First we need a sequence file. -We'll use this url: +Let's use a human GRCh38 assembly as our example. First we need a sequence +file. We'll use this url: https://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/fasta/GRCh38.fa.gz. -We also need to define some reference sequence name aliases so that any files we -want to use that use "chr1" instead of "1" will display correctly. There is an -alias file that we can use at +We also need to define some reference sequence name aliases so that any files +we want to use that use "chr1" instead of "1" will display correctly. There is +an alias file that we can use at http://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/GRCh38.aliases.txt. -This aliases file has on each line a name from the reference sequence and then a -tab-separated list of aliases for that name. +This aliases file has on each line a name from the reference sequence and then +a tab-separated list of aliases for that name. ### Running the `jbrowse` command @@ -91,12 +89,14 @@ There are a lot of options, and not all of them are things we need to worry about in this case. Now go ahead and run the below command, referring to the help to interpret the options as needed: -```sh -jbrowse add-assembly https://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/fasta/GRCh38.fa.gz --name GRCh38 --alias hg38 --refNameAliases http://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/GRCh38.aliases.txt --skipCheck -``` +````sh jbrowse add-assembly +https://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/fasta/GRCh38.fa.gz --name +GRCh38 --alias hg38 --refNameAliases +http://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/GRCh38.aliases.txt +--skipCheck ``` -This will create a file called "config.json". Go ahead and open that file up. In -it, you will see an entry called "assemblies". The first (and only) entry in +This will create a file called "config.json". Go ahead and open that file up. +In it, you will see an entry called "assemblies". The first (and only) entry in that list is our assembly. You can see the name, alias, sequence, and reference name aliases we specified in our command. If for some reason the index files were unusually named, you could change them in the "faiLocation" and @@ -137,7 +137,7 @@ export default { }, }, } -``` +```` Then add an import to your "index.html" adding this data: diff --git a/website/docs/tutorials/embed_linear_genome_view/04_tracks.md b/website/docs/tutorials/embed_linear_genome_view/04_tracks.md index 553fc05a2b..a2a453bbe0 100644 --- a/website/docs/tutorials/embed_linear_genome_view/04_tracks.md +++ b/website/docs/tutorials/embed_linear_genome_view/04_tracks.md @@ -6,9 +6,9 @@ title: About tracks ## What is a track? A track is the place to display your data files in JBrowse Linear Genome View. -For this tutorial we're going to add a gene track, an -[alignments track](../../../user_guide/#alignments-tracks), and a -[variants track](../../../user_guide/#variant-tracks). We're just going to use basic +For this tutorial we're going to add a gene track, an [alignments +track](/docs/user_guides/alignment_track), and a [variants +track](/docs/user_guides/variant_track). We're just going to use basic configuration, but check the links for the track types to see what kinds of things you can configure in them. @@ -45,8 +45,8 @@ jbrowse add-track https://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/alignments jbrowse add-track https://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/variants/ALL.wgs.shapeit2_integrated_snvindels_v2a.GRCh38.27022019.sites.vcf.gz --name "1000 Genomes Variant Calls" --category "1000 Genomes, Variants" --skipCheck ``` -Open "config.json" again and look at the tracks that were generated. You can see -that again, it has guessed index locations for you, which you can change if +Open "config.json" again and look at the tracks that were generated. You can +see that again, it has guessed index locations for you, which you can change if needed. Create a new file called "tracks.js" and copy the tracks array into it and have it be exported, like this: diff --git a/website/docs/tutorials/embed_linear_genome_view/05_other_options.md b/website/docs/tutorials/embed_linear_genome_view/05_other_options.md index 765f762074..0448f2caff 100644 --- a/website/docs/tutorials/embed_linear_genome_view/05_other_options.md +++ b/website/docs/tutorials/embed_linear_genome_view/05_other_options.md @@ -22,7 +22,7 @@ example, if you wanted to have the view open to chromosome 1 from position JBrowse 2 allows you to provide plugins to add new features or modify behavior. We won't get into them today, but you can read more about creating a plugin -[here](../../../developer_guide). +[here](/docs/developer_guide). ## defaultSession