-
-
Notifications
You must be signed in to change notification settings - Fork 1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #5278 from janezd/update-installation-instructions
README.md: Update installation instructions
- Loading branch information
Showing
1 changed file
with
137 additions
and
77 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -5,13 +5,17 @@ | |
| </p> | ||
| <p align="center"> | ||
| <a href="https://orange.biolab.si/download" alt="Latest release"> | ||
| <img src="https://img.shields.io/github/v/release/biolab/orange3?label=download" /></a> | ||
| <img src="https://img.shields.io/github/v/release/biolab/orange3?label=download" /> | ||
| </a> | ||
| <a href="https://orange3.readthedocs.io/en/latest/?badge=latest" alt="Documentation"> | ||
| <img src="https://readthedocs.org/projects/orange3/badge/?version=latest"></a> | ||
| <img src="https://readthedocs.org/projects/orange3/badge/?version=latest"> | ||
| </a> | ||
| <a href="https://discord.gg/FWrfeXV" alt="Discord"> | ||
| <img src="https://img.shields.io/discord/633376992607076354?logo=discord&color=7389D8&logoColor=white&label=Discord"> </a> | ||
| </p> | ||
|
|
||
| # Orange | ||
| [Orange] is a data mining and visualization toolbox for novice and expert alike. To explore data with Orange, one requires __no__ programming or in-depth mathematical knowledge. We believe that workflow-based data science tools democratize data science by hiding complex underlying mechanics and exposing intuitive concepts. Anyone who owns data, or is motivated to peek into data, should have the means to do so. | ||
| # Orange Data Mining | ||
| [Orange] is a data mining and visualization toolbox for novice and expert alike. To explore data with Orange, one requires __no programming or in-depth mathematical knowledge__. We believe that workflow-based data science tools democratize data science by hiding complex underlying mechanics and exposing intuitive concepts. Anyone who owns data, or is motivated to peek into data, should have the means to do so. | ||
|
|
||
| <p align="center"> | ||
| <a href="https://orange.biolab.si/download"> | ||
|
|
@@ -21,124 +25,180 @@ | |
|
|
||
| [Orange]: https://orange.biolab.si/ | ||
|
|
||
| ## Contributing | ||
|
|
||
| [](https://actions-badge.atrox.dev/biolab/orange3/goto) | ||
| [](https://codecov.io/gh/biolab/orange3) | ||
| [](https://github.com/biolab/orange3/graphs/contributors) | ||
| [](https://github.com/biolab/orange3/commits/master) | ||
| ## Installing | ||
|
|
||
| Want to get involved? Join us on [](https://discord.gg/FWrfeXV), introduce yourself in #general! | ||
| ### Easy installation | ||
|
|
||
| Take a look at our [contributing guide](https://github.com/irgolic/orange3/blob/README-shields/CONTRIBUTING.md), it might answer some questions, and it outlines the standards we adhere to. | ||
| For easy installation, [](https://orange.biolab.si/download) the latest released Orange version from our website. To install an add-on, head to `Options -> Add-ons...` in the menu bar. | ||
|
|
||
| Check out our widget development [](https://orange-widget-base.readthedocs.io/en/latest/?badge=latest) for a comprehensive guide on writing Orange widgets. | ||
| ### Installing with Conda | ||
|
|
||
| If you're looking for a good starting point, check out our [](https://github.com/biolab/orange3/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). | ||
| First, install [Miniconda](https://docs.conda.io/en/latest/miniconda.html) for your OS. | ||
|
|
||
| Then, create a new conda environment, and install orange3: | ||
|
|
||
| ### The Orange Ecosystem | ||
| ```Shell | ||
| # Add conda-forge to your channels for access to the latest release | ||
| conda config --add channels conda-forge | ||
|
|
||
| The development of Orange is primarily split into three repositories: | ||
| # Create and activate an environment for Orange | ||
| conda create python=3 --yes --name orange3 | ||
| conda activate orange3 | ||
|
|
||
| [biolab/orange-canvas-core](https://www.github.com/biolab/orange-canvas-core) implements canvas elements, | ||
| [biolab/orange-widget-base](https://www.github.com/biolab/orange-widget-base) implements a widget window's interface elements, | ||
| [biolab/orange3](https://www.github.com/biolab/orange3) brings it all together and implements the base data mining toolbox. | ||
| # Install Orange | ||
| conda install orange3 | ||
| ``` | ||
|
|
||
| Additionally, add-ons implement additional widgets for more specific use cases. [Anyone can write an add-on.](https://github.com/biolab/orange3-example-addon) Below is a list of our first-party add-ons: | ||
| For installation of an add-on, use: | ||
| ```Shell | ||
| conda install orange3-<addon name> | ||
| ``` | ||
| [See specific add-on repositories for details.](https://github.com/biolab/) | ||
|
|
||
| [biolab/orange3-text](https://www.github.com/biolab/orange3-text) | ||
| [biolab/orange3-bioinformatics](https://www.github.com/biolab/orange3-bioinformatics) | ||
| [biolab/orange3-timeseries](https://www.github.com/biolab/orange3-timeseries) | ||
| [biolab/orange3-single-cell](https://www.github.com/biolab/orange3-single-cell) | ||
| [biolab/orange3-imageanalytics](https://www.github.com/biolab/orange3-imageanalytics) | ||
| [biolab/orange3-educational](https://www.github.com/biolab/orange3-educational) | ||
| [biolab/orange3-geo](https://www.github.com/biolab/orange3-geo) | ||
| [biolab/orange3-associate](https://www.github.com/biolab/orange3-associate) | ||
| [biolab/orange3-network](https://www.github.com/biolab/orange3-network) | ||
| #### Running | ||
|
|
||
| ### Setting up | ||
| Activate the environment, | ||
| ```Shell | ||
| conda activate orange3 | ||
| ``` | ||
| and run either `orange-canvas` or `python3 -m Orange.canvas`. | ||
|
|
||
| 1. Set up a __virtual environment__. We recommend [Miniconda](https://docs.conda.io/en/latest/miniconda.html). | ||
| `conda create python=3 --name orange3` | ||
| 2. __Fork__ your chosen repository. | ||
| Press the fork button in top-right corner of the page | ||
| 3. __Clone__ it. | ||
| `git clone ssh://[email protected]/<your-username>/<repo-name>` | ||
| 4. __Install__ it. | ||
| `pip install -e .` or `python setup.py develop` | ||
| Add `--help` for a list of program options. | ||
|
|
||
| Now you're ready to work with git. See GitHub's guides on [pull requests](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests), [forks](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/working-with-forks) if you're unfamiliar. | ||
| If you're having trouble, get in touch on [](https://discord.gg/FWrfeXV). | ||
| Starting up for the first time may take a while. | ||
|
|
||
| ## Installing | ||
| ### Installing with pip | ||
|
|
||
| For easy installation, [](https://orange.biolab.si/download) the latest released Orange version from our website. | ||
| To install Orange with pip, run the following. | ||
|
|
||
| ### Installing with Miniconda / Anaconda | ||
| ```Shell | ||
| # Install build requirements via your system's package manager | ||
| sudo apt install virtualenv build-essential python3-dev | ||
|
|
||
| Orange requires Python 3.6 or newer. | ||
| # Create an environment for Orange and its dependencies | ||
| virtualenv --python=python3 --system-site-packages orange3venv | ||
|
|
||
| First, install [Miniconda] for your OS. Create virtual environment for Orange: | ||
| # Activate the environment | ||
| source orange3venv/bin/activate | ||
|
|
||
| ```Shell | ||
| conda create python=3 --name orange3 | ||
| # Install Orange | ||
| pip install orange3 | ||
| ``` | ||
| In your Anaconda Prompt add conda-forge to your channels: | ||
|
|
||
| #### Running | ||
|
|
||
| Activate the environment by `source orange3venv/bin/activate`. Then run `orange-canvas` or `python3 -m Orange.canvas`. Add `--help` for a list of program options. | ||
|
|
||
| Starting up for the first time may take a while. | ||
|
|
||
| ### Installing with winget (Windows only) | ||
|
|
||
| To install Orange with [winget](https://docs.microsoft.com/en-us/windows/package-manager/winget/), run: | ||
|
|
||
| ```Shell | ||
| conda config --add channels conda-forge | ||
| winget install --id UniversityofLjubljana.Orange | ||
| ``` | ||
|
|
||
| This will enable access to the latest Orange release. Then install Orange3: | ||
| ## Developing | ||
|
|
||
| [](https://actions-badge.atrox.dev/biolab/orange3/goto) [](https://codecov.io/gh/biolab/orange3) [](https://github.com/biolab/orange3/graphs/contributors) [](https://github.com/biolab/orange3/commits/master) | ||
|
|
||
| Want to write a widget? [Use the Orange3 example add-on template.](https://github.com/biolab/orange3-example-addon) | ||
|
|
||
| Want to get involved? Join us on [](https://discord.gg/FWrfeXV), introduce yourself in #general! | ||
|
|
||
| Take a look at our [contributing guide](https://github.com/irgolic/orange3/blob/README-shields/CONTRIBUTING.md) and [style guidelines](https://github.com/biolab/orange-widget-base/wiki/Widget-UI). | ||
|
|
||
| Check out our widget development [](https://orange-widget-base.readthedocs.io/en/latest/?badge=latest) for a comprehensive guide on writing Orange widgets. | ||
|
|
||
| ### The Orange ecosystem | ||
|
|
||
| The development of core Orange is primarily split into three repositories: | ||
|
|
||
| [biolab/orange-canvas-core](https://www.github.com/biolab/orange-canvas-core) implements the canvas, | ||
| [biolab/orange-widget-base](https://www.github.com/biolab/orange-widget-base) is a handy widget GUI library, | ||
| [biolab/orange3](https://www.github.com/biolab/orange3) brings it all together and implements the base data mining toolbox. | ||
|
|
||
| Additionally, add-ons implement additional widgets for more specific use cases. [Anyone can write an add-on.](https://github.com/biolab/orange3-example-addon) Some of our first-party add-ons: | ||
|
|
||
| - [biolab/orange3-text](https://www.github.com/biolab/orange3-text) | ||
| - [biolab/orange3-bioinformatics](https://www.github.com/biolab/orange3-bioinformatics) | ||
| - [biolab/orange3-timeseries](https://www.github.com/biolab/orange3-timeseries) | ||
| - [biolab/orange3-single-cell](https://www.github.com/biolab/orange3-single-cell) | ||
| - [biolab/orange3-imageanalytics](https://www.github.com/biolab/orange3-imageanalytics) | ||
| - [biolab/orange3-educational](https://www.github.com/biolab/orange3-educational) | ||
| - [biolab/orange3-geo](https://www.github.com/biolab/orange3-geo) | ||
| - [biolab/orange3-associate](https://www.github.com/biolab/orange3-associate) | ||
| - [biolab/orange3-network](https://www.github.com/biolab/orange3-network) | ||
| - [biolab/orange3-explain](https://www.github.com/biolab/orange3-explain) | ||
|
|
||
| ### Setting up for core Orange development | ||
|
|
||
| First, fork the repository by pressing the fork button in the top-right corner of this page. | ||
|
|
||
| Set your GitHub username, | ||
|
|
||
| ```Shell | ||
| conda install orange3 | ||
| export MY_GITHUB_USERNAME=replaceme | ||
| ``` | ||
|
|
||
| [Miniconda]: https://docs.conda.io/en/latest/miniconda.html | ||
|
|
||
| To install the add-ons, follow a similar recipe: | ||
| create a conda environment, clone your fork, and install it: | ||
|
|
||
| ```Shell | ||
| conda install orange3-<addon name> | ||
| conda create python=3 --yes --name orange3 | ||
| conda activate orange3 | ||
|
|
||
| git clone ssh://[email protected]/$MY_GITHUB_USERNAME/orange3 | ||
|
|
||
| pip install -e orange3 | ||
| ``` | ||
|
|
||
| See specific add-on repositories for details. | ||
| Now you're ready to work with git. See GitHub's guides on [pull requests](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests), [forks](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/working-with-forks) if you're unfamiliar. If you're having trouble, get in touch on [](https://discord.gg/FWrfeXV). | ||
|
|
||
| ### Installing with pip | ||
| #### Running | ||
|
|
||
| To install Orange with pip, run the following. | ||
| Run Orange with `python -m Orange.canvas` (after activating the conda environment). | ||
|
|
||
| ```Shell | ||
| # Install some build requirements via your system's package manager | ||
| sudo apt install virtualenv build-essential python3-dev | ||
| `python -m Orange.canvas -l 2 --no-splash --no-welcome` will skip the splash screen and welcome window, and output more debug info. Use `-l 4` for more. | ||
|
|
||
| # Create a separate Python environment for Orange and its dependencies ... | ||
| virtualenv --python=python3 --system-site-packages orange3venv | ||
| # ... and make it the active one | ||
| source orange3venv/bin/activate | ||
| Add `--clear-widget-settings` to clear the widget settings before start. | ||
|
|
||
| # Install Orange | ||
| pip install orange3 | ||
| ``` | ||
| To explore the dark side of the Orange, try `--style=fusion:breeze-dark` | ||
|
|
||
| ### Installing with winget (Windows only) | ||
| Argument `--help` lists all available options. | ||
|
|
||
| To install Orange with [winget](https://docs.microsoft.com/en-us/windows/package-manager/winget/), run: | ||
| To run tests, use `unittest Orange.tests Orange.widgets.tests` | ||
|
|
||
|
|
||
| ### Setting up for development of all components | ||
|
|
||
| Should you wish to contribute Orange's base components (the widget base and the canvas), you must also clone these two repositories from Github instead of installing them as dependencies of Orange3. | ||
|
|
||
| First, fork all the repositories to which you want to contribute. | ||
|
|
||
| Set your GitHub username, | ||
|
|
||
| ```Shell | ||
| winget install --id UniversityofLjubljana.Orange | ||
| export MY_GITHUB_USERNAME=replaceme | ||
| ``` | ||
|
|
||
| ### Starting Orange GUI | ||
|
|
||
| To start Orange GUI from the command line, run: | ||
| create a conda environment, clone your forks, and install them: | ||
|
|
||
| ```Shell | ||
| orange-canvas | ||
| # or | ||
| python3 -m Orange.canvas | ||
| conda create python=3 --yes --name orange3 | ||
| conda activate orange3 | ||
|
|
||
| git clone ssh://[email protected]/$MY_GITHUB_USERNAME/orange-widget-base | ||
| pip install -e orange-widget-base | ||
|
|
||
| git clone ssh://[email protected]/$MY_GITHUB_USERNAME/orange-canvas-core | ||
| pip install -e orange-canvas-core | ||
|
|
||
| git clone ssh://[email protected]/$MY_GITHUB_USERNAME/orange3 | ||
| pip install -e orange3 | ||
|
|
||
| # Repeat for any add-on repositories | ||
| ``` | ||
|
|
||
| Append `--help` for a list of program options. | ||
| It's crucial to install `orange-base-widget` and `orange-canvas-core` before `orange3` to ensure that `orange3` will use your local versions. | ||