From 399ba89dd8369ed82cfb44e4332e339d66b0a8f8 Mon Sep 17 00:00:00 2001 From: mdtanker Date: Tue, 11 Jun 2024 11:32:34 +0200 Subject: [PATCH] docs: consolidate and update install instructions --- README.md | 102 ++++++++++++------------------------------------ docs/install.md | 72 ++++++++++++++++++++-------------- 2 files changed, 68 insertions(+), 106 deletions(-) diff --git a/README.md b/README.md index f9468ea4..463a64a2 100644 --- a/README.md +++ b/README.md @@ -7,19 +7,14 @@ -**PolarToolkit** (formerly known as Antarctic-Plots) is a Python package with -the goal of making Polar (i.e. Antarctic, Arctic, Greenland) research more -efficient, reproducible, and accessible. The software does this by providing: +**PolarToolkit** (formerly known as Antarctic-Plots) is a Python package to make Polar (i.e. Antarctic, Arctic, Greenland) research more efficient, reproducible, and accessible. +The software does this by providing: -- Convenient functions for downloading and pre-processing a wide range of - commonly used polar datasets -- Tools for common geospatial tasks (i.e. changing data resolution, subsetting - data by geographic regions) -- Code to easily create publication-quality maps, data profiles, and - cross-sections +- Convenient functions for downloading and pre-processing a wide range of commonly used polar datasets +- Tools for common geospatial tasks (i.e. changing data resolution, subsetting data by geographic regions) +- Code to easily create publication-quality maps, data profiles, and cross-sections -Additionally, **PolarToolkit** provides an easy means for exploring datasets -with pre-defined or interactively-chosen geographic regions. +Additionally, **PolarToolkit** provides an easy means for exploring datasets with pre-defined or interactively chosen geographic regions. @@ -53,51 +48,35 @@ alt="Latest version on PyPI"/> 🚨 **Ready for daily use but still changing.** 🚨

-This means that we are still adding a lot of new features and sometimes we make -changes to the ones we already have while we try to improve the software based -on users' experience, test new ideas, make better design decisions, etc. Some of -these changes could be **backwards incompatible**. Keep that in mind before you -update PolarToolkit to a new major version (i.e. from `v1.0.0` to `v2.0.0`). +This means that we are still adding a lot of new features and sometimes we make changes to the ones we already have while we try to improve the software based on users' experience, test new ideas, make better design decisions, etc. +Some of these changes could be **backwards incompatible**. +Keep that in mind before you update PolarToolkit to a new major version (i.e. from `v1.0.0` to `v2.0.0`) and always check the [Changelog](https://github.com/mdtanker/polartoolkit/blob/main/CHANGELOG.md) for `BREAKING CHANGES` and how to update your code appropriately. -I welcome any feedback, ideas, or contributions! Please contact us on the -[GitHub discussions page](https://github.com/mdtanker/polartoolkit/discussions) -or submit an [issue on GitHub](https://github.com/mdtanker/polartoolkit/issues) -for problems or feature ideas. +I welcome any feedback, ideas, or contributions! +Please contact us on the [GitHub discussions page](https://github.com/mdtanker/polartoolkit/discussions) or submit an [issue on GitHub](https://github.com/mdtanker/polartoolkit/issues) for problems or feature ideas. -The **PolarToolkit** python package provides some basic tools to help in -conducting polar research. You can use it to download common datasets (i.e. -BedMachine, Bedmap2, MODIS Mosaics), create maps and plots specific to -Antarctica, Greenland and the Arctic and visualize data with multiple methods. +The **PolarToolkit** python package provides some basic tools to help in conducting polar research. +You can use it to download common datasets (i.e. BedMachine, Bedmap2, MODIS Mosaics), create maps and plots specific to Antarctica, Greenland and the Arctic and visualize data with multiple methods. -Feel free to use, share, modify, and -[contribute](https://polartoolkit.readthedocs.io/en/latest/contributing.html) to -this project. I've mostly made this for personal usage so expect significant -changes. Hopefully, I'll implement more tests and Gallery examples soon. +Feel free to use, share, modify, and [contribute](https://polartoolkit.readthedocs.io/en/latest/contributing.html) to this project. ### What _PolarToolkit_ is for: -- download commonly used datasets related to Antarctica, Greenland and the - Arctic +- download commonly used datasets related to Antarctica, Greenland and the Arctic - making publication-quality maps and cross-sections - interactively explore data and define geographic regions -- plotting and working with data in projected coordinates (meters) in either - EPSG 3031 or 3413, for the South and North hemispheres, respectively -- mostly focused on regularly gridded (interpolated) datasets, with some support - for discrete (un-gridded) data -- current focus for datasets is related to ice, geophysics, and earth properties - since this is where my personal research interests are, but please request or - add your own types of data! -- basic geospatial manipulations (filtering, resampling, reprojecting, masking - etc.) +- plotting and working with data in projected coordinates (meters) in either EPSG 3031 or 3413, for the South and North hemispheres, respectively +- mostly focused on regularly gridded (interpolated) datasets, with some support for discrete (un-gridded) data +- current focus for datasets is related to ice, geophysics, and earth properties since this is where my personal research interests are, but please request or add your own types of data! +- basic geospatial manipulations (filtering, resampling, reprojecting, masking etc.) ### What _PolarToolkit_ is **NOT** for: - downloading niche datasets or those that only cover specific regions - downloaded datasets outside of Antarctica, Greenland and the Arctic -- plotting and working with data in geographic (latitude and longitude) - coordinates +- plotting and working with data in geographic (latitude and longitude) coordinates - plots not related to geospatial data - a point-and-click GUI for plotting or data exploration -> see [Quantarctica](https://www.npolar.no/quantarctica/) or @@ -110,39 +89,16 @@ changes. Hopefully, I'll implement more tests and Gallery examples soon. -## Installation - -There are 3 main ways to install `polartoolkit`. We show them here in order of -simplest to hardest. - -### Conda / Mamba - -The easiest way to install this package and its dependencies is with conda or -mamba into a new virtual environment: - -``` -mamba create --name polartoolkit --yes --force polartoolkit -``` - -And activate the environment: - -``` -conda activate polartoolkit -``` - -Note that `conda` and `mamba` are interchangeable. ### Pip -Instead, you can use pip to install `polartoolkit`, but first you need to -install a few dependencies with conda. This is because `PyGMT` `GeoPandas`, and -`Cartopy` all rely on C packages, which can only be install with conda/mamba and -not with pip. +Instead, you can use pip to install `polartoolkit, but first, you need to install a few dependencies with conda. +This is because `PyGMT` `GeoPandas`, and `Cartopy` all rely on C packages, which can only be successfully installed with conda/mamba and not with pip. To create a new virtual environment: ``` -mamba create --name polartoolkit --yes --force pygmt geopandas cartopy +mamba create --name polartoolkit --yes --force pygmt geopandas cartopy --channel conda-forge ``` And activate the environment, followed by using `pip` to install `polartoolkit`: @@ -160,8 +116,7 @@ To install the optional dependencies of `polartoolkit`, use this instead: ### Development version -You can use pip, with the above created environment, to install the latest -source from GitHub: +You can use pip, with the above-created environment, to install the latest source from GitHub: ``` pip install git+https://github.com/mdtanker/polartoolkit.git @@ -176,13 +131,8 @@ pip install . ``` ## How to contribute - -I really welcome all forms of contribution! If you have any questions, comments -or suggestions, please open a [discussion]() or [issue (feature request)]() on -the [GitHub page](https://github.com/mdtanker/polartoolkit/)! +I welcome all forms of contribution! If you have any questions, comments or suggestions, please open a [discussion](https://github.com/mdtanker/polartoolkit/discussions/new/choose) or [issue (feature request)](https://github.com/mdtanker/polartoolkit/issues/new/choose) on the [GitHub page](https://github.com/mdtanker/polartoolkit/)! Also, please feel free to share how you're using PolarToolkit, I'd love to know. -Please, read our -[Contributor Guide](https://polartoolkit.readthedocs.io/en/latest/contributing.html) -to learn how you can contribute to the project. +Please, read our [Contributor Guide](https://polartoolkit.readthedocs.io/en/latest/contributing.html) to learn how you can contribute to the project. diff --git a/docs/install.md b/docs/install.md index 5b4fcb39..7f7d793e 100644 --- a/docs/install.md +++ b/docs/install.md @@ -2,52 +2,45 @@ ## Online usage (Binder) -See below for the full installation instructions. If instead you'd like to use -this package online, without needing to install anything, check out our -[Binder link](https://mybinder.org/v2/gh/mdtanker/polartoolkit-binder/main?urlpath=git-pull%3Frepo%3Dhttps%253A%252F%252Fgithub.com%252Fmdtanker%252Fpolartoolkit%26urlpath%3Dtree%252Fpolartoolkit%252Fdocs%252Fgallery%26branch%3Dmain), -which gives full access the the package in an online environment. +See below for the full installation instructions. If instead you'd like to use this package online, without needing to install anything, check out our [Binder link](https://mybinder.org/v2/gh/mdtanker/polartoolkit-binder/main?urlpath=git-pull%3Frepo%3Dhttps%253A%252F%252Fgithub.com%252Fmdtanker%252Fpolartoolkit%26urlpath%3Dtree%252Fpolartoolkit%252Fdocs%252Fgallery%26branch%3Dmain), which gives full access to the latest released version of the package in an online environment. ## Install Python -Before installing _PolarToolkit_, ensure you have Python downloaded. If you -don't, I recommend setting up Python with Miniforge. See the install -instructions [here](https://github.com/conda-forge/miniforge). +Before installing _PolarToolkit_, ensure you have Python 3.9 or greater downloaded. +If you don't, I recommend setting up Python with Miniforge. +See the install instructions [here](https://github.com/conda-forge/miniforge). ## Install _PolarToolkit_ Locally -There are 3 main ways to install `polartoolkit`. We show them here in order of -simplest to hardest. +There are 3 main ways to install `polartoolkit`. We show them here in order of simplest to hardest. ### Conda / Mamba -The easiest way to install this package and it's dependencies is with conda or -mamba into a new virtual environment: +```{note} +`conda` and `mamba` are interchangeable +``` + +The easiest way to install this package and it's dependencies is with conda or mamba into a new virtual environment: ``` -mamba create --name polartoolkit --yes --force polartoolkit +mamba create --name polartoolkit --yes --force polartoolkit --channel conda-forge ``` Activate the environment: ``` -conda activate polartoolkit +mamba activate polartoolkit ``` ### Pip -Instead, you can use pip to install `polartoolkit`, but first you need to -install a few dependencies with conda. This is because `PyGMT` `GeoPandas`, and -`Cartopy` all rely on C packages, which can only be install with conda/mamba and -not with pip. - -```{note} -`conda` and `mamba` are interchangeable -``` +Instead, you can use pip to install `polartoolkit`, but first you need to install a few dependencies with conda. +This is because `PyGMT` `GeoPandas`, and `Cartopy` all rely on C packages, which can only be successfully install with conda/mamba and not with pip. Create a new virtual environment: ``` -mamba create --name polartoolkit --yes --force pygmt geopandas cartopy +mamba create --name polartoolkit --yes --force pygmt geopandas cartopy --channel conda-forge ``` activate the environment and use `pip` to install `polartoolkit`: @@ -64,8 +57,7 @@ to install the optional dependencies, use this instead: ### Development version -You can use pip, with the above created environment, to install the latest -source from GitHub: +You can use pip, with the above created environment, to install the latest source from GitHub: pip install git+https://github.com/mdtanker/polartoolkit.git @@ -77,21 +69,41 @@ Or you can clone the repository and install: ## Common errors -If you get errors related to GDAL and GMT, try reinstalling Geopandas and PyGMT -with the following command: +If you get errors related to GDAL and GMT, try reinstalling Geopandas and PyGMT with the following command: - mamba install geopandas pygmt --force-reinstall -y + mamba install geopandas pygmt --force-reinstall -y --channel conda-forge If you get errors related to the PyProj EPSG database, try the following: - mamba install -c conda-forge proj-data --force-reinstall -y + mamba install -c conda-forge proj-data --force-reinstall -y --channel conda-forge or mamba remove --force pyproj -y pip install pyproj --force-reinstall -If you get an error related to traitlets run the following command as discussed -[here](https://github.com/microsoft/vscode-jupyter/issues/5689#issuecomment-829538285): +If you get an error related to traitlets run the following command as discussed [here](https://github.com/microsoft/vscode-jupyter/issues/5689#issuecomment-829538285): mamba install ipykernel --update-deps --force-reinstall -y + +If you are still having errors, then you can download the `environment.yml` file from [here]() and create a conda environment directly from this: + + mamba create --file PATH_TO_FILE + +where you replace PATH_TO_FILE with the path to your downloaded `environment.yml` file. + +## Test your install + +Run the following inside a Python interpreter: + +```python +import polartoolkit +polartoolkit.__version__ +``` + +This should tell you which version was installed. + +To further test, you can clone the GitHub repository and run the suite of tests, see the [Contributors Guide](https://polartoolkit.readthedocs.io/en/latest/contributing.html). + +A simpler method to ensure the basics are working would be to download any of the Tutorials or How-to guides and run them locally. On the documentation, each of the examples should have a drop down button in the top right corner to download the `.ipynb`. +