diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000..1e60f17 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,18 @@ +{ + "features": { + "ghcr.io/julialang/devcontainer-features/julia:1": { + "channel": "lts" + } + }, + "customizations": { + "vscode": { + "extensions": [ + "julialang.language-julia", + "tamasfe.even-better-toml", + "eamodio.gitlens" + ] + } + }, + "onCreateCommand": "julia --project=docs -e 'using Pkg; Pkg.instantiate(); Pkg.precompile();'" +} + diff --git a/README.md b/README.md index a203775..526df56 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,14 @@ similar to [SciMLDocs](https://github.com/SciML/SciMLDocs) (see the production p The rendered BioJuliaDocs site, for testing purposes, is published online using GitHub Pages at [biojulia.dev/BioJuliaDocs](https://biojulia.dev/BioJuliaDocs). A GitHub action rebuilds the site on every successful pull request. +To deploy the site locally: +```julia +# Make sure you are within or are pointing to the the docs/ folder +using Documenter, LiveServer +include("make.jl") +serve(dir="build") +``` + ## Contributing We appreciate contributions from users/members of the BioJulia commmunity diff --git a/docs/Project.toml b/docs/Project.toml index 6482e0d..2349c19 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -7,6 +7,7 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" DocumenterTools = "35a29f4d-8980-5a13-9543-d66fff28ecb8" FASTX = "c2308a5c-f048-11e8-3e8a-31650f418d12" FormatSpecimens = "3372ea36-2a1a-11e9-3eb7-996970b6ffbd" +GFF3 = "af1dc308-cb6b-11e8-32f0-31192efa90f6" GenomicFeatures = "899a7d2d-5c61-547b-bef9-6698a8d05446" Indexes = "4ffb77ac-cb80-11e8-1b35-4b78cc642f6d" IntervalTrees = "524e6230-43b7-53ae-be76-1e9e4d08d11b" diff --git a/docs/assets/JuliaVSCodeExtension.png b/docs/assets/JuliaVSCodeExtension.png new file mode 100644 index 0000000..15ab654 Binary files /dev/null and b/docs/assets/JuliaVSCodeExtension.png differ diff --git a/docs/make.jl b/docs/make.jl index 857d3e7..84cf6a2 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -17,13 +17,14 @@ makedocs( "getting_started/juliainstallation.md", "getting_started/toolsinstallation.md", "getting_started/biojuliainstallation.md", + "getting_started/casescenarios.md", ], "Comparison With Other Packages/Ecosystems" => [ "comparisons/biopython.md", "comparisons/scikitbio.md", "comparisons/bioconductor.md", - "comparisons/bioperl.md", "comparisons/biojava.md", + "comparisons/bioperl.md", "comparisons/bioruby.md", ], ], diff --git a/docs/src/comparisons/bioconductor.md b/docs/src/comparisons/bioconductor.md index 9ae1a89..e2e3230 100644 --- a/docs/src/comparisons/bioconductor.md +++ b/docs/src/comparisons/bioconductor.md @@ -2,9 +2,10 @@ - [Bioconductor](https://www.bioconductor.org/) represents an ecosystem of related genomics tools written in the R programming language - Tools written in other languages, such as C and Python, are also included with R wrappers available -- Initially released over two decades ago, it now hosts over 2000 packages for bioinformatics and related fields +- Launched over two decades ago, it now hosts over 2000 packages for bioinformatics and related fields - Packages cover a broard range of methods for the analysis and manipulation of genomic data +**A few equivalent applications between BioJulia and Bioconductor:** | Application | BioJulia packages | Bioconductor packages | |:--------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------| @@ -25,18 +26,16 @@ | Numerical mathematics | [LinearAlgebra](https://docs.julialang.org/en/v1/stdlib/LinearAlgebra/), [IterativeSolvers](https://iterativesolvers.julialinearalgebra.org/dev/) | `Matrix`, `pracma`, `deSolve` | | Web applications | [Genie](https://genieframework.com/), [Franklin](https://franklinjl.org/) | `shiny` | - **A few notable differences between Julia and R:** | Julia | R | |:-----------------------------------------------------------------------|:---------------------------------------------------------------------------------| | High-level, general-purpose compiled language | High-level, interpreted language for statistical computing | | Dynamically typed with multiple dispatch and optional type annotations | Dynamically typed without type annotations support | -| Built-in parallelism via threads, coroutines (Tasks) | Parallelism via external libraries (BLAS, parallel,...) | +| Built-in parallelism via threads, coroutines (Tasks) | Parallelism via external libraries (BLAS, `parallel`,...) | | Extensive metaprogramming (Lisp-like macros, generated functions,...) | Less extensive metaprogramming (function factories, expression manipulation,...) | | Single implementation available (JuliaLang) | Multiple implementations available (pqR, Renjin,...) | - **To transition from R to Julia:** - See [Noteworthy differences from R](https://docs.julialang.org/en/v1/manual/noteworthy-differences/#Noteworthy-differences-from-R) in the Julia manual for a more in-depth comparison - Use [RCall.jl](https://github.com/JuliaInterop/RCall.jl.git) to seamlessly integrate R code into your Julia project diff --git a/docs/src/comparisons/biojava.md b/docs/src/comparisons/biojava.md index b22c570..d552582 100644 --- a/docs/src/comparisons/biojava.md +++ b/docs/src/comparisons/biojava.md @@ -1 +1,41 @@ # [BioJava (Java)](@id biojava) + +- [BioJava](https://biojava.org/index.html) is a biological data processing library written in the Java programming language +- BioJava tooling is distributed via multiple classes within the same `org.biojava` package +- Launched in 2002 with six major releases covering more than 11 Java releases + +**A few equivalent applications between BioJulia and BioJava:** + +| Application | BioJulia packages | BioJava modules | +|:--------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------| +| Input/Output | [FASTX](https://biojulia.dev/FASTX.jl/stable/), [XAM](https://biojulia.dev/XAM.jl/stable/), [BigWig](https://biojulia.dev/BigWig.jl/dev/),... | `nbio.genome.io.fastq`, `nbio.ontology.obo`,... | +| Sequence alignment | [BioSequences](https://biojulia.dev/BioSequences.jl/stable/), [BioAlignments](https://biojulia.dev/BioAlignments.jl/stable/) | `nbio.sequence`, `nbio.alignment` | +| Macromolecular structures | [BioStructures](https://biojulia.dev/BioStructures.jl/stable/) | `nbio.structure` | + +**A few package/ecosystem equivalents between Julia and Java:** + +| Application | Julia | Java | +|:---------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------| +| Data manipulation/analysis | [DataFrames](https://dataframes.juliadata.org/stable/), [CSV](https://csv.juliadata.org/stable/), [Query](https://www.queryverse.org/Query.jl/stable/) | `Tablesaw` | +| Plotting/visualization | [Plots](https://docs.juliaplots.org/stable/), [Makie](https://docs.makie.org/stable/) | `JFreeChart`, `Jzy3d` | +| Statistical analysis | [Statistics](https://docs.julialang.org/en/v1/stdlib/Statistics/), [HypothesisTests](https://github.com/JuliaStats/HypothesisTests.jl) | `Statistics (Apache Commons)`, `NM Dev` | +| Machine learning | [Flux](https://fluxml.ai/Flux.jl/stable/), [SciML](https://sciml.ai/) | `Java-ML`, `Neuroph` | +| Numerical mathematics | [LinearAlgebra](https://docs.julialang.org/en/v1/stdlib/LinearAlgebra/) | `NM Dev` | +| Notebook/report generator | [IJulia](https://julialang.github.io/IJulia.jl/stable/), [Pluto](https://plutojl.org/) | `IJava` | +| Web applications | [Genie](https://genieframework.com/), [Franklin](https://franklinjl.org/) | `Grails`, `Javalin` | + +**A few notable differences between Julia and Java:** + +| Julia | Java | +|:-----------------------------------------------------------------------|:-----------------------------------------------------------------------------------------| +| High-level, general-purpose compiled language | High-level, object-oriented, two-step (compiled and interpreted) language | +| Expression-based (statements yield a value) | Statement-based (assignment as a statement) | +| Dynamically typed with multiple dispatch and optional type annotations | Statically typed with required type declarations | +| Built-in parallelism via threads, coroutines (Tasks) | Built-in parallelism via threads, streams, fibers (Project Loom) | +| Extensive metaprogramming (Lisp-like macros, homoiconicity,...) | Less extensive metaprogramming (reflection, annotations,...) | +| Included default package manager | No default package manager (dependency/build management tools include Maven, Gradle,...) | +| Single implementation available (JuliaLang) | Multiple implementations available (OpenJDK, GraalVM,...) | + +**To transition from Java to Julia:** +- Use [JavaCall.jl](https://juliainterop.github.io/JavaCall.jl/) to seamlessly integrate Java code into your Julia project +- See [Running External Programs](https://docs.julialang.org/en/v1/manual/running-external-programs/) in the Julia manual for running Java scripts or other programs from Julia \ No newline at end of file diff --git a/docs/src/comparisons/bioperl.md b/docs/src/comparisons/bioperl.md index 5aafe07..a118835 100644 --- a/docs/src/comparisons/bioperl.md +++ b/docs/src/comparisons/bioperl.md @@ -1 +1,39 @@ -# [BioPerl (Perl)](@id bioperl) +# [BioPerl (Perl5)](@id bioperl) + +- [BioPerl](https://bioperl.org/) represents an ecosystem of related molecular biology modules written in the Perl5 programming language +- Supported by the Open Bioinformatics Foundation and includes additional utilities and interfaces for common bioinformatics applications +- Launched in 2002 and has contributed to major scientific achievements including the Human Genome Project + +**A few equivalent application tools between BioJulia and BioPerl:** + +| Application | BioJulia packages | BioPerl modules/objects | +|:--------------------|:----------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------| +| Input/Output | [FASTX](https://biojulia.dev/FASTX.jl/stable/), [XAM](https://biojulia.dev/XAM.jl/stable/), [BigWig](https://biojulia.dev/BigWig.jl/dev/),... | `SeqIO` | +| Sequence alignment | [BioSequences](https://biojulia.dev/BioSequences.jl/stable/), [BioAlignments](https://biojulia.dev/BioAlignments.jl/stable/) | `AlignIO`, `SimpleAlign` | +| Data structures | [Kmers](https://biojulia.dev/Kmers.jl/stable/), [IntervalTrees](https://biojulia.dev/IntervalTrees.jl/stable/) | `Bio::Kmer`, `Bio::Tree` | +| Population Genetics | [PopGen](https://biojulia.dev/PopGen.jl/) | `PopGen` | + +**A few package/ecosystem equivalents between Julia and Perl5:** + +| Application | Julia | Perl5 | +|:---------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------| +| Data manipulation/analysis | [DataFrames](https://dataframes.juliadata.org/stable/), [CSV](https://csv.juliadata.org/stable/), [Query](https://www.queryverse.org/Query.jl/stable/) | `PDL`, `Text-CSV` | +| Plotting/visualization | [Plots](https://docs.juliaplots.org/stable/), [Gadfly](http://gadflyjl.org/stable/), [Makie](https://docs.makie.org/stable/) | `GDGraph`, `Chart-GGPlot` | +| Statistical analysis | [Statistics](https://docs.julialang.org/en/v1/stdlib/Statistics/), [HypothesisTests](https://github.com/JuliaStats/HypothesisTests.jl), [GLM](https://github.com/JuliaStats/GLM.jl) | `Statistics-Descriptive`, `PDL-Stats` | +| Numerical mathematics | [LinearAlgebra](https://docs.julialang.org/en/v1/stdlib/LinearAlgebra/), [Symbolics](https://symbolics.juliasymbolics.org/stable/) | `PDL-LinearAlgebra`, `Math-Symbolic` | +| Notebook/report generator | [IJulia](https://julialang.github.io/IJulia.jl/stable/), [Pluto](https://plutojl.org/) | `Devel-IPerl` | +| Web applications | [Genie](https://genieframework.com/), [Franklin](https://franklinjl.org/) | `Catalyst`, `Mojolicious` | + +**A few notable differences between Julia and Perl5:** + +| Julia | Perl5 | +|:-----------------------------------------------------------------------|:--------------------------------------------------------------------------------| +| High-level, general-purpose compiled language | High-level, general-purpose interpreted language | +| Dynamically typed with multiple dispatch and optional type annotations | Dynamically typed without type annotations support | +| Built-in parallelism via threads, coroutines (Tasks) | Parallelism via threads, external modules (`Coro`, `Parallel`,...) | +| Lisp-inspired metaprogramming (S-expressions, homoiconicity,...) | Macro-less metaprogramming capabilities (eval, symbol table manipulation,...) | +| Single language implementation (JuliaLang) | Family of related languages/implementations (Perl5, Perl6/Raku, ActivePerl,...) | + +**To transition from Perl5 to Julia:** +- Read the [Julia manual](https://docs.julialang.org/) for an in-depth look at its internals and features +- See [Running External Programs](https://docs.julialang.org/en/v1/manual/running-external-programs/) in the manual for running Perl scripts or other programs from Julia \ No newline at end of file diff --git a/docs/src/comparisons/biopython.md b/docs/src/comparisons/biopython.md index f15affa..c3e871e 100644 --- a/docs/src/comparisons/biopython.md +++ b/docs/src/comparisons/biopython.md @@ -1,10 +1,12 @@ # [Biopython (Python3)](@id biopython) - [Biopython](https://biopython.org/) represents an ecosystem of related biology tools written in the Python3 programming language -- Unlike in BioJulia, Biopython tools are installed together as modules into a single `biopython` package -- Initially released over two decades ago with major releases covering the Python2/3 transition +- Unlike with BioJulia, Biopython tools are installed together as modules into a single `biopython` package +- Launched over two decades ago with major releases covering the Python2/3 transition - Capabilities cover a number of molecular biology applications including sequence alignment, population genetics, and machine learning +**A few equivalent application tools between BioJulia and Biopython:** + | Application | BioJulia packages | Biopython objects/modules | |:--------------------|:----------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------| | Sequence annotation | [GenomicFeatures](https://biojulia.dev/GenomicFeatures.jl/stable/), [GenomicAnnotations](https://biojulia.dev/GenomicAnnotations.jl/dev/) | `Seq`, `SeqRecord` | @@ -24,19 +26,18 @@ | Notebook/report generator | [IJulia](https://julialang.github.io/IJulia.jl/stable/), [Pluto](https://plutojl.org/), [Weave](https://weavejl.mpastell.com/stable/) | `IPython`, `Jupyter Book` | | Web applications | [Genie](https://genieframework.com/), [Franklin](https://franklinjl.org/) | `Django`, `Flask`, `Pelican`, `Dash` | - **A few notable differences between Julia and Python3:** -| Julia | Python3 | -|:-----------------------------------------------------------------------|:-------------------------------------------------------------------------| -| High-level, general-purpose compiled language | High-level, general-purpose interpreted language | -| Expression-based (statements yield a value) | Statement-based (assignment as a statement) | -| Dynamically typed with multiple dispatch and optional type annotations | Dynamically typed with optional type annotations | -| Built-in parallelism via threads, coroutines (Tasks) | Limited (GIL) parallelism via threads, async/await | -| Extensive metaprogramming (Lisp-like macros, homoiconicity,...) | Less extensive metaprogramming (decorators, metaclasses,...) | -| Included default package manager | No default package manager (poetry, conda, other alternatives available) | -| Single implementation available (JuliaLang) | Multiple implementations available (PyPy, Numba,...) | -| Arrays are column-major (columns are contiguous in memory) | (Numpy) arrays are row-major by default (rows are contiguous in memory) | +| Julia | Python3 | +|:-----------------------------------------------------------------------|:-----------------------------------------------------------------------------| +| High-level, general-purpose compiled language | High-level, general-purpose interpreted language | +| Expression-based (statements yield a value) | Statement-based (assignment as a statement) | +| Dynamically typed with multiple dispatch and optional type annotations | Dynamically typed with optional type annotations | +| Built-in parallelism via threads, coroutines (Tasks) | Limited (GIL) built-in parallelism via threads, async/await | +| Extensive metaprogramming (Lisp-like macros, homoiconicity,...) | Less extensive metaprogramming (decorators, metaclasses,...) | +| Included default package manager | No default package manager (poetry, conda, and other alternatives available) | +| Single implementation available (JuliaLang) | Multiple implementations available (PyPy, Numba,...) | +| Arrays are column-major (columns are contiguous in memory) | (Numpy) arrays are row-major by default (rows are contiguous in memory) | **To transition from Python3 to Julia:** - See [Noteworthy differences from Python](https://docs.julialang.org/en/v1/manual/noteworthy-differences/#Noteworthy-differences-from-Python) in the Julia manual for a more in-depth comparison diff --git a/docs/src/comparisons/bioruby.md b/docs/src/comparisons/bioruby.md index 49a1ced..f231f89 100644 --- a/docs/src/comparisons/bioruby.md +++ b/docs/src/comparisons/bioruby.md @@ -1 +1,39 @@ # [BioRuby (Ruby)](@id bioruby) + +- [BioRuby](http://bioruby.org/) represents an ecosystem of related biology tools written in the Ruby programming language +- Unlike with BioJulia, BioRuby tools are installed together as classes/modules into a single `bio` gem +- Launched in 2000 with two major releases covering the Ruby1/2/3 transitions +- Primarily composed of wrapper classes/modules for common bioinformatics, molecular biology applications + +**A few equivalent application tools between BioJulia and BioRuby:** + +| Application | BioJulia packages | BioRuby classes/modules | +|:-------------------|:----------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------| +| Sequence alignment | [BioSequences](https://biojulia.dev/BioSequences.jl/stable/), [BioAlignments](https://biojulia.dev/BioAlignments.jl/stable/) | `Bio::Sequence`, `Bio::Alignment` | +| Input/Output | [FASTX](https://biojulia.dev/FASTX.jl/stable/), [XAM](https://biojulia.dev/XAM.jl/stable/), [BigWig](https://biojulia.dev/BigWig.jl/dev/),... | `Bio::Fasta`, `Bio::Fastq`,... | + +**A few package/ecosystem equivalents between Julia and Ruby:** + +| Application | Julia | Ruby | +|:---------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------| +| Data manipulation/analysis | [DataFrames](https://dataframes.juliadata.org/stable/), [CSV](https://csv.juliadata.org/stable/), [Query](https://www.queryverse.org/Query.jl/stable/) | `daru`, `CSV` | +| Plotting/visualization | [Plots](https://docs.juliaplots.org/stable/), [Makie](https://docs.makie.org/stable/) | `Chartkick`, `gruff` | +| Statistical analysis | [Statistics](https://docs.julialang.org/en/v1/stdlib/Statistics/), [HypothesisTests](https://github.com/JuliaStats/HypothesisTests.jl), [GLM](https://github.com/JuliaStats/GLM.jl), [Distributions](https://juliastats.org/Distributions.jl/latest/) | `Statsample`, `distribution` | +| Machine learning | [Flux](https://fluxml.ai/Flux.jl/stable/), [SciML](https://sciml.ai/) | `Rumale`, `TensorStream` | +| Numerical mathematics | [LinearAlgebra](https://docs.julialang.org/en/v1/stdlib/LinearAlgebra/) | `NMatrix`, `minimization`, `integration` | +| Notebook/report generator | [IJulia](https://julialang.github.io/IJulia.jl/stable/), [Pluto](https://plutojl.org/) | `IRuby` | +| Web applications | [Genie](https://genieframework.com/), [Franklin](https://franklinjl.org/) | `Hanami`, `Jekyll` | + +**A few notable differences between Julia and Ruby:** + +| Julia | Ruby | +|:-----------------------------------------------------------------------|:-------------------------------------------------------------------------------| +| High-level, general-purpose compiled language | High-level, general-purpose interpreted language | +| Dynamically typed with multiple dispatch and optional type annotations | Dynamically typed with optional type annotations (Sorbet, RBS) | +| Built-in parallelism via threads, coroutines (Tasks) | Built-in parallelism via threads, fibers | +| Lisp-inspired metaprogramming (S-expressions, homoiconicity,...) | Macro-less metaprogramming capabilities (dynamic reflection, eval methods,...) | +| Single implementation available (JuliaLang) | Multiple implementations available (TruffleRuby, mruby,...) | + +**To transition from Ruby to Julia:** +- Read the [Julia manual](https://docs.julialang.org/) for an in-depth look at its internals and features +- See [Running External Programs](https://docs.julialang.org/en/v1/manual/running-external-programs/) in the manual for running Ruby scripts or other programs from Julia \ No newline at end of file diff --git a/docs/src/comparisons/scikitbio.md b/docs/src/comparisons/scikitbio.md index 26b6d16..63ce8be 100644 --- a/docs/src/comparisons/scikitbio.md +++ b/docs/src/comparisons/scikitbio.md @@ -1 +1,43 @@ # [scikit-bio (Python3)](@id scikitbio) + +- [scikit-bio](http://scikit-bio.org/) represents a Python3 library providing data structures, algorithms, and additional bioinformatics resources +- Unlike with BioJulia, scikit-bio tools are installed together as modules into a single `skbio` package +- Launched in 2014 based on a BSD-relicensing of PyCogent and QIIME code and is currently in beta/maintenance mode + +**A few equivalent application tools between BioJulia and scikit-bio:** + +| Application | BioJulia packages | scikit-bio modules | +|:-------------------|:----------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------| +| Sequence alignment | [BioSequences](https://biojulia.dev/BioSequences.jl/stable/), [BioAlignments](https://biojulia.dev/BioAlignments.jl/stable/) | `skbio.sequence`, `skbio.alignment` | +| Input/Output | [FASTX](https://biojulia.dev/FASTX.jl/stable/), [XAM](https://biojulia.dev/XAM.jl/stable/), [BigWig](https://biojulia.dev/BigWig.jl/dev/),... | `skbio.io` | +| Data structures | [IntervalTrees](https://biojulia.dev/IntervalTrees.jl/stable/) | `skbio.tree` | + +**A few package/ecosystem equivalents between Julia and Python3:** + +| Application | Julia | Python3 | +|:---------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------| +| Data manipulation/analysis | [DataFrames](https://dataframes.juliadata.org/stable/), [CSV](https://csv.juliadata.org/stable/), [Query](https://www.queryverse.org/Query.jl/stable/) | `pandas`, `Blaze` | +| Plotting/visualization | [Plots](https://docs.juliaplots.org/stable/), [Gadfly](http://gadflyjl.org/stable/), [Makie](https://docs.makie.org/stable/) | `matplotlib`, `seaborn`, `bokeh`, `plotnine`, `VisPy` | +| Statistical analysis | [Statistics](https://docs.julialang.org/en/v1/stdlib/Statistics/), [HypothesisTests](https://github.com/JuliaStats/HypothesisTests.jl), [GLM](https://github.com/JuliaStats/GLM.jl) | `SciPy`, `statsmodels` | +| Machine learning | [Flux](https://fluxml.ai/Flux.jl/stable/), [SciML](https://sciml.ai/), [Zygote](https://fluxml.ai/Zygote.jl/stable/) | `PyTorch`, `TensorFlow`, `scikit-learn`, `JAX` | +| Numerical mathematics | [LinearAlgebra](https://docs.julialang.org/en/v1/stdlib/LinearAlgebra/), [Symbolics](https://symbolics.juliasymbolics.org/stable/) | `NumPy`, `SciPy`, `SymPy` | +| Notebook/report generator | [IJulia](https://julialang.github.io/IJulia.jl/stable/), [Pluto](https://plutojl.org/), [Weave](https://weavejl.mpastell.com/stable/) | `IPython`, `Jupyter Book` | +| Web applications | [Genie](https://genieframework.com/), [Franklin](https://franklinjl.org/) | `Django`, `Flask`, `Pelican`, `Dash` | + +**A few notable differences between Julia and Python3:** + +| Julia | Python3 | +|:-----------------------------------------------------------------------|:-----------------------------------------------------------------------------| +| High-level, general-purpose compiled language | High-level, general-purpose interpreted language | +| Expression-based (statements yield a value) | Statement-based (assignment as a statement) | +| Dynamically typed with multiple dispatch and optional type annotations | Dynamically typed with optional type annotations | +| Built-in parallelism via threads, coroutines (Tasks) | Limited (GIL) built-in parallelism via threads, async/await | +| Extensive metaprogramming (Lisp-like macros, homoiconicity,...) | Less extensive metaprogramming (decorators, metaclasses,...) | +| Included default package manager | No default package manager (poetry, conda, and other alternatives available) | +| Single implementation available (JuliaLang) | Multiple implementations available (PyPy, Numba,...) | +| Arrays are column-major (columns are contiguous in memory) | (Numpy) arrays are row-major by default (rows are contiguous in memory) | + +**To transition from Python3 to Julia:** +- See [Noteworthy differences from Python](https://docs.julialang.org/en/v1/manual/noteworthy-differences/#Noteworthy-differences-from-Python) in the Julia manual for a more in-depth comparison +- Use [PythonCall.jl](https://github.com/cjdoris/PythonCall.jl.git)/[CondaPkg.jl](CondaPkg.jl) to seamlessly integrate Python3 code into your Julia project +- Use [juliacall](https://pypi.org/project/juliacall/) to seamlessly integrate Julia code into your Python3 project \ No newline at end of file diff --git a/docs/src/getting_started/JuliaVSCodeExtension.png b/docs/src/getting_started/JuliaVSCodeExtension.png new file mode 100644 index 0000000..15ab654 Binary files /dev/null and b/docs/src/getting_started/JuliaVSCodeExtension.png differ diff --git a/docs/src/getting_started/biojuliainstallation.md b/docs/src/getting_started/biojuliainstallation.md index 6cc78ae..1ea4fe3 100644 --- a/docs/src/getting_started/biojuliainstallation.md +++ b/docs/src/getting_started/biojuliainstallation.md @@ -1 +1,85 @@ # [Installing BioJulia Packages](@id biojuliainstallation) + +## Standard installation + +As with any Julia package, you can easily install any BioJulia package with the help of the [official +package manager](https://pkgdocs.julialang.org/v1/) included by default with every Julia installation. +All you need to know is the name of the package of interest! + +There are two standard methods to install a package: + +1. **The package manager (Pkg) module** + +```julia +# You can exclude the semicolon, it is used here for suppressing output +using Pkg; +# Install the package +julia> Pkg.add(""); +# Use the installed package +using +``` + +!!! note + One excellent trick is that any Julia code with the `julia>` prompt included at the beginning of the + line can be copy/pasted as is into the REPL! See the [Julia REPL](@ref julia-repl) section for more. + +2. **Pkg mode** + +```julia +# Enter ] +] +# @v1.x will show your current Julia version +(@v1.9) pkg> add +# Exit REPL via the Backspace key +julia> using +``` + +!!! note + Just like with the previous method, you can copy/paste code with the `(@v1.x) pkg>` prompt included + and Julia will work correctly! You can even skip having to enter Pkg mode by just entering directly + `(@v1.x) pkg> add...`. You do not need to manually change the version number indicated in the + prompt if you have a different Julia version than that which is listed, it is again handled for you. + +## Package development + +If you are interested in developing a new or existing BioJulia/Julia package, the package manager can also +help you by first cloning the package repository to your development machine. Pkg will then load the required +dependencies in a new dependency environment based on the package's `Project.toml` file. Thereafter, both the +direct and indirect dependencies can be locked using a generated `Manifest.toml` if needed and a pull request +can be submitted. + +There are two standard methods to set up Julia for developing a package: + +1. **The package manager (Pkg) module** + +```julia +using Pkg; +julia> Pkg.develop(""); +using +``` + +1. **Pkg mode** + +```julia +# Enter ] +] +# If the package is within a remote Git repository, write instead +# `dev https://github.com//` +(@v1.9) pkg> dev +# Make sure you are within the same directory as the package folder +(@v1.9) pkg> activate /path/to/package/folder/PackageName +# The previous command activates the environment as directed by the +# package's Project.toml file. This next command will then download +# all of the dependencies specified in that file into your Julia environment. +(@v1.9) pkg> instantiate +# Exit REPL via the Backspace key +julia> using +``` + +!!! note + You can skip straight to `(@v1.9) pkg> activate ...` if you have already installed the package code locally, + simply make sure to point Pkg to the right path as shown above. + +You can now change your source code and load them into the Julia session with `using `. +To test your code, run `(@v1.9) pkg> test` to run the package's test suite to ensure that everything works +correctly. When you are done developing the package, enter `(@v1.9) pkg> free` to stop tracking the package. diff --git a/docs/src/getting_started/casescenarios.md b/docs/src/getting_started/casescenarios.md new file mode 100644 index 0000000..f3070e9 --- /dev/null +++ b/docs/src/getting_started/casescenarios.md @@ -0,0 +1,25 @@ +# [Case Scenarios](@id casescenarios) + +## Novel biotechnology startup solutions + + + +## Lab data processing, visualization, and analysis + + + +## Pharmaceutical drug design pipelines + + + +## Modeling and simulation of biological systems + + + +## Course teaching and lesson design + + + +## Research planning and development + + diff --git a/docs/src/getting_started/juliainstallation.md b/docs/src/getting_started/juliainstallation.md index dcb664f..2b09364 100644 --- a/docs/src/getting_started/juliainstallation.md +++ b/docs/src/getting_started/juliainstallation.md @@ -3,7 +3,7 @@ There are a number of methods available to install Julia that each have their own advantages: !!! note - Unix users: It is NOT recommended to install Julia from your distribution's package manager, as no such installation + It is NOT recommended to install Julia from your distribution's package manager, as no such installation is officially endorsed by the Julia project and thus may be out-of-date and broken/unmaintained! ## juliaup (recommended) @@ -12,20 +12,20 @@ There are a number of methods available to install Julia that each have their ow installation from the command-line. It is the easiest and most convenient installation option, and is available on almost all platforms that support Julia. -- If you are running Linux or Mac, enter the following command in your terminal: +- If you are running **Linux or Mac**, enter the following command in your terminal: ``` curl -fsSL https://install.julialang.org | sh ``` -- If you are running Windows, enter the following: +- If you are running **Windows**, enter the following: ``` winget install julia -s msstore ``` -- If you have the Rust programming language installed on your machine, you can install `juliaup` via the Cargo package manager: +- If you have the **Rust** programming language installed on your machine, you can install `juliaup` via the Cargo package manager: !!! warning - This is not a recommended option as this will involve compiling the actual `juliaup` executable on your local machine + This is not a recommended option as this will involve compiling the actual `juliaup` executable on your machine ``` cargo install juliaup @@ -105,4 +105,4 @@ Make sure to follow the exact installation steps for your machine in order to en For building/testing purposes, you may build Julia from the source code that is fully available in the [Julia GitHub repository](https://github.com/JuliaLang/julia.git). Simply enter `git clone https://github.com/JuliaLang/julia.git` to copy the entire source on your machine, create a new git branch via `git checkout -b name-of-branch`, -add your modifications, and run `make` to begin the Makefile build system. \ No newline at end of file +add your modifications, and run `make` to start the Makefile build. \ No newline at end of file diff --git a/docs/src/getting_started/toolsinstallation.md b/docs/src/getting_started/toolsinstallation.md index fd378cc..3719374 100644 --- a/docs/src/getting_started/toolsinstallation.md +++ b/docs/src/getting_started/toolsinstallation.md @@ -1 +1,110 @@ # [Installing Development Tools](@id toolsinstallation) + +## [Julia REPL](@id julia-repl) + +A REPL, or read-eval-print loop, represents a language "shell" or program that allows the user to communicate with the +programming language interactively with immediate feedback. This allows for exploring the language more deeply than via +a script, with rapid prototyping being much quicker and easier to perform. + +The Julia REPL is included by default in every Julia installation and boasts a number of features to the point that it +alone can almost be considered a proper IDE. It should appear the moment you enter `julia` into your terminal: + +``` + _ _ _(_)_ | Documentation: https://docs.julialang.org + (_) | (_) (_) | + _ _ _| |_ __ _ | Type "?" for help, "]?" for Pkg help. + | | | | | | |/ _` | | + | | |_| | | | (_| | | Version 1.9.2 (2023-07-05) + _/ |\__'_|_|_|\__'_| | Official https://julialang.org/ release +|__/ | + +julia> +``` + +We won't go into every feature that the REPL provides, however here is a quick list that most Julia users should +know to make the most of this shell: + +- There are 5 Julia REPL modes that serve separate purposes: + 1. The Julian (default) mode wherein one can write, load, and test out code + 2. Help mode for printing documentation for functions, keywords, etc. + 3. Pkg mode for working with the included package manager and manipulating dependencies/packages + 4. Shell mode to execute system commands (run a terminal from Julia which itself is running from a terminal!) + 5. Search modes (forward, reverse) to look through your history of inputs + +| Prompt | Key binding | +|:---------------------:|:---------------------------:| +| `julia> ` | None (default mode) | +| `help?> ` | `?` or `??` (extended help) | +| `(@v1.x) pkg> ` | `]` | +| `shell> ` | `;` | +| `(reverse-i-search):` | `^R` | +| `(forward-i-search):` | `^S` | + +- If you have a code editor installed on your development machine, you can go back and forth between the Julia session + and the editor by entering `julia> edit("")`. You can jump right back into the Julia session once you're + finished! +- You can get a list of matches to a partially written word by entering the TAB key, which also serves to render an + Unicode symbol in the REPL (full list available in the [Unicode Input](https://docs.julialang.org/en/v1/manual/unicode-input/) section of the Julia manual): + ```julia + julia> pri[TAB] + primitive type print println printstyled + julia> \pi[TAB] # renders π + ``` +- You can run a standalone script by entering `include("")` in Julian mode. For greater control, the + equivalent of Python3's `if __name__ == __main__` condition would be `if abspath() == @__FILE__` + +!!! warning + One common footgun with the Julia REPL is that there are currently certain code changes that cannot be performed without + restarting your session, such as redefining structs (see the example below). You can mitigate this by adding the + [Revise](https://timholy.github.io/Revise.jl/stable/) package, although restarting the session is the simplest option. + ```julia + julia> struct Point + x::Int + y::Int + end + + julia> struct Point + x::Int + z::Int + end + ERROR: invalid redefinition of constant Point + Stacktrace: + [1] top-level scope + @ REPL[2]:1 + ``` + +To learn more, see the [The Julia REPL](https://docs.julialang.org/en/v1/stdlib/REPL/) section in the Julia manual. + +## Visual Studio Code extension + +The Julia organization officially maintains the [Julia vscode extension](https://www.julia-vscode.org/), which provides +a complete IDE solution for developing in Julia. This boasts a number of advantages compared to a REPL solution: +- Built-in syntax highlighting and code completion +- GUI interaction for managing options and commands +- Advanced profiling/debugging features +- Additional extensions support + +To install vscode, follow the instructions on how to install the official binary for your development machine from the +[official website](https://code.visualstudio.com/). Next, click on the Extension icon in the side Activity Bar and search +for "Julia". The official Julia extension should be the first extension available. You can also install Julia within the +Quick Open input panel by pressing `Ctrl + P` and entering `ext install julialang.language-julia`. + + +![Julia VSCode Extension](JuliaVSCodeExtension.png) + + +Install the extension and restart vscode. We also recommend installing some additional extensions that will further improve +the development experience: +- [Even Better TOML](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml) + (`ext install tamasfe.even-better-toml`) for working with the package TOML + files (Project.toml, Manifest.toml, Artifacts.toml,...) +- [GitLens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens) (`ext install eamodio.gitlens`) for + enhancing Git workflows + + + +You can experiment with Julia extension features in the Quick Open panel by writing Julia and consulting the available +options. To learn more, visit the [Julia in Visual Studio Code](https://code.visualstudio.com/docs/languages/julia) page +in the official vscode docs. You can also visit the [Julia extension](https://www.julia-vscode.org/) website to learn more about +what features are available. +