{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Setup and Installation\n",
    "\n",
    "The purpose of this tutorial is to demonstrate the proper setup of your Python environment so that `hs_process` properly runs. In this tutorial, we will:\n",
    "\n",
    "1. [Install hs-process](installation.html#Installing-with-Anaconda/conda)\n",
    "2. [Confirm you are using the correct Python installation](installation.html#Confirming-your-environment)\n",
    "3. Verify that the installation was successful by [executing a test script](installation.html#Testing-hs_process-installation)\n",
    "\n",
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Installing with Anaconda/conda\n",
    "\n",
    "With [Anaconda](https://www.anaconda.com/distribution/#download-section) installed, please proceed to install `hs_process` via [conda-forge](https://anaconda.org/conda-forge/hs-process):\n",
    "\n",
    "```\n",
    "conda install -c conda-forge hs-process\n",
    "```\n",
    "\n",
    "This is the easiest, most complete, and most reliable method for installation because it installs all of the dependencies from the same conda-forge channel. Before installing, it is recommended to create a new environment (see the [Python Environment setup below](installation.html#Create-a-new-environment-(optional)))."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Confirming your environment\n",
    "It can be easy to accidentally open a Python IDE (e.g., [Spyder](https://www.spyder-ide.org/) or [Jupyter Notebook](https://jupyter.org/)) for a Python environment different that where `hs_process` and its dependencies were installed. The following Python command can be used to confirm you are using the Python executable in your new environment:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'C:\\\\Users\\\\nigo0024\\\\Anaconda3\\\\envs\\\\hs_process\\\\python.exe'"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import sys\n",
    "\n",
    "sys.executable"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Testing `hs_process` installation\n",
    "To verify `hs_process` and its dependencies are properly installed, the `test.py` can be run. First get local access to `test.py`:\n",
    "\n",
    "1. Fork, clone, or download the [hs_process repository](https://github.com/tnigon/hs_process).\n",
    "\n",
    "2. Download [sample files](https://drive.google.com/drive/folders/1KpOBB4-qghedVFd8ukQngXNwUit8PFy_?usp=sharing) and place into the newly forked/cloned/downloaded `hs_process\\test\\testdata` directory (do not change the file names).\n",
    "\n",
    "__*Note*__: There is a hyperspectral datacube that is ~750 MB, and this is why this data is not placed in the `testdata` folder by default (Github doesn't allow large files). The small files should be included from Github, but the *.spec* and *.bip* files must be copied over. After copying the sample files to your `testdata` directory, run `test.py` from your command prompt:\n",
    "\n",
    "3. `python <path to hs_process\\test\\test.py>` to run through some basic tests to be sure all dependencies are installed properly.\n",
    "\n",
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Other information\n",
    "\n",
    "### Install Python\n",
    "There are many ways to download and install Python. The [Anaconda distribution](https://www.anaconda.com/distribution/#download-section) is recommended becuase it can simplify the installation of package dependencies and streamlines the process of setting up the virtual environment. Anaconda also comes with [Spyder](https://www.spyder-ide.org/) and [Jupyter notebooks](https://jupyter.org/), each of which make working with Python quite easy.\n",
    "\n",
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Create a new environment (optional)\n",
    "\n",
    "Creating a new environment is not strictly necessary, but given that installing other geospatial packages from different channels may cause dependency conflicts, it can be good practice to install the geospatial stack in a clean environment starting fresh.\n",
    "\n",
    "A *Python environment* refers to the ecosystem consisting of a particular installed version of [Python](https://www.python.org/), as well as any third-party packages it has access to. In Python, every time a package is installed (e.g., `pip install some_third_party_package`, `conda install -c conda-forge some_third_party_package`, etc.), your Python environment is gaining functionality that builds upon the [Python Standard Library](https://docs.python.org/3/library/).\n",
    "\n",
    "This is great because the possibilities of what can be accomplished using Python is virtually limitless. Ideally, the list of packages in a given environment should only include those required in the project we are working on, not all packages that have ever been installed and are needed for any project you've ever worked on (this can be dozens or even hundreds of packages). A downside with too many packages is that it is inefficient to share your environment with someone else that would like to use the program. As time goes on, there may also be compatibility issues among package dependencies and your code that can be avoided by creating a tidy little Python environment for your project.\n",
    "\n",
    "With [Anaconda](https://www.anaconda.com/distribution/#download-section) installed, it is first recommended (but not required) to create a new **Python 3.8** environment before installing package dependencies. Open an Anaconda console from the start menu as an administrator by clicking `Start->Anaconda`, right-click `Anaconda Console`, and choose to `Run as Administrator`. In the `Anaconda Console`, execute the following commands:\n",
    "\n",
    "1. `conda create -n spec python=3.8` to create an Anaconda **Python 3.8** environment named **spec** (you can name this whatever you'd like).\n",
    "2. `conda activate spec` to activate the newly configured environment. **IMPORTANT**: Anytime you want to use `hs_process`, be sure to run `conda activate spec` prior to opening your Python IDE via the command line (e.g. *Spyder*, *Jupyter Notebook*, etc.). Otherwise, open your IDE via Anaconda Navigator, being sure the correct environment is active.\n",
    "\n",
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### System Requirements\n",
    "\n",
    "`hs_process` was developed using Python 3 (on Windows 10 OS), so it is recommended to install and use Python 3. This tutorial has only been tested on Windows. It will likely work on other major platforms (i.e., Windows, Linux, Mac), but you will have to be sure to get the required dependencies installed and working on your own.\n",
    "\n",
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Software and Libraries\n",
    "\n",
    "The following software and libraries are required to leverage the full API of `hs_process`:\n",
    "\n",
    "**Software**\n",
    "\n",
    "* [Python 3](https://www.python.org/downloads/)\n",
    "\n",
    "**Libraries**\n",
    "\n",
    "1. [GeoPandas](https://anaconda.org/conda-forge/geopandas)\n",
    "2. [Seaborn](https://anaconda.org/conda-forge/seaborn) (if only for visualizing data in the API examples)\n",
    "3. [Spectral Python](https://anaconda.org/conda-forge/spectral)\n",
    "\n",
    "The following libraries are also dependencies of `hs_process`, but they are also dependencies of `GeoPandas`, `Seaborn`, and `Spectral`. Therefore they will be installed during the install procedures of the above libraries.\n",
    "\n",
    "- [GDAL](https://anaconda.org/conda-forge/gdal) *`GeoPandas` has a `GDAL` dependency\n",
    "- [Numpy](https://anaconda.org/conda-forge/numpy) *`GDAL` has a `numpy` dependency\n",
    "- [Pandas](https://anaconda.org/conda-forge/pandas) *`GeoPandas` has a `Pandas` dependency\n",
    "- [Matplotlib](https://anaconda.org/conda-forge/matplotlib) *`Seaborn` has a `Matplotlib` dependency\n",
    "- [Shapely](https://anaconda.org/conda-forge/shapely) *`GeoPandas` has a `Shapely` dependency\n",
    "\n",
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Other methods for installing `hs_process`\n",
    "**IMPORTANT**: Before installing `hs_process` via any of the following methods, be sure the [GeoPandas](http://geopandas.org/install.html) and [Fiona](https://fiona.readthedocs.io/en/latest/index.html) dependencies are installed via `conda` (see [GeoPandas and Fiona dependencies](installation.html#GeoPandas-and-Fiona-dependencies) below).\n",
    "\n",
    "* `pip install git+https://github.com/tnigon/hs_process` [*(link)*](https://github.com/tnigon/hs_process) will install the latest development version directly from Github.\n",
    "\n",
    "OR *another* option is to clone the Github repository and install from your local copy. After navigating to the directory of your cloned local copy:\n",
    "\n",
    "* `pip install .`\n",
    "\n",
    "The recommended folder directory for the `hs_process` package is in the *site-packages* folder in your Python Path (alongside all other Python packages).\n",
    "\n",
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### [GeoPandas](http://geopandas.org/install.html) and [Fiona](https://fiona.readthedocs.io/en/latest/index.html) dependencies\n",
    "**IMPORTANT**: The [GeoPandas](http://geopandas.org/install.html) and [Fiona](https://fiona.readthedocs.io/en/latest/index.html) dependencies **MUST** installed via `conda`. [GeoPandas](http://geopandas.org/install.html) has a dependency on [Fiona](https://fiona.readthedocs.io/en/latest/index.html), and because of some nuances with the [pip version of Fiona*](https://pypi.org/project/Fiona/), [GeoPandas](https://anaconda.org/conda-forge/geopandas) **MUST** be installed via Anaconda (at least on Windows OS).\n",
    "\n",
    "* `conda install -c conda-forge geopandas` [*(link)*](https://anaconda.org/conda-forge/geopandas) will install both *GeoPandas* and *fiona* because *GeoPandas* has a [fiona dependency](http://geopandas.org/install.html#dependencies).\n",
    "\n",
    "*During installation, the pip version of [Fiona](https://pypi.org/project/Fiona/) requires that it is able to discover the locations of header files and libraries needed to compile its C extnesions, and these must be provided by the user when installing on Windows. For more information on this behavior, please refer to the [Fiona documentation](https://fiona.readthedocs.io/en/latest/README.html#windows)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}