diff --git a/docs/getting-started/installation.rst b/docs/getting-started/installation.rst index 5b2caa943..636fd2fa3 100644 --- a/docs/getting-started/installation.rst +++ b/docs/getting-started/installation.rst @@ -5,42 +5,61 @@ Installation ============ -UXarray is built **on top of** `Xarray `__, -so we **strongly** recommend becoming familiar with Xarray’s installation -process and dependencies first. +UXarray itself is a pure Python package, but its dependencies are not. +The easiest way to get everything installed is to use conda or pip. -Installing with Conda (recommended) ------------------------------------ +.. admonition:: Conda versus Pip -UXarray itself is a pure Python package, but its dependencies are not. -The easiest way to get everything installed is to use conda. -To install UXarray with its recommended dependencies using the conda command line tool: + Conda installs UXarray with all optional depencies. + Pip installs only the minimal required dependencies by default, but it + is also easy to include any/all optional dependencies too, if desired. +Installing with Conda +--------------------- + +To install UXarray with its recommended dependencies using the conda command line tool: + .. code-block:: bash conda install -c conda-forge uxarray -.. note:: - - Conda automatically installs Xarray and every other required - dependency (including non‑Python libraries). Installing with pip ------------------- +For a lightweight installation with **only required dependencies**: + .. code-block:: bash pip install uxarray -This installs the *minimal* required dependencies. UXarray also provides optional extras: + +For a complete installation which also includes **all optional dependencies**: .. code-block:: bash - pip install "uxarray[dev]" # development tools - pip install "uxarray[complete]" # all optional features + pip install "uxarray[complete]" -A complete list of extras lives in the ``[project.optional-dependencies]`` -section of our `pyproject.toml `_ + +For an installation including **only some optional dependencies**, +consider using one of the following extras: + +- ``pip install "uxarray[dev]"`` includes development tools (e.g. pytest, ruff) +- ``pip install "uxarray[geo]"`` includes geospatial packages (e.g. geopandas, healpix) +- ``pip install "uxarray[viz]"`` includes plotting packages (e.g. matplotlib, hvplot) + +It is also possible to combine extras, for example: + +- ``pip install "uxarray[geo,viz]"`` includes all geospatial and plotting packages. + + +To see the full lists of which optional dependencies are included with each extra group, +take a look at the ``[project.optional-dependencies]`` section in ``pyproject.toml``: + +.. literalinclude:: ../../pyproject.toml + :language: toml + :start-at: [project.optional-dependencies] + :end-before: [project.urls] Installing from source @@ -67,9 +86,12 @@ Installing from source is intended mainly for developers. .. code-block:: bash - pip install . + pip install ".[complete]" # test suite relies on optional dependencies + +#. **Optional: run the test suite** -#. **Run the test suite** + Running the test suite is a good way to verify that the installation is working correctly. + It should take roughly a minute to run on modern machines. .. code-block:: bash diff --git a/pyproject.toml b/pyproject.toml index 0596956c6..8a9548abf 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -23,41 +23,52 @@ requires-python = ">=3.10" # minimal dependencies start dependencies = [ "antimeridian", - "cartopy", "dask[dataframe]", - "datashader", - "geoviews", - "holoviews", - "matplotlib<3.11", # matplotlib 3.11.0 breaks some plots but <3.11 is fine; see issue #1542. - "matplotlib-inline", "netcdf4", "numba>=0.63", # 0.63 is the first release supporting Python 3.14 (3.10 <= py < 3.15). See #1561. "numpy", "pandas", - "pyarrow", - "requests", "scikit-learn", "scipy", "shapely", - "spatialpandas", - "geopandas", "xarray", - "hvplot", - "healpix", "polars", - "pyproj" ] # minimal dependencies end [project.optional-dependencies] -complete = ["uxarray[dev]"] -dev = ['pre_commit', 'pytest', 'pytest-cov', 'ruff', 'asv'] +all = ["uxarray[dev,geo,viz]"] +complete = ["uxarray[dev,geo,viz]"] # alias to "all" +dev = [ + 'asv', + 'pooch', + 'pre_commit', + 'pytest', + 'pytest-cov', + 'ruff', +] +geo = [ + "cartopy", # in both geo and viz it is needed by to_geodataframe() and by plotting routines. + "geopandas", + "healpix", + "pyproj", + "spatialpandas", +] +viz = [ + "cartopy", + "datashader", + "matplotlib<3.11", # matplotlib 3.11.0 breaks some plots but <3.11 is fine; see issue #1542. + "geoviews", + "holoviews", + "hvplot", +] [project.urls] Documentation = "https://uxarray.readthedocs.io/" Source = "https://github.com/UXARRAY/uxarray" Tracker = "https://github.com/UXARRAY/uxarray/issues" - +# please keep [project.urls] immediately after [project.optional-dependencies], +# or, if rearranging sections, make sure to edit installation.rst accordingly. [build-system] build-backend = "setuptools.build_meta" diff --git a/uxarray/plot/accessor.py b/uxarray/plot/accessor.py index e17bd4cf4..2f8bb56fd 100644 --- a/uxarray/plot/accessor.py +++ b/uxarray/plot/accessor.py @@ -472,6 +472,9 @@ def polygons( project=False, ) + # import datashader # no need to import explicitly, but gets used below when rasterize=True. + # (commented here for future reference, since datashader appears in uxarray dependency list, + # but it isn't imported explicitly anywhere in uxarray. For more details see PR #1548.) return gdf.hvplot.polygons( c=self._uxda.name if self._uxda.name is not None else "var", rasterize=rasterize,