Skip to content

Commit

Permalink
rewrite install instructions for tutorial and remove top level instal…
Browse files Browse the repository at this point in the history 
…l page
  • Loading branch information
@droumis
droumis committed Apr 25, 2024
1 parent 40f966c commit 7130a39
Show file tree
Hide file tree
Showing 3 changed files with 55 additions and 72 deletions.
3 changes: 3 additions & 0 deletions doc/conf.py
View file
Expand Up @@ -48,3 +48,6 @@
'github_user': 'holoviz',
'github_repo': 'holoviz',
})

# Uncomment to turn off notebook execution.
# nb_execution_mode = "off"
1 change: 0 additions & 1 deletion doc/index.rst
View file
Expand Up @@ -87,7 +87,6 @@ If what you see looks relevant to you, you can then follow the steps outlined in
:maxdepth: 2

Background <background>
Installation <installation>
Talks <talks/index>
Tutorial <tutorial/index>
Blog <https://blog.holoviz.org/>
Expand Down
123 changes: 52 additions & 71 deletions examples/tutorial/00_Setup.ipynb
View file
Expand Up @@ -13,67 +13,60 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"This first step to the tutorial will make sure your system is set up to do all the remaining sections, with all software installed and all data downloaded as needed. The [index](index.ipynb) provided some links you might want to examine before you start."
"This first step to the tutorial will ensure your system is set up to handle all the subsequent sections, with all software installed and all data downloaded as needed. The [index](index.ipynb) provides some links you might want to examine before you start."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Getting set up\n",
"\n",
"Please consult [holoviz.org](http://holoviz.org/installation.html) for the full instructions on installing the software used in these tutorials. Here is the condensed version of those instructions, assuming you have already downloaded and installed [Anaconda](https://www.anaconda.com/download) or [Miniconda](https://conda.io/miniconda.html) and have opened a command prompt in a Conda environment:"
"<div class=\"admonition alert alert-warning\">\n",
" <p class=\"admonition-title\" style=\"font-weight:bold\">Tutorial Instructions Only!</p>\n",
" The instructions below are specific to this tutorial. If you are looking to install a HoloViz package for your own use, please consult each library's website (linked from <a href=\"https://holoviz.org/\">HoloViz.org</a>) for detailed guidance. Typically, installing these packages simply involves `conda install` or `pip install`.\n",
"</div>\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"```\n",
"conda create -n project \"anaconda-project>=0.11\"\n",
"conda activate project\n",
"anaconda-project download pyviz/holoviz_tutorial\n",
"cd holoviz_tutorial # You may need to delete this directory if you've run the command above before\n",
"anaconda-project run jupyter notebook\n",
"```"
"<div class=\"admonition alert alert-info\">\n",
" <p class=\"admonition-title\" style=\"font-weight:bold\">Get the latest version</p>\n",
" If you are attending a live tutorial or workshop and have previously run through the tutorial, make sure to run these steps again shortly before the live session to ensure you have the same version of the tutorial that the presenter will use.\n",
"</div>"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"If you prefer JupyterLab to the default (classic) notebook interface, you can replace \"notebook\" with \"lab\"."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Once your chosen environment is running, navigate to `tutorial/00_Setup.ipynb` (i.e. this notebook) and run the following cell to test the key imports needed for this tutorial. If it completes without errors your environment should be ready to go:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"import datashader as ds, bokeh, holoviews as hv, panel as pn # noqa\n",
"from packaging.version import Version\n",
"## Getting set up\n",
"\n",
"min_versions = dict(ds='0.15.1', bokeh='3.2.0', hv='1.16.2', pn='1.2.0')\n",
"1. **Install conda**:\n",
" If you don't have conda installed, you can follow the [conda docs](https://conda.io/projects/conda/en/latest/user-guide/install/index.html) to download and install it. We recommend using the [Miniconda](https://conda.io/miniconda.html) installer.\n",
"\n",
"for lib, ver in min_versions.items():\n",
" v = globals()[lib].__version__\n",
" if Version(v) < Version(ver):\n",
" print(\"Error: expected {}={}, got {}\".format(lib,ver,v))"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"And you should see the HoloViews, Bokeh, and Matplotlib logos after running the following cell:"
"2. **Open a new terminal window**\n",
" \n",
"3. **Create and activate a new conda environment**: This environment is just for `anaconda-project`, a tool to help download the required packages and data for the tutorial.\n",
" ```bash\n",
" >> conda create -n project \"anaconda-project>=0.11\"\n",
" >> conda activate project\n",
" ```\n",
"\n",
"4. **Download and navigate to the tutorial project**: If you've previously run the `anaconda-project download` command below, you may need to delete or rename the pre-existing `holoviz_tutorial` directory.\n",
" ```bash\n",
" >> anaconda-project download pyviz/holoviz_tutorial\n",
" >> cd holoviz_tutorial\n",
" ```\n",
"\n",
"5. **Run the tutorial Launch Jupyter**: Don't be alarmed, this will output many lines as it downloads packages, sets up another conda environment for the tutorial, and then launches Jupyter.\n",
" ```bash\n",
" >> anaconda-project run jupyter lab\n",
" ```\n",
" Note: You can replace \"lab\" with \"notebook\" if you prefer the original Jupyter notebook interface.\n",
"\n",
"5. **Test HoloViz imports**:\n",
"After launching Jupyter, navigate to this notebook (`tutorial/00_Setup.ipynb`) and run the following cell. This is a quick check that your environment is set up correctly. You should see the HoloViews, Bokeh, and Matplotlib logos along with a success message.\n"
]
},
{
Expand All @@ -82,21 +75,19 @@
"metadata": {},
"outputs": [],
"source": [
"hv.extension('bokeh', 'matplotlib')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Downloading sample data"
"import version_checker\n",
"import datashader, panel, hvplot, param, holoviews as hv # noqa\n",
"hv.extension('bokeh', 'matplotlib')\n",
"\n",
"packages = ['datashader', 'holoviews', 'panel', 'hvplot', 'param']\n",
"version_checker.check_packages(packages)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Lastly, let's make sure the datasets needed are available. First, check that the large earthquake dataset was downloaded correctly during the `anaconda-project run` command:"
"7. **Check datasets**: Finally, run the following cell to make sure the dataset exists and is readable."
]
},
{
Expand All @@ -106,33 +97,18 @@
"outputs": [],
"source": [
"import pathlib\n",
"from pyct import cmd\n",
"import pandas as pd\n",
"\n",
"if not pathlib.Path('../data/earthquakes-projected.parq').is_file():\n",
" cmd.fetch_data(name='holoviz', path='..') # Alternative way to fetch the data"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Make sure that you have the SNAPPY dependency required to read these data:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"try:\n",
" import pandas as pd\n",
"print('Data exists:', pathlib.Path('../data/earthquakes-projected.parq').is_file())\n",
"\n",
"try: \n",
" columns = ['depth', 'id', 'latitude', 'longitude', 'mag', 'place', 'time', 'type']\n",
" path = pathlib.Path('../data/earthquakes-projected.parq')\n",
" data = pd.read_parquet(path, columns=columns, engine='fastparquet')\n",
" data.head()\n",
" print('Data check successful!')\n",
"except RuntimeError as e:\n",
" print('The data cannot be read: %s' % e)"
" print('The data cannot be read: %s' % e)\n"
]
},
{
Expand All @@ -141,6 +117,11 @@
"source": [
"If you don't see any error messages above, you should be good to go! Now that you are set up, you can continue with the [rest of the tutorial sections](01_Overview.ipynb). "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": []
}
],
"metadata": {
Expand Down

0 comments on commit 7130a39

Please sign in to comment.