Skip to content

Commit

Permalink
docs: consolidate and update install instructions
Browse files Browse the repository at this point in the history
  • Loading branch information
@mdtanker
mdtanker committed Jun 14, 2024
1 parent 8ef681f commit 399ba89
Show file tree
Hide file tree
Showing 2 changed files with 68 additions and 106 deletions.
102 changes: 26 additions & 76 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,19 +7,14 @@

<!-- SPHINX-START-proj-desc -->

**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.

<!-- SPHINX-END-proj-desc -->

Expand Down Expand Up @@ -53,51 +48,35 @@ alt="Latest version on PyPI"/></a>
🚨 **Ready for daily use but still changing.** 🚨
</p>

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.

<!-- SPHINX-START-long-desc -->

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
Expand All @@ -110,39 +89,16 @@ changes. Hopefully, I'll implement more tests and Gallery examples soon.

<!-- SPHINX-END-long-desc -->

## 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`:
Expand All @@ -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
Expand All @@ -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.
72 changes: 42 additions & 30 deletions docs/install.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`:
Expand All @@ -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

Expand All @@ -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`.

0 comments on commit 399ba89

Please sign in to comment.