diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index aac5f6b..d89f4ac 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -9,7 +9,8 @@ "extensions": [ "julialang.language-julia", "tamasfe.even-better-toml", - "eamodio.gitlens" + "eamodio.gitlens", + "stkb.rewrap", ] } }, diff --git a/docs/make.jl b/docs/make.jl index 72119e9..bb18c23 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -28,7 +28,7 @@ makedocs( ], ], # Showcase of Cool Examples - "What is BioJulia" => ["overview.md", + "What is BioJulia?" => ["overview.md", ] ] ) diff --git a/docs/src/assets/JuliaVSCodeExtension.png b/docs/src/assets/JuliaVSCodeExtension.png new file mode 100644 index 0000000..15ab654 Binary files /dev/null and b/docs/src/assets/JuliaVSCodeExtension.png differ diff --git a/docs/src/comparisons/bioconductor.md b/docs/src/comparisons/bioconductor.md index 4cac5df..44eba2e 100644 --- a/docs/src/comparisons/bioconductor.md +++ b/docs/src/comparisons/bioconductor.md @@ -1,9 +1,13 @@ # [Bioconductor (R)](@id bioconductor) -- [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 -- 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 +* [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 +* 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:** @@ -37,7 +41,15 @@ | 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 -- Use [JuliaCall](https://cran.r-project.org/web/packages/JuliaCall/readme/README.html) to seamlessly integrate Julia code into your R project -- Check out the [Tidier.jl ecosystem](https://tidierorg.github.io/Tidier.jl/dev/) for packages similar to those commonly found in `tidyverse` +* 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 +* Use + [JuliaCall](https://cran.r-project.org/web/packages/JuliaCall/readme/README.html) + to seamlessly integrate Julia code into your R project +* Check out the [Tidier.jl + ecosystem](https://tidierorg.github.io/Tidier.jl/dev/) for packages similar to + those commonly found in `tidyverse` + diff --git a/docs/src/comparisons/biojava.md b/docs/src/comparisons/biojava.md index 853aaa6..b6ba43e 100644 --- a/docs/src/comparisons/biojava.md +++ b/docs/src/comparisons/biojava.md @@ -1,8 +1,10 @@ # [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 +* [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:** @@ -37,6 +39,9 @@ | 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 +* 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 diff --git a/docs/src/comparisons/bioperl.md b/docs/src/comparisons/bioperl.md index a1c32c4..7826b1b 100644 --- a/docs/src/comparisons/bioperl.md +++ b/docs/src/comparisons/bioperl.md @@ -1,8 +1,11 @@ # [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 +* [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:** @@ -35,6 +38,9 @@ | 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 +* 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 diff --git a/docs/src/comparisons/biopython.md b/docs/src/comparisons/biopython.md index 9172595..218ac82 100644 --- a/docs/src/comparisons/biopython.md +++ b/docs/src/comparisons/biopython.md @@ -1,9 +1,13 @@ # [Biopython (Python3)](@id biopython) -- [Biopython](https://biopython.org/) represents an ecosystem of related biology tools written in the Python3 programming language -- 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 +* [Biopython](https://biopython.org/) represents an ecosystem of related biology + tools written in the Python3 programming language +* 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:** @@ -40,7 +44,12 @@ | 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](https://github.com/JuliaPy/CondaPkg.jl.git) 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 +* 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](https://github.com/JuliaPy/CondaPkg.jl.git) + 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 diff --git a/docs/src/comparisons/bioruby.md b/docs/src/comparisons/bioruby.md index a3fce1c..08bbcbe 100644 --- a/docs/src/comparisons/bioruby.md +++ b/docs/src/comparisons/bioruby.md @@ -1,9 +1,12 @@ # [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 +* [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:** @@ -35,6 +38,9 @@ | 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 +* 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 diff --git a/docs/src/comparisons/scikitbio.md b/docs/src/comparisons/scikitbio.md index f65aa28..7bfbef3 100644 --- a/docs/src/comparisons/scikitbio.md +++ b/docs/src/comparisons/scikitbio.md @@ -1,8 +1,11 @@ # [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 +* [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:** @@ -38,7 +41,12 @@ | 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](https://github.com/JuliaPy/CondaPkg.jl.git) 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 +* 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](https://github.com/JuliaPy/CondaPkg.jl.git) + 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 diff --git a/docs/src/getting_started/biojuliainstallation.md b/docs/src/getting_started/biojuliainstallation.md index 027fb74..0d33d9b 100644 --- a/docs/src/getting_started/biojuliainstallation.md +++ b/docs/src/getting_started/biojuliainstallation.md @@ -2,21 +2,26 @@ ## 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! +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: -!!! note - The Julia package manager, similarly to conda and others, organizes dependencies according to the "environment" - they are in, meaning in which directory the packages are installed to. The default Julia session adds packages - to a "global" environment, usually the .julia/environments/v1.x directory. When you are developing a package, - you must activate its project-specific environment by calling `activate MyProjectName` (see [Package development](@ref pkg-devel) - below) so that you can isolate your dependencies from the global environment and manage them independently. See - [Working with Environment](https://pkgdocs.julialang.org/v1/environments/) for more details. +!!! note + The Julia package manager, similarly to conda and others, organizes + dependencies according to the "environment" they are in, meaning in which + directory the packages are installed to. The default Julia session adds + packages to a "global" environment, usually the .julia/environments/v1.x + directory. When you are developing a package, you must activate its + project-specific environment by calling `activate MyProjectName` (see + [Package development](@ref pkg-devel) below) so that you can isolate your + dependencies from the global environment and manage them independently. See + [Working with Environment](https://pkgdocs.julialang.org/v1/environments/) + for more details. -- **The package manager (Pkg) module** +* **The package manager (Pkg) module** ```julia julia> using Pkg @@ -26,11 +31,12 @@ julia> Pkg.add("") julia> 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. +!!! 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. -- **Pkg mode** +* **Pkg mode** ```julia # Enter ] @@ -41,23 +47,26 @@ julia> using 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 all handled for you. +!!! note J + 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 all handled for you. ## [Package development](@id pkg-devel) -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. +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: -- **The package manager (Pkg) module** +* **The package manager (Pkg) module** ```julia julia> using Pkg @@ -65,7 +74,7 @@ julia> Pkg.develop("") julia> using ``` -- **Pkg mode** +* **Pkg mode** ```julia # Enter ] @@ -83,11 +92,14 @@ julia> using julia> using ``` -!!! note - You can skip straight to `(@v1.9) pkg> activate ...` if you have already installed the package locally, - simply make sure to point Pkg to the right path as shown above. +!!! note + You can skip straight to `(@v1.9) pkg> activate ...` if you have + already installed the package 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. +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 index 9adda88..fa9601e 100644 --- a/docs/src/getting_started/casescenarios.md +++ b/docs/src/getting_started/casescenarios.md @@ -1,115 +1,276 @@ # [Case Scenarios](@id casescenarios) -!!! note - These scenarios are based on practical workflows and real stories from fellow members of the BioJulia/Julia community! +!!! note + These scenarios are based on experiences and case studies from fellow + members of the BioJulia/Julia community! ## Industry !!! tip - Visit [JuliaHub](https://juliahub.com/case-studies/) for real-world case studies of Julia in multiple areas of industry! + Visit [JuliaHub](https://juliahub.com/case-studies/) for real-world case + studies of Julia in multiple areas of industry! -## App/Web Development +A biotechnology-oriented collaborative research organization has ordered their +IT department to organize the first in-house software development division. +Researchers and other essential personnel are divided into teams that each serve +one client at a time, though they all share the same laboratory and equipment. +The need for an in-house programming division has arisen based on feedback from +these teams facing many similar problems with the current workplace setup: + +* The researchers may not be digitally literate, thus they require more + accessible user experiences +* Lessening the number of tools they are required to learn would ideally reduce + complexity and onboarding time +* Some workflows can be repetitive and could take advantage of some automation + to reduce overall time -An analytics firm is interested in developing a new framework for creating interactive dashboards, the idea being that each -client can receive a real-time, custom view of their customer or product data. +It is thus decided that an employee-facing platform should be created that will +host a suite of simple, web-based software tools. These can include tools usable +by any employee or by only one or several teams depending on their needs. The +new division is given the following objectives: +* Collaborate with the researchers and understand their software requirements +* Use modern languages/frameworks to avoid technical headaches and allow for + faster onboarding +* Ensure access to both general and scientific libraries when needed for a + specific tool + +Upon reviewing these objectives, the division begins discussing which tech +stacks they should use. With a mix of veteran and junior talent, as well as a +desire to allow for fast time-to-deployment and performance, it is agreed that a +modern, higher-level programming language would be ideal. One of the +collaborating researchers suggests they look into Julia, which has been the +scripting language of choice amongst some of the teams for automating several +workflows, and the division gives it a go following some research and planning. + +The platform and first two tools for the collaborating researcher's team are +prototyped. The stack is built upon the [Genie](https://genieframework.com/) web +framework, which, crucially, enables authorization/authentication support on a +team-by-team basis and HTML/CSS/JS interoperability. The entire platform is +designed as a reactive app that can be deployed anywhere and is almost entirely +written in Julia for both the frontend and backend. Further Genie ecosystem +packages and plugins spur potential ideas like taking advantage of the included +no-code [UI builder](https://learn.genieframework.com/guides/genie-builder) for +producing analytics dashboards built by each team without advanced programming +expertise. + +The first tool conceived allows teams to upload, download, and manage files or +datasets within the company's shared drive from the web. It is designed to +handle data management on its own without the employees needing to remember +specific drive locations or other details, their only responsibility being +categorization (data pulled from which instrument, for which project, +etc.). The tool is able to manage the data by working with the company's S3 and +S3 Glacier storage instances via the +[AWS](https://juliacloud.github.io/AWS.jl/stable/) package. A user-facing +feature is also included that generates an `Artifacts.toml` file, allowing +researchers to use Julia's [Artifact +system](https://pkgdocs.julialang.org/v1/artifacts/) to declaratively point to +select data and download them when required for their local needs. For the more +tech savvy user, an input feature is set up to allow for +[DuckDB](https://duckdb.org/) database queries for large datasets. An [official +Julia package](https://duckdb.org/docs/api/julia.html) is provided for this +DBMS, however, one incredible feature of the language is the ability to bundle +external programs written in other languages and treat them as first-class Julia +packages, known as +[JLLs](https://docs.binarybuilder.org/stable/jll/#JLL-packages). The official +package wraps the `DuckDB_jll` bundle, which the developers can manage as a +separate dependency for more direct interaction with the DBMS. This feature, to +their delight, also means that porting over common, open scientific software for +more specific tools can be as simple as generating their JLLs and managing them +directly via Julia. Seamless interoperability also extends to the ability to +interact with codes from other languages such as Python with +[PythonCall](https://juliapy.github.io/PythonCall.jl/stable/)/[CondaPkg](https://github.com/JuliaPy/CondaPkg.jl) +and R with [RCall](https://juliainterop.github.io/RCall.jl/stable/). + +The second tool conceived is designed specifically for the collaborating +researcher who needs to determine total cell count following each cell passage. +The user uploads a photo of a stained cell culture sample, along with inputs +such as total medium volume and dilution factor. The developers make use of the +[ImageSegmentation](https://juliaimages.org/stable/pkgs/segmentation/#ImageSegmentation.jl) +package for differentiating live and dead cells through the use of the watershed +algorithm. A side-by-side view is generated with the original and segmented +image, as well as the total number of markers indicating the amount of live +cells, being differentiable due to their staining. Although only a prototype, +the developers believe it would be more than possible, thanks to the number of +large Julia packages already available, to employ basic machine learning to +simplify the process and increase accuracy. Aside from other imaging packages +like [ImageAxes](https://juliaimages.org/stable/pkgs/axes/#ImageAxes.jl), OpenCV +has already been ported over [as a +JLL](https://juliahub.com/ui/Packages/General/OpenCV_jll) for direct +development, and a host of packages are available within the +[SciML](https://sciml.ai/) ecosystem for building the machine learning model. + +The trial period with the collaborating researcher's team proves to be a +success, and the company decides to fully commit to this platform, almost fully +written in Julia, with additional resources and manpower. Novel ideas are +excitedly tossed about internally over which tools can further improve +workflows, such as replacing their electronic lab notebook systems with +[Pluto](https://plutojl.org/) and embedding a quick statistics calculator for +linear regression modelling with packages including +[GLM](https://juliastats.org/GLM.jl/stable/) and [Makie](https://makie.org/). It +is even discussed how Julia may allow the company to eventually commercialize +these tools for other contract research organizations that face the same +challenges. + ## Research -!!! tip - Visit [The Journal of Open Source Software](https://joss.theoj.org/) and [JuliaCon Proceedings](https://proceedings.juliacon.org/) to explore several research packages written in Julia! - -A freshly minted researcher begins the morning with a new directive from the principal investigator. Their lab specializes in -translational cancer immunotherapy, and as of late have been exploring a potential avenue for T-cell activation in patients with -with a rare type of lymphoma. It is hoped that strengthening the expression of specific peptides involved in cellular adaptive immune -response can lead to more effective treatment of this specific cancer. One patient's blood has been sampled and delivered to the lab, -with the goal of extacting and combing through the resulting expression data from various antigen-presenting cells (APCs) to identify abnormal -peptide expression levels. - -The researcher understands that the exploratory nature of this project will require an interactive environment from which results can be -rapidly generated and saved/discarded when need be. Previously, a number of challenges would get in the way of this workflow: - -- Working with interactive languages had proven to be a hassle due to issues like competing build systems and environments -- The REPL experience was often lacking due to missing features or lack of integrations with other tools like a package manager -- Notebooks, while good for experimenting, can come with their own problems such as slow speeds and difficulties with deployment and versioning -- Writing high-performing software would require lower-level languages like C or Fortran, which would prove difficult for scientists without a computer science background - -They remember previously experimenting with Julia while before it was stable, and decide to give it a second go. Installation proved to be very simple with the -[juliaup](https://github.com/JuliaLang/juliaup#installation) tool, and they proceed to read up on the basics from the [Julia manual](https://docs.julialang.org/en/v1/). -The first step, upon loading the Julia REPL, is to add the [DrWatson](https://juliadynamics.github.io/DrWatson.jl/stable/) package to better track -the project. With DrWatson and the built-in package manager, the researcher can geneate reproducible code for simulations, plotting, and -data preparation. - -At the same time, the researcher isolates the APCs via a microfluidic cell-sorting device. The patient's cells are encapsulated into individual -droplets from which single-cell profiling can occur via Droplet-Sequencing (Drop-seq). The resulting data is stored in [.h5 files](https://www.wikiwand.com/en/Hierarchical_Data_Format) on the lab's shared drive. The researcher generates an `Artifacts.toml` file that utilizes Julia's built-in package manager to point -to these files in a persistent and reproducible manner every time when the project needs to be shared with others on their own machines. The researcher makes -quick work of loading the data into Julia with the [HDF5](https://juliaio.github.io/HDF5.jl/stable/) package, and applies a number of steps with -[DataFrames](https://dataframes.juliadata.org/stable/), [TidierData](https://tidierorg.github.io/TidierData.jl/latest/), and [Chain](https://github.com/jkrumbiegel/Chain.jl) -to transform, normalize, and filter the data. Finally, principle component analysis (PCA) with [SingleCellProjections](https://biojulia.dev/SingleCellProjections.jl/stable/) -is conducted, visualized with a plotting package such as [Makie](https://makie.org/) or [PlotlyJS](http://juliaplots.org/PlotlyJS.jl/stable/). - -The whole project is saved by DrWatson and shared with the P.I. for further discussion. PCA analysis leads them to focus on a narrow subset of -APCs with elevated peptide expression levels which will be followed up in subsequent studies. The researcher prepares a more digestible format of the results -as a [Pluto notebook](https://plutojl.org/) to share with colleagues the more pertinent observations, and finally a more formal research report is written with -[Weave](https://weavejl.mpastell.com/stable/). The lab is impressed with what was achieved with Julia, with many remarking how effortless it seemed to achieve -excellent performance with such a high-level language. +!!! tip + Visit [The Journal of Open Source Software](https://joss.theoj.org/) and + [JuliaCon Proceedings](https://proceedings.juliacon.org/) to explore several + research packages written in Julia! + +A freshly minted researcher begins the morning with a new directive from the +principal investigator. Their lab specializes in translational cancer +immunotherapy, and as of late have been exploring a potential avenue for T-cell +activation in patients with with a rare type of lymphoma. It is hoped that +strengthening the expression of specific peptides involved in cellular adaptive +immune response can lead to more effective treatment of this specific cancer. +One patient's blood has been sampled and delivered to the lab, with the goal of +extacting and combing through the resulting expression data from various +antigen-presenting cells (APCs) to identify abnormal peptide expression levels. + +The researcher understands that the exploratory nature of this project will +require an interactive environment from which results can be rapidly generated +and saved/discarded when need be. Previously, a number of challenges would get +in the way of this workflow: + +* Working with interactive languages had proven to be a hassle due to issues + like competing build systems and environments +* The REPL experience was often lacking due to missing features or lack of + integrations with other tools like a package manager +* Notebooks, while good for experimenting, can come with their own problems such + as slow speeds and difficulties with deployment and versioning +* Writing high-performance software would require lower-level languages like C + or Fortran, which would prove difficult for scientists without a computer + science background + +They remember previously experimenting with Julia before it was considered +stable, and decide to give it a second go. Installation proved to be very simple +with the [juliaup](https://github.com/JuliaLang/juliaup#installation) tool, and +they proceed to read up on the basics from the [Julia +manual](https://docs.julialang.org/en/v1/). The first step, upon loading the +Julia REPL, is to add the +[DrWatson](https://juliadynamics.github.io/DrWatson.jl/stable/) package to +better track the project. With DrWatson and the built-in package manager, the +researcher can geneate reproducible code for simulations, plotting, and data +preparation. + +At the same time, the researcher isolates the APCs via a microfluidic +cell-sorting device. The patient's cells are encapsulated into individual +droplets from which single-cell profiling can occur via Droplet-Sequencing +(Drop-seq). The resulting data is stored in [.h5 +files](https://www.wikiwand.com/en/Hierarchical_Data_Format) on the lab's shared +drive. The researcher generates an `Artifacts.toml` file that utilizes Julia's +built-in [Artifact system](https://pkgdocs.julialang.org/v1/artifacts/) to point +to these files in a persistent and reproducible manner every time the project +needs to be shared with others on their own machines. The researcher makes quick +work of loading the data into Julia with the +[HDF5](https://juliaio.github.io/HDF5.jl/stable/) package, and applies a number +of steps with [DataFrames](https://dataframes.juliadata.org/stable/), +[TidierData](https://tidierorg.github.io/TidierData.jl/latest/), and +[Chain](https://github.com/jkrumbiegel/Chain.jl) to transform, normalize, and +filter the data. Finally, principle component analysis (PCA) with +[SingleCellProjections](https://biojulia.dev/SingleCellProjections.jl/stable/) +is conducted, visualized with the help of the [Makie](https://makie.org/) +plotting package. + +The whole project is saved by DrWatson and shared with the P. I. for further +discussion. PCA analysis leads them to focus on a narrow subset of APCs with +elevated peptide expression levels which will be followed up in subsequent +studies. The researcher prepares a more digestible format of the results as a +[Pluto notebook](https://plutojl.org/) to share with colleagues the more +pertinent observations, and finally a more formal research report with Julia +code included is written with [Weave](https://weavejl.mpastell.com/stable/). The +lab is impressed with what was achieved with Julia, with many remarking how +effortless it seemed to achieve excellent performance with such a high-level +language. ## Education -A new teacher was recently hired to teach a biostatistics course for first-year students at the University of Concordia. This will be -a new offering at the university, thus they have been given free reign to design their own course plan. They are most interested in -engaging students with a fun practical component, including assignments that are trivial to set up, easy for students to learn, -and that draw from real-world examples. They look for inspiration from similar courses, and finds that many are aiming to -develop a strong foundation in statistical programming for handling data analysis, hypothesis testing, and other tasks. - -A number of these courses teach R or Python3, which have been entrenched in statistics for a number of years. They also appear -to be popular with new programmers due to being high-level and easy to learn. However, the new teacher encounters -a number of issues that raise concern: - -- Performance would become an issue with larger datasets or visual plots, with the interpreter taking too long to generate output - and thus wasting valuable class time -- Both languages have been around for a long time, with a number of quirks and design decisions that have not aged well such as - implicit mutation or lack of type annotations -- Setting up reproducible environments with all the necessary bits (packages, data,...) in either language is challenging, with a - number of limitations and choices presented such as package manager, language implementation, etc. -- R is designed specifically for statistical computing, with concepts not found in other, more general languages (S3/S4 class system, - factors,...) which could confuse students with previous programming knowledge or those wishing to learn more common computer science - concepts -- There is a desire to avoid the "two-language problem" wherein parts of either language are written in another and thus introduce unneeded - complexity - -A fellow professor recommends that they look into Julia, which has found success within the department. Beyond addressing many -of the issues encountered with R and Python3, it is especially enjoyable how fast the performance is, how the default package manager -allows for reproducibility and ease of use, and how close to mathematical writing Julia can get whilst remaining readable. - -The first objective is to create a presentation format with good aesthetics that can also show off and run code. They discover how -to set up interactive notebooks with [Pluto](https://plutojl.org/) that will be hosted in a [central repository](https://github.com/) -or online via a website or with solutions like [Binder](https://mybinder.org/). This has a number of advantages compared to PowerPoint or -Markdown presentations: - -- Easily run and experiment with code cells within a reproducible environment -- Dependency management automatically handled via the built-in package manager -- Share the code and lessons with students either as notebooks or as exported PDF/HTML pages - -To bundle the datasets with the notebooks, they take advantage of Julia's [Artifact system](https://pkgdocs.julialang.org/v1/artifacts/) for -handling and retrieving data from almost anywhere on the Internet. - -With the course infrastructure set, attention is now put towards creating the actual course material. They can cover a number of biostatistics -topics using powerful, well-established Julia packages: - -- [Plots](https://docs.juliaplots.org/stable/) or [Makie](https://docs.makie.org/stable/) for data visualization -- [DataFrames](https://dataframes.juliadata.org/stable/), [CSV](https://csv.juliadata.org/stable/), and [Tidier](https://tidierorg.github.io/Tidier.jl/dev/) - for data handling -- [Statistics] and [StatsBase] for general statistical functionality (scalar statistics, estimation,...) -- [Distributions](https://juliastats.org/Distributions.jl/stable/) for probability and sampling -- [HypothesisTests](https://juliastats.org/HypothesisTests.jl/stable/) for parametric (ANOVA, chi-squared,...) and non-parametric testing -- [GLM](https://juliastats.org/GLM.jl/stable/) for generalized linear modelling -- [Flux](https://fluxml.ai/) or [MLJ](https://alan-turing-institute.github.io/MLJ.jl/stable/) for basic machine learning - -The course agenda is now almost complete. However, just before the start of the semester, a new lesson on Tukey's honest significance test is -added. Unfortunately, there is no package written in Julia for this test, and there is little time left to develop the code on their own. Luckily, -Julia posseses amazing interoperability with both Python3 and R, and they discover how to both call and bundle Scipy's `stats.tukey_hsd` function via -[PythonCall](https://cjdoris.github.io/PythonCall.jl/stable/) and [CondaPkg](https://github.com/cjdoris/CondaPkg.jl). Not only will the Python3 code -seamlessly integrate into the Julia notebook, but it will also handle conda packaging automatically! - -The teacher goes on to deliver one of the best courses that semester, empowered by Julia to deliver an engaging, interactive experience that teaches -students both the fundamentals of biostatistics and of quality programming. +A new teacher was recently hired to teach a biostatistics course for first-year +students at the University of Concordia. This will be a new offering at the +university, thus they have been given free reign to design their own course +plan. They are most interested in engaging students with a fun, practical +component, including assignments that are trivial to set up, easy for students +to learn, and that draw from real-world examples. They look for inspiration from +similar courses, and finds that many are aiming to develop a strong foundation +in statistical programming for handling data analysis, hypothesis testing, and +other tasks. + +A number of these courses teach R or Python3, which have been entrenched in +statistics for a number of years. They also appear to be popular with new +programmers due to being high-level and easy to learn. However, the new teacher +encounters a number of issues that raise concern: + +* Performance would become an issue with larger datasets or visual plots, with + the interpreter taking too long to generate output and thus wasting valuable + class time +* Both languages have been around for a long time, with a number of quirks and + design decisions that have not aged well such as implicit mutation or lack of + type annotations +* Setting up reproducible environments with all the necessary bits (packages, + data, ...) in either language is challenging, with a number of limitations and + choices presented including package manager, language implementation, etc. +* R is designed specifically for statistical computing, with concepts not found + in other, more general languages (S3/S4 class system, factors, ...) which + could confuse students with previous programming knowledge or those wishing to + learn more common computer science concepts +* There is a desire to avoid the "two-language problem" wherein parts of either + language are written in another and thus introduce unneeded complexity + +A fellow professor recommends that they look into Julia, which has already found +success within certain departments. Beyond addressing many of the issues +encountered with R and Python3, it is especially enjoyable how fast the +performance is, how the default package manager allows for reproducibility and +ease of use, and how close to mathematical writing Julia can get whilst +remaining readable. + +The first objective is to create a presentation format with good aesthetics that +can also show off and run code. They discover how to set up interactive +notebooks with [Pluto](https://plutojl.org/) that will be hosted in a [central +repository](https://github.com/) or online via a website or with solutions like +[Binder](https://pluto-on-binder.glitch.me/). This has a number of advantages +compared to PowerPoint or Markdown presentations: + +* Easily run and experiment with code cells within a reproducible environment +* Dependency management automatically handled via the built-in package manager +* Share the code and lessons with students either as notebooks or as exported + PDF/HTML pages + +To bundle the datasets with the notebooks, they take advantage of Julia's +[Artifact system](https://pkgdocs.julialang.org/v1/artifacts/) for handling and +retrieving data from almost anywhere on the Internet. + +With the course infrastructure set, attention is now put towards creating the +actual course material. They can cover a number of biostatistics topics using +powerful, well-established Julia packages: + +* [Plots](https://docs.juliaplots.org/stable/) or + [Makie](https://docs.makie.org/stable/) for data visualization +* [DataFrames](https://dataframes.juliadata.org/stable/), + [CSV](https://csv.juliadata.org/stable/), and + [Tidier](https://tidierorg.github.io/Tidier.jl/dev/) for data handling +* [Statistics] and [StatsBase] for general statistical functionality (scalar + statistics, estimation, ...) +* [Distributions](https://juliastats.org/Distributions.jl/stable/) for + probability and sampling +* [HypothesisTests](https://juliastats.org/HypothesisTests.jl/stable/) for + parametric (ANOVA, chi-squared, ...) and non-parametric testing +* [GLM](https://juliastats.org/GLM.jl/stable/) for generalized linear modelling +* [Flux](https://fluxml.ai/) or + [MLJ](https://alan-turing-institute.github.io/MLJ.jl/stable/) for basic + machine learning + +The course agenda is now almost complete. However, just before the start of the +semester, a new lesson on Tukey's honest significance test is added. +Unfortunately, there is no package written in Julia for this test, and there is +little time left to develop the code on their own. Luckily, Julia posseses +amazing interoperability with both Python3 and R, and they discover how to both +call and bundle Scipy's `stats.tukey_hsd` function via +[PythonCall](https://cjdoris.github.io/PythonCall.jl/stable/) and +[CondaPkg](https://github.com/cjdoris/CondaPkg.jl). + +The teacher goes on to deliver one of the best courses that semester, empowered +by Julia to deliver an engaging, interactive experience that teaches students +both the fundamentals of biostatistics and of quality programming. + diff --git a/docs/src/getting_started/juliainstallation.md b/docs/src/getting_started/juliainstallation.md index 77e3307..5507fb0 100644 --- a/docs/src/getting_started/juliainstallation.md +++ b/docs/src/getting_started/juliainstallation.md @@ -1,78 +1,93 @@ # [Installing Julia](@id juliainstallation) -There are a number of methods available to install Julia that each have their own advantages: +There are a number of methods available to install Julia that each have their +own advantages: -!!! note - 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! +!!! note + 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) -[juliaup](https://github.com/JuliaLang/juliaup.git) is a Julia manager/version multiplexer tool designed to handle your Julia -installation from the command-line. -It is the easiest and most convenient installation option, and is available on almost all platforms that support Julia. +[juliaup](https://github.com/JuliaLang/juliaup.git) is a Julia manager/version +multiplexer tool designed to handle your Julia 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 machine +!!! warning + This is not a recommended option as this will involve compiling the + actual `juliaup` executable on your machine ``` cargo install juliaup ``` -You can use the first and last commands listed to install Julia via `juliaup` in a container (see [Docker/Podman](#Docker/Podman) below) +You can use the first and last commands listed to install Julia via `juliaup` in +a container (see [Docker/Podman](#Docker/Podman) below) ## Docker/Podman -An [official Docker image](https://hub.docker.com/_/julia) is available, allowing you to build containers with Julia already installed. -This can be a preferred method of installation if you wish to test out Julia in a sandboxed, ephemeral (temporary) instance or are looking -to include Julia in a containerized application. +An [official Docker image](https://hub.docker.com/_/julia) is available, +allowing you to build containers with Julia already installed. This can be a +preferred method of installation if you wish to test out Julia in a sandboxed, +ephemeral (temporary) instance or are looking to include Julia in a +containerized application. You must first download the image via the Docker or Podman command-line tool: -!!! note - If you are using Podman, you can replace the keyword `docker` with `podman` in any of the following commands! +!!! note + If you are using Podman, you can replace the keyword `docker` with + `podman` in any of the following commands! ``` docker pull julia:latest ``` -You can specify which version of the image you wish to install via tags, such as `latest`, `rc`, `1.6`, etc. +You can specify which version of the image you wish to install via tags, such as +`latest`, `rc`, `1.6`, etc. To create a container instance, run the following command: -!!! note - You may skip the previous step if you have not already downloaded the image, Docker/Podman will automatically begin installing it for - you here! +!!! note + You may skip the previous step if you have not already downloaded the + image, Docker/Podman will automatically begin installing it for you here! ``` docker run -it --rm --network host julia:latest ``` -The above command creates an interactive container that will be deleted the moment you exit via the `--rm` option and that will also -share the same network namespace as your machine via the `--network host` option (allow for automatic port bindings). You may remove -either option to disable their respective behaviours. +The above command creates an interactive container that will be deleted the +moment you exit via the `--rm` option and that will also share the same network +namespace as your machine via the `--network host` option (allow for automatic +port bindings). You may remove either option to disable their respective +behaviours. -The image itself can serve as a base for your custom container built from a Dockerfile/Containerfile: +The image itself can serve as a base for your custom container built from a +Dockerfile/Containerfile: ``` FROM julia:latest # ... ``` -If you wish to use a different image as the basis of your container, yet still require Julia, you can use any of the other installation -methods listed in this section in your Dockerfile/Containerfile. A few examples with `juliaup`: +If you wish to use a different image as the basis of your container, yet still +require Julia, you can use any of the other installation methods listed in this +section in your Dockerfile/Containerfile. A few examples with `juliaup`: ``` # First option: Install juliaup via curl @@ -92,18 +107,24 @@ RUN cargo install juliaup ## Direct download -You can also install Julia as a downloadable executable from the Julia website's [Download section](https://julialang.org/downloads/). -You must make sure to install the correct Julia build for your machine based on: -- native instruction set (x86_64, i686, ARM, Apple Silicon, PowerPC) -- operating system type (Windows, MacOS, Linux (Glibc), Linux (Musl), FreeBSD) -- bit compute type (32-bit, 64-bit) -- desired level of support (Tier 1 (guaranteed to build and pass all tests) through Tier 4) +You can also install Julia as a downloadable executable from the Julia website's +[Download section](https://julialang.org/downloads/). You must make sure to +install the correct Julia build for your machine based on: +* native instruction set (x86_64, i686, ARM, Apple Silicon, PowerPC) +* operating system type (Windows, MacOS, Linux (Glibc), Linux (Musl), FreeBSD) +* bit compute type (32-bit, 64-bit) +* desired level of support (Tier 1 (guaranteed to build and pass all tests) + through Tier 4) -Make sure to follow the exact installation steps for your machine in order to ensure the best experience. +Make sure to follow the exact installation steps for your machine in order to +ensure the best experience. ## Build from source -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 start the Makefile build. +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 start the Makefile build. diff --git a/docs/src/getting_started/toolsinstallation.md b/docs/src/getting_started/toolsinstallation.md index b9af2e0..5579a11 100644 --- a/docs/src/getting_started/toolsinstallation.md +++ b/docs/src/getting_started/toolsinstallation.md @@ -2,12 +2,14 @@ ## [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 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: +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 @@ -21,15 +23,17 @@ alone can almost be considered a proper IDE. It should appear the moment you ent 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: +Not every feature that the REPL provides will be shown, 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: +* 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!) + 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 | @@ -41,73 +45,172 @@ know to make the most of this 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): +* 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 gotcha 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. +* 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 gotcha 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 - + x::Int + y::Int + end + julia> struct Point x::Int z::Int - end + 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. +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 +The Julia organization officially supports the [julia-vscode +extension](https://www.julia-vscode.org/) which, together with VSCode, provides +a complete solution for developing in Julia similar to a fully integrated +development environment (IDE). This boasts a number of advantages compared to a +pure REPL-driven 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](../assets/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. +* [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 or the [Julia +extension's](https://www.julia-vscode.org/) official website. + +## Alternative Editor/IDE extensions + +Although [julia-vscode](https://www.julia-vscode.org/) is the only officially +supported extension, community extensions are available for a range of code +editors/IDEs: + +- [julia-emacs](https://github.com/JuliaEditorSupport/julia-emacs.git) that + integrates a new major mode for developing in Julia +- [julia-vim](https://github.com/JuliaEditorSupport/julia-vim.git) to enable + Julia support for Vim/Neovim +- [julia-sublime](https://github.com/JuliaEditorSupport/Julia-sublime.git) to + enable Julia support for Sublime + +Certain editors/IDEs, such as [GodBolt](https://godbolt.org/) and +[Replit](https://replit.com/lm/julia), already support Julia without extensions. +Finally, many editors, like [micro](https://micro-editor.github.io/), natively +include support for basic features such as code highlighting or simple +autocomplete. + +## Notebooks + +A reactive notebook is an interactive environment that combines elements of a +code editor and a REPL into one solution. One writes code in executable blocks +of "cells" that can be mixed with text and other assets to create a reproducible +document that is shareable and easily manipulable. Notebooks are especially +useful for scientific exploration since code can be rapidly prototyped in an +isolated environment that can be both visualized and documented in the same +file. + +There are two standard methods for working with Julia in notebooks: + +### IJulia (Julia kernel for Jupyter) + +The Julia organization officially supports the +[IJulia](https://julialang.github.io/IJulia.jl/stable/) kernel, or backend, for +Jupyter notebooks, which is the most popular web-based notebook solution. + +To install IJulia/Jupyter and run the notebook server: + +!!! note + Instead of loading Pkg, one can simply activate pkg mode with the `]` key and enter `(@v1.9) pkg> add ` + + 1. Install Julia via any method mentioned in the [Installing Julia](@ref juliainstallation) section + 2. Open the Julia REPL by entering `julia` into your terminal + 3. Add the IJulia package via the built-in package manager: `julia> using Pkg;Pkg.add("IJulia")` + 4. Load IJulia and launch the notebook server: `julia> using IJulia; notebook()` + (run `notebook(detached=true)` if you wish that the notebook, and `notebook(dir="/some/path")` if you wish to open a notebook in a ) + server sruns in the background even if the Julia session is closed) + 5. Enter `y` to install Jupyter via Conda if you have not done so already on + your machine + +The notebook dashboard should open within your web browser. If you already have +jupyter installed ([Installing Jupyter](https://jupyter.org/install)), you can +enter `n` when prompted by the Julia REPL and instead run `jupyter notebook` +from the terminal. Visit the [Running +IJulia](https://julialang.github.io/IJulia.jl/stable/manual/running/#Running-IJulia) +section in the official IJulia docs for more information. + +### Pluto notebooks + +[Pluto.jl](https://plutojl.org/) is an alternative notebook solution built with +Julia in mind. It integrates well with the language and boasts a number of +features that are not available or are difficult to achieve with the Jupyter +solution: + +* Works with Julia's built-in package manager for native reproducibility +* Live docs feature, essentially Julia's help mode available within the notebook +* Works with normal Julia (.jl) files as opposed to .ipynb files +* Extendable via packages like + [PlutoUI](https://featured.plutojl.org/basic/plutoui.jl) and + [PlutoPDF](https://github.com/JuliaPluto/PlutoPDF.jl.git) + +To install and run the Pluto server: + + 1. Install Julia via any method mentioned in the [Installing Julia](@ref juliainstallation) section + 2. Open the Julia REPL by entering `julia` into your terminal + 3. Add the Pluto package via the built-in package manager: `julia> using Pkg;Pkg.add("Pluto")` + 4. Load Pluto and launch the notebook server: `julia> using Pluto; Pluto.run()` + 5. Copy/paste the given URL (http://localhost:...) into your web browser + +A number of featured notebooks are [available +online](https://featured.plutojl.org/) that include basic tutorials and powerful +demonstrations achieved with Pluto. diff --git a/docs/src/index.md b/docs/src/index.md index 9791d8e..2a9a1d2 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -1,29 +1,48 @@ # BioJulia: Fast, open, easy software for biology -> Note: This landing site is under extensive development and will receive frequent updates. -> It is not in a ready state, and is published under GitHub Pages only for testing purposes. +> Note: This landing site is under extensive development and will receive +> frequent updates. It is not in a ready state, and is published under GitHub +> Pages only for testing purposes. -BioJulia is a passionate, community-led organization providing biology-related packages written -in the [Julia programming language](https://julialang.org/). The organization offers a comprehensive, -fully open-source ecosystem of both libraries that serve as essential building blocks for other packages -as well as interactive tools for everyday tasks and workflows. +BioJulia is a passionate, community-led organization providing biology-related +packages written in the [Julia programming language](https://julialang.org/). +The organization offers a comprehensive, fully open-source ecosystem of both +libraries that serve as essential building blocks for other packages as well as +interactive tools for everyday tasks and workflows. -Biologists and other scientists are fully empowered by Julia to easily tackle domain-specific challenges, taking advantage of features including: -- [Fully reproducible environments](https://pkgdocs.julialang.org/v1/environments/) thanks to Julia's built-in package manager -- [Competitive performance](https://julialang.org/benchmarks/) that rivals that of lower-level, more complex languages such as C and Fortran -- [Unicode-based math symbol support](https://docs.julialang.org/en/v1/manual/unicode-input/), [transparent BLAS integration](https://docs.julialang.org/en/v1/stdlib/LinearAlgebra/#man-linalg), and additional features for performing complex numerical operations -- [A batteries-included read-eval-print loop (REPL)](https://docs.julialang.org/en/v1/stdlib/REPL/#The-Julia-REPL) for interactive data exploration and prototyping -- [Seamless interoperability](https://docs.julialang.org/en/v1/manual/calling-c-and-fortran-code/#Calling-C-and-Fortran-Code) [(JLLs,](https://docs.binarybuilder.org/stable/#Project-flow) [Cmd,...)](https://docs.julialang.org/en/v1/manual/running-external-programs/#Running-External-Programs) with other languages via multiple foreign function interfaces +Biologists and other scientists are fully empowered by Julia to easily tackle +domain-specific challenges, taking advantage of features including: +* [Fully reproducible + environments](https://pkgdocs.julialang.org/v1/environments/) thanks to + Julia's built-in package manager +* [Competitive performance](https://julialang.org/benchmarks/) that rivals that + of lower-level, more complex languages such as C and Fortran +* [Unicode-based math symbol + support](https://docs.julialang.org/en/v1/manual/unicode-input/), [transparent + BLAS + integration](https://docs.julialang.org/en/v1/stdlib/LinearAlgebra/#man-linalg), + and additional features for performing complex numerical operations +* [A batteries-included read-eval-print loop + (REPL)](https://docs.julialang.org/en/v1/stdlib/REPL/#The-Julia-REPL) for + interactive data exploration and prototyping +* [Seamless + interoperability](https://docs.julialang.org/en/v1/manual/calling-c-and-fortran-code/#Calling-C-and-Fortran-Code) + [(JLLs,](https://docs.binarybuilder.org/stable/#Project-flow) + [Cmd,...)](https://docs.julialang.org/en/v1/manual/running-external-programs/#Running-External-Programs) + with other languages via multiple foreign function interfaces ## Where to Start? - - Take a look at all BioJulia code via the official [GitHub page](https://github.com/BioJulia). - - Begin contributing ideas and features following the [core guidelines](https://github.com/BioJulia/Contributing.git). - - Deep dive into the ecosystem over at the [Overview](). - - Start learning right away using the [Getting Started tutorials](). - - See some awesome examples in the [BioJulia Showcase](). - - - Come chat with us over in the [Slack](https://julialang.org/slack/) #biology workspace and on [forums](https://discourse.julialang.org/). +* Take a look at all BioJulia code via the official [GitHub + page](https://github.com/BioJulia) +* Begin contributing ideas and features following the [core + guidelines](https://github.com/BioJulia/Contributing.git) +* Deep dive into the ecosystem over at the [Overview]() +* Start learning right away using the [Getting Started tutorials]() +* See some awesome examples in the [BioJulia Showcase]() +* Come chat with us over in the [Slack](https://julialang.org/slack/) #biology + channel and on [forums](https://discourse.julialang.org/) -Use the top navigation bar to search for provided packages within one's field of interest. +Use the top navigation bar to search for provided packages within one's field of +interest. diff --git a/docs/src/overview.md b/docs/src/overview.md index e69de29..1a80318 100644 --- a/docs/src/overview.md +++ b/docs/src/overview.md @@ -0,0 +1,11 @@ +# [Overview](@id overview) + +# Overview of the BioJulia Ecosystem + +BioJulia is an + +## + +## Common Julia packages + +Below are a few examples of common Julia packages that are \ No newline at end of file