diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..3e09a4a --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,5 @@ +version: 2 + +python: + version: "3.8" + system_packages: true diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html new file mode 100644 index 0000000..5b8f0ee --- /dev/null +++ b/docs/_templates/layout.html @@ -0,0 +1,5 @@ +{% extends "!layout.html" %} + +{% block extrahead %} + +{% endblock %} \ No newline at end of file diff --git a/docs/about.rst b/docs/about.rst deleted file mode 100644 index f227a08..0000000 --- a/docs/about.rst +++ /dev/null @@ -1,155 +0,0 @@ -.. _about: - -About psyplot -============= - -Why psyplot? ------------- -When visualizing data, one always has to choose: - -- Either create the plot with an intuitive graphical user interface (GUI) - (e.g. panoply) but less options for customization and difficult to script -- or create the plot from the command line, e.g. via NCL, R or python with more - possibilities for customization and scripting but also less intuitive - -``psyplot`` wants to combine these two worlds: create a well-documented and -easy accessible framework to visualize data from a GUI and the command line -(and of course through a script). - -There exists nothing like that. Of course you can also work with software like -Paraview_ via the built-in python shell. But, if you really want to explore your -data it is totally not straightforward to access and explore it from within -such a software using numeric functions from numpy, scipy, etc. - -Therefore I developed this modular framework that can create and customize plots -efficiently with short and comprehensive commands, that can be accessed -through a GUI (see :ref:`projects`) and where you have always a comprehensive -API to access your data. - -Different from the usual use with matplotlib, which in the end results most of -the time in copy-pasting parts of your code, this software is build on the -*don't repeat yourself* principle. Each of the small parts that make up a -visualization, whether it is part of the data evaluation or of the appearance -of the plot, psyplot puts it into a formatoption can be reused when it is -needed. - -Nevertheless, it's again a new piece of software. Therefore, if you want to use -it, for sure you need a bit of time to get comfortable with the framework. I -promise to you, it's worth it. So :ref:`get started ` and -please let me know if you have a different opinion. - -.. _matplotlib: http://matplotlib.org - - -.. _what-it-is-and-what-it-is-not: - -What it is, and what it is not ------------------------------- -.. note:: - - First of all, it's open source! So please, if you don't agree with the - points below, `edit this document`_ and click on *Propose File Change* and - *Create pull request*. We can then discuss your changes. - -.. _edit this document: https://github.com/psyplot/psyplot/edit/master/docs/about.rst - -There are tons of software tools around for visualization, so what is special -about psyplot? The following list should hopefully provide you some guidance. - -What it is -********** -- It is fast. Not necessarily when it comes down to being the fastest - interactive visualization software, but for sure when it comes down to - development time, as it is very user-friendly from the command line. There are - no other software packages that provide a simple and intuitive visualization - such as - - .. code-block:: python - - psy.plot.mapplot('my-netcdf-file.nc', lonlatbox='Germany') - - while still providing a very high range of flexible options to adjust the - visualization. No GUI, independent of it's intuitiveness, can ever beat the - speed of a scientist that knows a bit of coding and how to use the different - formatoptions in psyplot. -- it visualizes :ref:`unstructured grids `, - such as ICON or UGRID model data -- it automatically decodes CF-conventions -- it intuitively integrates the structure of netCDF files. So if you often - work with netCDF files, psyplot might be a good option -- it is pythonic. If you are using python anyway, psyplot is worth a try and we - are always keen to help new users getting started. -- it is very flexible (I think we made this point already), from command-line - and GUI. - - * We can implement tons of new visualization and data analysis techniques and - :ref:`you can implement your own `. - * they are automatically implemented in the GUI - * the user can do his statistical and numerical computations with software - like xarray, numpy, scipy, etc. and then use the psyplot visualization - methods in the same script - * its modular framework allows to tackle new scientific questions and handle - them in separate psyplot plugins with it's own formatoptions and - plotting methods -- it will always be free and open-source under the GPL License. - -What it is not -************** -No software can do everything, neither can psyplot. Our main focus on -flexibility, easy command-line usage and the GUI integration inevitably comes -with a few downsides. - -- it is not the fastest, because we use matplotlib to be flexible in our - visualization, and this runs on the CPU, rather than the GPU. But if - matplotlib or the standard visualization utilities from R, NCL, etc. are - sufficient for you, you can go with psyplot. -- it is not the best for interactive web-applications. Although it would be - pretty simple to set up a backend server with psyplot and tornado_ or Flask_, - for instance, it's limited to sending rastered image data around, due to the - `options provided by matplotlib`_. -- it is not as fast as ncview_. psyplot (and psy-view_ in particular) are - written in the dynamically interpreted python language (which allows the - combination of GUI and command-line, and the high flexibility). But we will - never beat the speed of the (compiled but less flexible) ncview software. -- our GUI is not the most interactive one. psyplot is a `command-line-first` - software, i.e. we put the most effort in making the usage from command-line - and scripts as easy as possible. The GUI is something on top and is limited by - the speed and functionalities of matplotlib (which is, nevertheless, pretty - rich). But we are constantly improving the GUI, see psy-view_ for instance. -- it is not made for statistical visualizations. We will never beat the - possibilities by packages like seaborn_ or R_. The only advantage of psy-reg_ - over these other software tools, is the possibility to adapt everything using - the full power of matplotlib artists within and outside of the psyplot - framework -- it is not the best software for manipulating shapefiles, although some support - of this might come in the future. - -.. _Paraview: https://www.paraview.org -.. _tornado: https://www.tornadoweb.org -.. _flask: https://flask.palletsprojects.com -.. _options provided by matplotlib: https://matplotlib.org/3.1.1/faq/howto_faq.html#how-to-use-matplotlib-in-a-web-application-server -.. _other visualization backends: https://github.com/psyplot/psy-vtk -.. _psy-view: https://github.com/psyplot/psy-view -.. _ncview: http://meteora.ucsd.edu/~pierce/ncview_home_page.html -.. _psy-reg: https://psyplot.readthedocs.io/projects/psy-reg -.. _seaborn: https://seaborn.pydata.org -.. _R: https://www.r-project.org/ - - -About the author ----------------- -I, (`Philipp Sommer`_), work as a Data Scientist at the -`Helmholtz-Zentrum Geesthacht, Centre for Materials and Coastal Research (HZG)` -(Germany) in the `Helmholtz Coastal Data Center (HCDC)`. Checkout my homepage -if you want to know more at philipp-s-sommer.de_ - -.. _Helmholtz Coastal Data Center (HCDC): https://hcdc.hzg.de -.. _Helmholtz-Zentrum Geesthacht, Centre for Materials and Coastal Research (HZG): https://hzg.de -.. _Philipp Sommer: http://www.philipp-s-sommer.de -.. _philipp-s-sommer.de: http://www.philipp-s-sommer.de - - -License -------- -psyplot is published under the -`GNU General Public License v2.0 `__ diff --git a/docs/accessors.rst b/docs/accessors.rst deleted file mode 100644 index 7720225..0000000 --- a/docs/accessors.rst +++ /dev/null @@ -1,212 +0,0 @@ -.. _accessors: - -.. currentmodule:: psyplot.data - -xarray Accessors -================ -psyplot defines a :class:`~xarray.DataArray` and a :class:`~xarray.Dataset` -accessor. You can use these accessors (see :ref:`xarray:internals`) to -visualize your data and to update your plots. The following sections will show -you how to make and update plots with these accessors. The plotmethods of the -accessors are the same as for the :class:`psyplot.project.plot` object. - -.. _dataset-accessor: - -The :class:`DatasetAccessor` dataset accessor ---------------------------------------------- -Importing the psyplot package registers a new dataset accessor (see -:func:`xarray.register_dataset_accessor`), the -:class:`DatasetAccessor`. You can access it via the ``psy`` -attribute of the :class:`~xarray.Dataset` class, i.e. - -.. autosummary:: - - xarray.Dataset.psy - -It can be used to visualize the variables in the dataset directly from the -dataset itself, e.g. - -.. ipython:: - :okwarning: - - In [1]: import psyplot - - In [2]: ds = psyplot.open_dataset('demo.nc') - - @savefig docs_dataset_accessor.png width=4in - In [3]: sp = ds.psy.plot.mapplot(name='t2m', cmap='Reds') - -The variable ``sp`` is a psyplot subproject of the current main project. - -.. ipython:: - - In [4]: print(sp) - - @suppress - In [4]: import psyplot.project as psy - ...: psy.close('all') - -Hence, it would be completely equivalent if you type - -.. ipython:: - :verbatim: - - In [5]: import psyplot.project as psyplot - - In [6]: sp = psy.plot.mapplot(ds, name='t2m', cmap='Reds') - -Note that the :attr:`DatasetAccessor.plot` attribute has the -same plotmethods as the :attr:`psyplot.project.plot` instance. - - -.. _dataarray-accessor: - -The :class:`InteractiveArray` dataarray accessor ------------------------------------------------- -More advanced then the :ref:`dataset accessor ` is the -registered DataArray accessor, the :class:`InteractiveArray`. - -As well as the :class:`DatasetAccessor`, it is registered as the ``'psy'`` -attribute of any :class:`~xarray.DataArray`, i.e. - -.. autosummary:: - - xarray.DataArray.psy - -You can use it for two things: - -1. create plots of the array -2. update the plots and the array - -.. _dataarray-accessor-plot: - -Creating plots with the dataarray accessor -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Just use the :attr:`~psyplot.data.InteractiveBase.plot` attribute the accessor. - -.. ipython:: - - In [1]: import psyplot - - In [2]: ds = psyplot.open_dataset('demo.nc') - - In [3]: da = ds.t2m[0, 0] - - # this is a two dimensional array - In [4]: print(da) - - # and we can plot it using the mapplot plot method - @savefig docs_dataarray_accessor_1.png width=4in - In [5]: plotter = da.psy.plot.mapplot() - - @suppress - In [6]: import matplotlib.pyplot as plt - ...: plt.close('all') - -The resulting plotter, an instance of the :class:`psyplot.plotter.Plotter` -class, is the object that visualizes the data array. It can also -be accessed via the ``da.psy.plotter`` attribute. Note that the creation of -such a plotter overwrites any previous plotter in the ``da.psy.plotter`` -attribute. - -This methodology does not only work for :class:`DataArrays `, -but also for multiple DataArrays in a :class:`InteractiveList`. This data -structure is, for example, used by the -:attr:`psy_simple:psyplot.project.plot.lineplot` plot method to visualize -multiple lines. Consider the following example: - -.. ipython:: - - In [7]: ds0 = ds.isel(lev=0) # select a subset of the dataset - - # create a list of arrays at different longitudes - In [8]: l = psyplot.InteractiveList([ - ...: ds0.t2m.sel(lon=2.35, lat=48.86, method='nearest'), # Paris - ...: ds0.t2m.sel(lon=13.39, lat=52.52, method='nearest'), # Berlin - ...: ds0.t2m.sel(lon=-74.01, lat=40.71, method='nearest'), # NYC - ...: ]) - - In [9]: l.arr_names = ['Paris', 'Berlin', 'NYC'] - - # plot the list - @savefig docs_dataarray_accessor_2.png width=4in - In [10]: plotter = l.psy.plot.lineplot(xticks='data', xticklabels='%B') - - @suppress - In [10]: import matplotlib.pyplot as plt - ....: plt.close('all') - -Note that for the :class:`InteractiveList`, the :attr:`~InteractiveList.psy` -attribute is just the list it self. So it would have been equivalent to call - -.. ipython:: - :verbatim: - - In [11]: l.plot.lineplot() - -.. _dataarray-accessor-update: - -Updating plots and arrays with the dataarray accessor -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The :class:`InteractiveArray` accessor is designed for interactive usage of, -not only the matplotlib figures, but also of the data. If you selected a -subset of a dataset, e.g. via - -.. ipython:: - - In [1]: da = ds.t2m[0, 0] - ...: print(da.time) # January 1979 - -You can change to a different slice using the :meth:`InteractiveArray.update` -method. - -.. ipython:: - - In [2]: da.psy.base = ds # tell psyplot the source of the dataarray - - In [3]: da.psy.update(time=2) - ...: print(da.time) # changed to March 1979 - -The ``da.psy.base = ds`` command hereby tells the dataarray, where it is -coming from, since this information is not known in the standard -xarray framework. - -.. hint:: - - You can avoid this, using the :meth:`DatasetAccessor.create_list` method - of the dataset accessor - - .. ipython:: - - In [4]: da = ds.psy.create_list(time=0, lev=0, name='t2m')[0] - ...: print(da.psy.base is ds) - -If you plotted the data, you can also change the formatoptions using the -:meth:`~InteractiveArray.update` method, e.g. - -.. ipython:: - - # create plot - @savefig docs_dataarray_accessor_3.png width=4in - In [5]: da.psy.plot.mapplot(); - -.. ipython:: - - @savefig docs_dataarray_accessor_4.png width=4in - In [6]: da.psy.update(cmap='Reds') - - @suppress - In [6]: import matplotlib.pyplot as plt - ...: plt.close('all') - -The same holds for the Interactive list - -.. ipython:: - - @suppress - In [6]: plotter = l.psy.plot.lineplot(xticks='data', xticklabels='%B') - - @savefig docs_dataarray_accessor_5.png width=4in - In [7]: l.update(time=slice(1, 4), # change the data by selecting a subset of the timeslice - ...: title='Subset', # change a formatoption, the title of the plot - ...: ) diff --git a/docs/changelog.rst b/docs/changelog.rst deleted file mode 100644 index c393d07..0000000 --- a/docs/changelog.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _changelog: - -Changelog -********* - -.. include:: ../CHANGELOG.rst diff --git a/docs/command_line.rst b/docs/command_line.rst deleted file mode 100644 index 8a31397..0000000 --- a/docs/command_line.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. highlight:: bash - -.. _command-line: - -Command line usage -================== -The :mod:`psyplot.__main__` module defines a simple parser to parse commands -from the command line to make a plot of data in a netCDF file. Note that the -arguments change slightly if you have the ``psyplot-gui`` module installed -(see :ref:`psyplot-gui ` documentation). - -It can be run from the command line via:: - - python -m psyplot [options] [arguments] - -or simply:: - - psyplot [options] [arguments] - -.. argparse:: - :module: psyplot.__main__ - :func: get_parser - :prog: psyplot diff --git a/docs/conf.py b/docs/conf.py index 6b0ffca..151f025 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,315 +1,57 @@ -# -*- coding: utf-8 -*- +# Configuration file for the Sphinx documentation builder. # -# psyplot documentation build configuration file, created by -# sphinx-quickstart on Mon Jul 20 18:01:33 2015. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. # -# All configuration values have a default; values that are commented out -# serve to show the default. +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) -import sphinx -import os -import os.path as osp -import sys -import re -import six -import subprocess as spr -from itertools import product -import warnings -import sphinx_rtd_theme -import json -import logging -if six.PY2: - from urllib import urlopen -else: - from urllib.request import urlopen +# -- Project information ----------------------------------------------------- -# make sure, psyplot from parent directory is used -sys.path.insert(0, os.path.abspath('..')) -import psyplot -from psyplot.plotter import Formatoption, Plotter +project = 'psyplot' +copyright = '2021, Philipp S. Sommer' +author = 'Philipp S. Sommer' -# automatically import all plotter classes -psyplot.rcParams['project.auto_import'] = True -# include links to the formatoptions in the documentation of the -# :attr:`psyplot.project.ProjectPlotter` methods -Plotter.include_links(True) +# The full version, including alpha/beta/rc tags +release = '1.3.1' -warnings.filterwarnings('ignore', message="axes.color_cycle is deprecated") -warnings.filterwarnings( - 'ignore', message=("This has been deprecated in mpl 1.5,")) -warnings.filterwarnings('ignore', message="invalid value encountered in ") -warnings.filterwarnings('ignore', message=r"\s*examples.directory") -warnings.filterwarnings('ignore', message='numpy.dtype size changed') -warnings.filterwarnings( - 'ignore', message='Using an implicitly registered datetime converter') -warnings.filterwarnings( - 'ignore', message=r"\s*The on_mappable_changed function") -# -- General configuration ------------------------------------------------ +# -- General configuration --------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx.ext.doctest', - 'sphinx.ext.intersphinx', - 'sphinx.ext.autosummary', - 'sphinx.ext.todo', - 'sphinx.ext.viewcode', - 'sphinx.ext.extlinks', - 'matplotlib.sphinxext.plot_directive', - 'IPython.sphinxext.ipython_console_highlighting', - 'IPython.sphinxext.ipython_directive', - 'sphinxarg.ext', - 'psyplot.sphinxext.extended_napoleon', - 'autodocsumm', - 'sphinx_nbexamples', - 'sphinx.ext.imgconverter', ] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] -# on_rtd is whether we are on readthedocs.org, this line of code grabbed from -# docs.readthedocs.org -on_rtd = os.environ.get('READTHEDOCS', None) == 'True' - -# process the examples if they don't exist already -process_examples = ( - not osp.exists(osp.join(osp.dirname(__file__), 'examples')) or on_rtd) - -if on_rtd: - spr.call([sys.executable] + - ('-m ipykernel install --user --name python3 ' - '--display-name python3').split()) - -# create the api documentation -if not osp.exists(osp.join(osp.dirname(__file__), 'api')) or on_rtd: - spr.check_call(['bash', 'apigen.bash']) - -# The cdo example would require the installation of climate data operators -# which is a bit of an overkill -example_gallery_config = dict( - dont_preprocess=['../examples/example_cdo.ipynb'], - urls='https://github.com/psyplot/psyplot/blob/master/examples', - binder_url='https://mybinder.org/v2/gh/Chilipp/psyplot/master?filepath=examples', - ) - -napoleon_use_admonition_for_examples = True - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -source_suffix = '.rst' - -# The master toctree document. -master_doc = 'index' - -autodoc_default_options = { - 'show_inheritance': True, - 'autosummary': True, -} - -autoclass_content = 'both' - -not_document_data = ['psyplot.config.rcsetup.defaultParams', - 'psyplot.config.rcsetup.rcParams'] - -ipython_savefig_dir = os.path.join(os.path.dirname(__file__), '_static') - -# General information about the project. -project = 'psyplot' -copyright = psyplot.__copyright__ -author = psyplot.__author__ - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = re.match('\d+\.\d+\.\d+', psyplot.__version__).group() -# The full version, including alpha/beta/rc tags. -release = psyplot.__version__ - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = None - # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['_build'] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = True +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] +# The master toctree document. +master_doc = 'index' -# -- Options for HTML output ---------------------------------------------- +# -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'sphinx_rtd_theme' -html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] - -# Add any paths that contain custom static files (such as style sheets) -# here, relative to this directory. They are copied after the builtin -# static files, so a file named "default.css" will overwrite the builtin -# "default.css". -html_static_path = ['_static'] - -# otherwise, readthedocs.org uses their theme by default, so no need to specify - -# Output file base name for HTML help builder. -htmlhelp_basename = 'psyplotdoc' - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -html_logo = '_static/psyplot.png' - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -html_favicon = '_static/psyplot.ico' - -# Custom sidebar templates, maps document names to template names. -html_sidebars = { - 'index': ['sidebarlogo.html', 'sidebarusefullinks.html', 'searchbox.html'], - '**': ['sidebarlogo.html', 'relations.html', 'searchbox.html', - 'localtoc.html', 'sidebarusefullinks.html'] -} - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { - # Additional stuff for the LaTeX preamble. - 'preamble': '\setcounter{tocdepth}{10}' -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, 'psyplot.tex', u'psyplot Documentation', - author, 'manual'), -] - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'psyplot', u'psyplot Documentation', - [author], 1) -] - - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - (master_doc, 'psyplot', u'psyplot Documentation', - author, 'psyplot', 'Python framework for interactive data documentation', - 'Miscellaneous'), -] - - -# -- Options for Epub output ---------------------------------------------- - -# Bibliographic Dublin Core info. -epub_title = project -epub_author = author -epub_publisher = author -epub_copyright = copyright - -# A list of files that should not be packed into the epub file. -epub_exclude_files = ['search.html'] - -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = { - 'pandas': ('https://pandas.pydata.org/pandas-docs/stable/', None), - 'numpy': ('https://numpy.org/doc/stable/', None), - 'matplotlib': ('https://matplotlib.org/', None), - 'seaborn': ('http://seaborn.pydata.org/', None), - 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), - 'xarray': ('http://xarray.pydata.org/en/stable/', None), - 'cartopy': ('https://scitools.org.uk/cartopy/docs/latest/', None), - 'mpl_toolkits': ('https://matplotlib.org/basemap/', None), - 'sphinx_nbexamples': ('https://sphinx-nbexamples.readthedocs.io/en/latest/', - None), - 'psy_maps': ( - 'https://psyplot.readthedocs.io/projects/psy-maps/en/latest/', None), - 'psy_simple': ( - 'https://psyplot.readthedocs.io/projects/psy-simple/en/latest/', None), - 'psy_reg': ('https://psyplot.readthedocs.io/projects/psy-reg/en/latest/', - None), - 'psyplot_gui': ( - 'https://psyplot.readthedocs.io/projects/psyplot-gui/en/latest/', None), - 'psy_view': ( - 'https://psyplot.readthedocs.io/projects/psy-view/en/latest/', None), -} -if six.PY3: - intersphinx_mapping['python'] = ('https://docs.python.org/3.8/', None) -else: - intersphinx_mapping['python'] = ('https://docs.python.org/2.7/', None) - - -replacements = { - '`psyplot.rcParams`': '`~psyplot.config.rcsetup.rcParams`', - '`psyplot.InteractiveList`': '`~psyplot.data.InteractiveList`', - '`psyplot.InteractiveArray`': '`~psyplot.data.InteractiveArray`', - '`psyplot.open_dataset`': '`~psyplot.data.open_dataset`', - '`psyplot.open_mfdataset`': '`~psyplot.data.open_mfdataset`', - } - - -def link_aliases(app, what, name, obj, options, lines): - for (key, val), (i, line) in product(six.iteritems(replacements), - enumerate(lines)): - lines[i] = line.replace(key, val) - - -fmt_attrs_map = { - 'Interface to other formatoptions': [ - 'children', 'dependencies', 'connections', 'parents', - 'shared', 'shared_by'], - 'Formatoption intrinsic': [ - 'value', 'value2share', 'value2pickle', 'default', 'validate'], - 'Interface for the plotter': [ - 'lock', 'diff', 'set_value', 'check_and_set', 'initialize_plot', - 'update', 'share', 'finish_update', 'remove', 'changed', 'plotter', - 'priority', 'key', 'plot_fmt', 'update_after_plot', - 'requires_clearing', 'requires_replot'], - 'Interface to the data': ['data_dependent', 'index_in_list', 'project', - 'ax', 'raw_data', 'decoder', 'any_decoder', - 'data', 'iter_data', 'iter_raw_data', - 'set_data', 'set_decoder'], - 'Information attributes': ['group', 'name', 'groupname', 'default_key'], - 'Miscellaneous': ['init_kwargs', 'logger'], -} - - -def group_fmt_attributes(app, what, name, obj, section, parent): - if parent is Formatoption: - return next( - (group for group, val in fmt_attrs_map.items() if name in val), - None) - +# +html_theme = 'alabaster' -def setup(app): - app.connect('autodoc-process-docstring', link_aliases) - app.connect('autodocsumm-grouper', group_fmt_attributes) - return {'version': sphinx.__display_version__, 'parallel_read_safe': True} +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] \ No newline at end of file diff --git a/docs/configuration.rst b/docs/configuration.rst deleted file mode 100644 index f9b356e..0000000 --- a/docs/configuration.rst +++ /dev/null @@ -1,100 +0,0 @@ -.. _configuration: - -Configuration -============= - -The ``rcParams`` ----------------- - -.. hint:: - - If you are using the :ref:`psyplot-gui ` module, - you can also use the preferences widget to modify the configuration. See - :ref:`psyplot_gui:configuration`. - -Psyplot, and especially it's plugins have a lot of configuration values. -Our rcParams handling is motivated by -:ref:`matplotlib ` although we extended the -possibilities of it's :class:`matplotlib.RcParams` class. Our rcParams -are stored in the :attr:`psyplot.rcParams ` -object. Without any plugins, this looks like - -.. ipython:: - - @verbatim - In [1]: from psyplot import rcParams - - @suppress - In [1]: # is not shown because we have to disable the plugins - ...: from psyplot.config.rcsetup import RcParams, defaultParams_orig - ...: rcParams = RcParams(defaultParams=defaultParams_orig) - ...: rcParams.update_from_defaultParams() - - In [2]: print(rcParams.dump(exclude_keys=[])) - -You can use this object like a dictionary and modify the default values. For -example, if you do not want, that the seaborn_ package is imported when the -:mod:`psyplot.project` module is imported, you can simply do this via: - -.. ipython:: - - In [3]: rcParams['project.import_seaborn'] = False - -Additionally, you can make these changes permanent. At every first import of -the ``psyplot`` module, the rcParams are updated from a yaml configuration -file. On Linux and OS X, this is stored under -``$HOME/.config/psyplot/psyplotrc.yml``, under Windows it is stored at -``$HOME/.psyplot/psyplotrc.yml``. But use the -:func:`psyplot.config.rcsetup.psyplot_fname` function, to get the correct -location. - -To make our changes from above permanent, we could just do: - -.. ipython:: - - In [4]: import yaml - ...: from psyplot.config.rcsetup import psyplot_fname - - In [5]: with open(psyplot_fname(if_exists=False), 'w') as f: - ...: yaml.dump({'project.import_seaborn': False}, f) - - # or we use the dump method - In [6]: rcParams.dump(psyplot_fname(if_exists=False), - ...: overwrite=True, # update the existing file - ...: include_keys=['project.import_seaborn']) - -Default formatoptions ---------------------- - -The psyplot plugins, (:mod:`psy_simple.plugin`, :mod:`psy_maps.plugin`, etc.) -define their own :data:`~psy_simple.plugin.rcParams` instance. When the plugins -are loaded at the first import of ``psyplot``, these instances update -:attr:`psyplot.rcParams `. - -The update mainly defines the default values for the plotters defined by that -plugin. However, it is not always obvious, which key in the -:attr:`psyplot.rcParams ` belongs to which -formatoption. For this purpose, however, you can use the -:attr:`~psyplot.plotter.Formatoption.default_key` attribute. For example, -the :attr:`title ` formatoption has the -default_key - -.. ipython:: - - In [7]: import psyplot.project as psy - - In [8]: plotter = psy.plot.lineplot.plotter_cls() - ...: plotter.title.default_key - -As our plotters are based on inheritance, the default values use it, too. -Therefore, the :class:`~psy_maps.plotters.FieldPlotter`, the underlying plotter -for the :attr:`~psyplot.Project.ProjectPlotter.mapplot` plot method, uses the -same configuration value in the -:attr:`psyplot.rcParams `: - -.. ipython:: - - In [9]: plotter = psy.plot.mapplot.plotter_cls() - ...: plotter.title.default_key - -.. _seaborn: http://seaborn.pydata.org/ diff --git a/docs/contribute.rst b/docs/contribute.rst deleted file mode 100644 index be502e5..0000000 --- a/docs/contribute.rst +++ /dev/null @@ -1,265 +0,0 @@ -.. _how-to-contribute: - -Contributing to psyplot -======================= - -First off, thanks for taking the time to contribute! - -The following is a set of guidelines for contributing to psyplot and its -packages, which are hosted on GitHub. These are mostly guidelines, not -rules. Use your best judgment, and feel free to propose changes to this -document in a pull request. - -.. contents:: Table of Contents - -Code of Conduct ---------------- - -This project and everyone participating in it is governed by the -`psyplot Code of Conduct `__. -By participating, you are expected to uphold this code. - -What should I know before I get started? ----------------------------------------- - -The psyplot framework -~~~~~~~~~~~~~~~~~~~~~ - -``psyplot`` is just the framework that allows interactive data analysis -and visualization. Much of the functionality however is implemented by -other packages. What package is the correct one for your bug -report/feature request, can be determined by the following list - -- `psyplot-gui `__: - Everything specific to the graphical user interface -- `psy-view `__: - Everything specific to the psy-view graphical user interface -- `psy-simple `__: - Everything concerning, e.g. the ``lineplot``, ``plot2d``, ``density`` - or ``vector`` plot methods -- `psy-maps `__: Everything - concerning, e.g. the ``mapplot``, ``mapvector`` ``mapcombined`` plot - methods -- `psy-reg `__: Everything - concerning, e.g. the ``linreg`` or ``densityreg`` plot methods -- `psyplot `__: Everything - concerning the general framework, e.g. data handling, parallel - update, etc. - -Concerning plot methods, you can simply find out which module -implemented it via - -.. code:: python - - import psyplot.project as psy - print(psy.plot.name-of-your-plot-method._plugin) - -If you still don’t know, where to open the issue, just go for -`psyplot `__. - -How Can I Contribute? ---------------------- - -Reporting Bugs -~~~~~~~~~~~~~~ - -This section guides you through submitting a bug report for psyplot. -Following these guidelines helps maintainers and the community -understand your report, reproduce the behavior, and find related -reports. - -Before creating bug reports, please check existing issues and pull -requests as you might find out that you don’t need to create one. When -you are creating a bug report, please `include as many details as -possible <#how-do-i-submit-a-good-bug-report>`__. Fill out `the required -template `__, the information it asks for -helps us resolve issues faster. - - **Note:** If you find a **Closed** issue that seems like it is the - same thing that you’re experiencing, open a new issue and include a - link to the original issue in the body of your new one. - -How Do I Submit A (Good) Bug Report? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Bugs are tracked as `GitHub -issues `__. After you’ve -determined `which repository <#the-psyplot-framework>`__ your bug is -related to, create an issue on that repository and provide the following -information by filling in `the template `__. - -Explain the problem and include additional details to help maintainers -reproduce the problem: - -- **Use a clear and descriptive title** for the issue to identify the - problem. -- **Describe the exact steps which reproduce the problem** in as many - details as possible. For example, start by explaining how you started - psyplot, e.g. which command exactly you used in the terminal, or how - you started psyplot otherwise. When listing steps, **don’t just say - what you did, but explain how you did it**. For example, did you - update via GUI or console and what? -- **Provide specific examples to demonstrate the steps**. Include links - to files or GitHub projects, or copy/pasteable snippets, which you - use in those examples. If you’re providing snippets in the issue, use - `Markdown code - blocks `__. -- **Describe the behavior you observed after following the steps** and - point out what exactly is the problem with that behavior. -- **Explain which behavior you expected to see instead and why.** -- **Include screenshots and animated GIFs** which show you following - the described steps and clearly demonstrate the problem. You can use - `this tool `__ to record GIFs on - macOS and Windows, and `this - tool `__ or `this - tool `__ on Linux. -- **If the problem is related to your data structure**, include a small - example how a similar data structure can be generated - -Include details about your configuration and environment: - -- **Which version of psyplot are you using?** You can get the exact - version by running ``psyplot -aV`` in your terminal, or by starting - the psyplot-gui and open Help->Dependencies. -- **What’s the name and version of the OS you’re using**? - -Suggesting Enhancements -~~~~~~~~~~~~~~~~~~~~~~~ - -This section guides you through submitting an enhancement suggestion for -psyplot, including completely new features and minor improvements to -existing functionality. - -If you want to change an existing feature, use the `change feature -template `__, -otherwise fill in the `new feature -template `__. - -How Do I Submit A (Good) Enhancement Suggestion? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Enhancement suggestions are tracked as `GitHub -issues `__. After you’ve -determined `which repository <#the-psyplot-framework>`__ your -enhancement suggestion is related to, create an issue on that repository -and provide the following information: - -- **Use a clear and descriptive title** for the issue to identify the - suggestion. -- **Provide a step-by-step description of the suggested enhancement** - in as many details as possible. -- **Provide specific examples to demonstrate the steps**. Include - copy/pasteable snippets which you use in those examples, as `Markdown - code - blocks `__. -- **Describe the current behavior** and **explain which behavior you - expected to see instead** and why. -- **Include screenshots and animated GIFs** which help you demonstrate - the steps or point out the part of psyplot which the suggestion is - related to. You can use `this - tool `__ to record GIFs on macOS and - Windows, and `this - tool `__ or `this - tool `__ on Linux. -- **Explain why this enhancement would be useful** to most psyplot - users. -- **List some other analysis software or applications where this - enhancement exists.** -- **Specify which version of psyplot you’re using.** You can get the - exact version by running ``psyplot -aV`` in your terminal, or by - starting the psyplot-gui and open Help->Dependencies. -- **Specify the name and version of the OS you’re using.** - -Pull Requests -~~~~~~~~~~~~~ - -- Fill in `the required template `__ -- Do not include issue numbers in the PR title -- Include screenshots and animated GIFs in your pull request whenever - possible. -- Document new code based on the `Documentation - Styleguide <#documentation-styleguide>`__ -- End all files with a newline and follow the - `PEP8 `__, e.g. by using - `flake8 `__ - -Adding new examples -~~~~~~~~~~~~~~~~~~~ - -You have new examples? Great! If you want to add them to the -documentation, please just fork the correct github repository and add a -jupyter notebook in the `examples `__ directory, together with -all the necessary data files. - -To build our docs, we use the -`sphinx-nbexamples `__ -package to convert the examples to reStructuredText. Therefore please -make sure that your supplementary data files are correctly implemented -in the meta data of the notebook. - -We are, however, also willing to help you finalizing incomplete pull -requests. - -Styleguides ------------ - -Git Commit Messages -~~~~~~~~~~~~~~~~~~~ - -- Use the present tense (“Add feature” not “Added feature”) -- Use the imperative mood (“Move cursor to…” not “Moves cursor to…”) -- Limit the first line (summary) to 72 characters or less -- Reference issues and pull requests liberally after the first line -- When only changing documentation, include ``[ci skip]`` in the commit - title - -Documentation Styleguide -~~~~~~~~~~~~~~~~~~~~~~~~ - -- Follow the `numpy documentation - guidelines `__. -- Use - `reStructuredText `__. -- Try to not repeat yourself and make use of the - ``psyplot.docstring.docstrings`` - -Example -^^^^^^^ - -.. code:: python - - @docstrings.get_sections(base='new_function') - def new_function(a=1): - """Make some cool new feature - - This function implements a cool new feature - - Parameters - ---------- - a: int - First parameter - - Returns - ------- - something awesome - The result""" - ... - - @docstrings.dedent - def another_new_function(a=1, b=2): - """Make another cool new feature - - Parameters - ---------- - %(new_function.parameters)s - b: int - Another parameter - - Returns - ------- - Something even more awesome""" - ... - -.. note:: - - This document has been inspired by `the contribution guidelines of Atom `__ diff --git a/docs/develop/framework.rst b/docs/develop/framework.rst deleted file mode 100644 index 292ab9b..0000000 --- a/docs/develop/framework.rst +++ /dev/null @@ -1,288 +0,0 @@ -.. _framework: - -The psyplot framework -===================== -.. only:: html - - .. image:: psyplot_framework.gif - -.. only:: latex - - .. image:: psyplot_framework.png - -The main module we used so far, was the :mod:`psyplot.project` module. It is -the end of a whole framework that is setup by the psyplot package. - -This framework is designed in analogy to matplotlibs -`figure - axes - artist setup `__, -where one figure controls multiple axes, an axes is the manager of multiple -artists (e.g. a simple line) and each artist is responsible for visualizing one -or more objects on the plot. The psyplot framework instead is defined through -the :class:`~psyplot.project.Project` - -(:class:`~psyplot.data.InteractiveBase` - :class:`~psyplot.plotter.Plotter`) - -:class:`~psyplot.plotter.Formatoption` relationship. - -The last to parts in this framework, the :class:`~psyplot.plotter.Plotter` and -:class:`~psyplot.plotter.Formatoption`, are only defined through abstract base -classes in this package. They are filled with contents in plugins such as the -psy-simple_ or the psy-maps_ plugin (see :ref:`plugins`). - -.. _psy-simple: https://psy-simple.readthedocs.io/en/latest -.. _psy-maps: https://psy-maps.readthedocs.io/en/latest - - -.. _project_framework: - -The :func:`~psyplot.project.project` function ---------------------------------------------- - -.. currentmodule:: psyplot.project - -The :class:`psyplot.project.Project` class (in analogy to matplotlibs -:class:`~matplotlib.figure.Figure` class) is basically a list that controls -multiple plot objects. It comprises the full functionality of the package and -packs it into one class, the :class:`~psyplot.project.Project` class. - -In analogy to pyplots :func:`~matplotlib.pyplot.figure` function, a new project -can simply be created via - -.. ipython:: - - In [1]: import psyplot.project as psy - - In [2]: p = psy.project() - -This automatically sets ``p`` to be the current project which can be accessed -through the :func:`gcp` method. You can also set the current -project by using the :func:`scp` function. - -.. note:: - - We highly recommend to use the :func:`project` function to create new - projects instead of creating projects from the :class:`Project`. This - ensures the right numbering of the projects of old projects. - -The project uses the plotters from the :mod:`psyplot.plotter` module to -visualize your data. Hence you can add new plots and new data to the project by -using the :attr:`Project.plot` attribute or the :attr:`psyplot.project.plot` -attribute which targets the current project. The return types of the plotting -methods are again instances of the :class:`Project` class, however we consider -them as *subprojects* in contrast *main projects* that are created through the -:func:`project` function. There is basically no difference but the result of the -:attr:`Project.is_main` attribute which is ``False`` for subprojects. Hence, -each new plot creates a subproject but also stores the data array in the -corresponding main project of the :class:`Project` instance from which the plot -method has been called. The newly created subproject can be accessed via - -.. ipython:: - - In [3]: sp = psy.gcp() - -whereas the current main project can be accessed via - -.. ipython:: - - In [4]: p = psy.gcp(main=True) - -Plots created by a specific method of the :attr:`Project.plot` attribute may -however be accessed via the corresponding attribute of the :class:`Project` -class. The following example creates three subprojects, two with the -:attr:`~ProjectPlotter.mapplot` and :attr:`~ProjectPlotter.mapvector` methods -from the psy-maps_ plugin and one with the simple -:attr:`~ProjectPlotter.lineplot` method from the psy-simple_ plugin to visualize -simple lines. - - -.. ipython:: - - In [5]: import matplotlib.pyplot as plt - - In [6]: import cartopy.crs as ccrs - - # the subplots for the maps (need cartopy projections) - In [7]: ax = list(psy.multiple_subplots(2, 2, n=3, for_maps=True)) - - # the subplot for the line plot - In [8]: ax.append(plt.gcf().add_subplot(2, 2, 4)) - - # scalar field of the zonal wind velocity in the file demo.nc - In [5]: psy.plot.mapplot('demo.nc', name='u', ax=ax[0], clabel='{desc}') - - # a second scalar field of temperature - In [6]: psy.plot.mapplot('demo.nc', name='t2m', ax=ax[1], clabel='{desc}') - - # a vector plot projected on the earth - In [7]: psy.plot.mapvector('demo.nc', name=[['u', 'v']], ax=ax[2], - ...: attrs={'long_name': 'Wind speed'}) - - @savefig docs_framework_project_demo1.png width=4in - In [8]: psy.plot.lineplot('demo.nc', name='t2m', x=0, y=0, z=range(4), - ...: ax=ax[3], xticklabels='%b %d', ylabel='{desc}', - ...: legendlabels='%(zname)s = %(z)s %(zunits)s') - -The latter is now the current subproject we could access via -:func:`psy.gcp() `. However we can access all of them through the main -project - -.. ipython:: - - In [9]: mp = psy.gcp(True) - - In [10]: mp # all arrays - - In [11]: mp.mapplot # all scalar fields - - In [12]: mp.mapvector # all vector plots - - In [13]: mp.maps # all data arrays that are plotted on a map - - In [14]: mp.lineplot # the simple plot we created - -The advantage is, since every plotter has different formatoptions, we can -now update them very easily. For example lets update the arrowsize to -1 (which only works for the :attr:`~Project.mapvector` plots), the projection -to an orthogonal (which only works for :attr:`~Project.maps`), the simple -plots to use the ``'viridis'`` colormap for color coding the lines and for all -we choose their title corresponding to the variable names - -.. ipython:: - - @suppress - In [15]: with p.maps.no_auto_update: - ....: p.maps.update(grid_labels=False) - - In [15]: p.maps.update(projection='ortho') - - In [16]: p.mapvector.update(color='r', plot='stream', lonlatbox='Europe') - - In [17]: p.lineplot.update(color='viridis') - - @savefig docs_framework_project_demo2.png width=4in - In [18]: p.update(title='%(long_name)s') - - @suppress - In [19]: psy.close('all') - - -The :class:`~psyplot.data.InteractiveBase` and the :class:`~psyplot.plotter.Plotter` classes --------------------------------------------------------------------------------------------- - -.. currentmodule:: psyplot.plotter - -Interactive data objects -^^^^^^^^^^^^^^^^^^^^^^^^ - -The next level are instances of the -:class:`~psyplot.data.InteractiveBase` class. This abstract base -class provides an interface between the data and the visualization. Hence a -plotter (that's how we call instances of the :class:`Plotter` class) will deal -with the subclasses of the :class:`~psyplot.data.InteractiveBase`: - -.. autosummary:: - - ~psyplot.data.InteractiveArray - ~psyplot.data.InteractiveList - -Those classes (in particular the :class:`~psyplot.data.InteractiveArray`) keep -the reference to the base dataset to allow the update of the dataslice you are -plotting. The :class:`~psyplot.data.InteractiveList` class can be used in a -plotter for the visualization of multiple -:class:`~psyplot.data.InteractiveArray` instances (see for example the -:class:`psyplot.plotter.simple.LinePlotter` and -:class:`psyplot.plotter.maps.CombinedPlotter` classes). -Furthermore those data instances have a -:attr:`~psyplot.data.InteractiveBase.plotter` attribute that is usually -occupied by an instance of a :class:`Plotter` subclass. - -.. note:: - - The :class:`~psyplot.data.InteractiveArray` serves as a - :class:`~xarray.DataArray` accessor. After you imported psyplot, you can - access it via the ``psy`` attribute of a :class:`~xarray.DataArray`, i.e. - via - - .. ipython:: - - In [1]: import xarray as xr - - In [2]: xr.DataArray([]).psy - -Visualization objects -^^^^^^^^^^^^^^^^^^^^^ -Each plotter class is the coordinator of several visualization options. -Thereby the :class:`~psyplot.plotter.Plotter` class itself contains only -the structural functionality for managing the formatoptions that do the -real work. The plotters for the real usage are defined in plugins like the -psy-simple_ or the psy-maps_ package. - -Hence each :class:`~psyplot.data.InteractiveBase` instance is visualized by -exactly one :class:`Plotter` class. If you don't want to use the -:ref:`project framework `, the initialization of such an -instance nevertheless straight forward. Just open a dataset, extract the right -data array and plot it - -.. ipython:: - - In [1]: from psyplot import open_dataset - - In [2]: from psy_maps.plotters import FieldPlotter - - In [3]: ds = open_dataset('demo.nc') - - In [4]: arr = ds.t2m[0, 0] - - @savefig docs_framework_plotter_demo.png width=4in - In [5]: plotter = FieldPlotter(arr) - -Now we created a plotter with all it's formatoptions: - -.. ipython:: - - In [6]: type(plotter), plotter - -You can use the :meth:`~Plotter.show_keys`, :meth:`~Plotter.show_summaries` and -:meth:`~Plotter.show_docs` methods to have a look into the documentation into -the formatoptions or you simply use the builtin :func:`help` function for it:: - - >>> help(plotter.clabel) - -The update methods are the same as for the :class:`~psyplot.project.Project` -class. You can use the :meth:`psyplot.data.InteractiveArray.update` via -``arr.psy.update()`` which updates the data and forwards the formatoptions to -the :meth:`Plotter.update` method. - -.. note:: - - Plotters are subclasses of dictionaries where each item represents the - key-value pair of one formatoption. Anyway, although you could now simply - set a formatoption like you set an item for a dictionary via - - .. ipython:: - - In [7]: plotter['clabel'] = 'my label' - - or equivalently - - .. ipython:: - - In [7]: plotter.clabel = 'my label' - - this would not change the plot! Instead you have to use the - :meth:`psyplot.plotter.Plotter.update` method, i.e. - - .. ipython:: - - In [7]: plotter.update(clabel='my label') - - @suppress - In [8]: plt.close('all') - -Formatoptions -------------- -Formatoptions are the core of the visualization in the psyplot framework. They -conceptually correspond to the basic :class:`matplotlib.artist.Artist` and -inherit from the abstract :class:`Formatoption` class. Each -plotter is set up through it's formatoptions where each formatoption has a -unique formatoption key inside the plotter. This formatoption key (e.g. 'title' -or 'clabel') is what is used for updating the plot etc. You can find more -information in :ref:`plugins_guide` . diff --git a/docs/develop/index.rst b/docs/develop/index.rst deleted file mode 100644 index 845f369..0000000 --- a/docs/develop/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _developers-guide: - -Developers guide -================ -In this section we provide a deeper overview and introduction in the psyplot -frameworks that is necessary for creating new plugins. - -.. toctree:: - :maxdepth: 1 - - framework - plugins_guide diff --git a/docs/develop/plugins_guide.rst b/docs/develop/plugins_guide.rst deleted file mode 100644 index 977f7e6..0000000 --- a/docs/develop/plugins_guide.rst +++ /dev/null @@ -1,497 +0,0 @@ -.. _plugins_guide: - -How to implement your own plotters and plugins -============================================== -New plotters and plugins to the psyplot framework are highly welcomed. In this -guide, we present :ref:`how to create new plotters ` and explain -to you how you can :ref:`include them as a plugin in psyplot `. - -.. _new_plotters: - -Creating plotters ------------------ - -.. currentmodule:: psyplot.plotter - -Implementing new plotters can be very easy or quite an effort depending on how -sophisticated you want to do it. In principle, you only have to implement the -:meth:`Formatoption.update` method and a default value. I.e., one simple -formatoption would be - - -.. ipython:: - - In [1]: from psyplot.plotter import Formatoption, Plotter - - In [2]: class MyFormatoption(Formatoption): - ...: default = 'my text' - ...: def update(self, value): - ...: self.ax.text(0.5, 0.5, value, fontsize='xx-large') - -together with a plotter - -.. ipython:: - - In [3]: class MyPlotter(Plotter): - ...: my_fmt = MyFormatoption('my_fmt') - -and your done. Now you can make a simple plot - -.. ipython:: - - In [4]: from psyplot import open_dataset - - In [5]: ds = open_dataset('demo.nc') - - @savefig docs_demo_MyPlotter_simple.png width=4in - In [6]: plotter = MyPlotter(ds.t2m) - -However, if you're using the psyplot framework, you probably will be a bit more -advanced so let's talk about attributes and methods of the :class:`Formatoption` -class. - -If you look into the documentation of the :class:`Formatoption` class, you find -quite a lot of attributes and methods which probably is a bit depressing and -confusing. But in principle, we can group them into 4 categories, the interface -to the data, to the plotter and to other formatoptions. Plus an additional -category for some Formatoption internals you definitely have to care about. - -Interface for the plotter -^^^^^^^^^^^^^^^^^^^^^^^^^ -The first interface is the one, that interfaces to the plotter. The most -important attributes in this group are the :attr:`~Formatoption.key`, -:attr:`~Formatoption.priority`, :attr:`~Formatoption.plot_fmt`, -:meth:`~Formatoption.initialize_plot` and most important the -:meth:`~Formatoption.update` method. - -The :attr:`~Formatoption.key` is the unique key for the formatoption inside the -plotter. In our example above, we assign the ``'my_fmt'`` key to the -``MyFormatoption`` class in ``MyPlotter``. Hence, this key is defined when the -plotter class is defined and will be automatically assigned to the formatoption. - -The next important attribute is the :attr:`priority` attribute. There are three -stages in the update of a plotter: - -1. The stage with data manipulation. If formatoptions manipulate the data that - shall be visualized (the :attr:`~Formatoption.data` attribute), those - formatoptions are updated first. They have the :attr:`psyplot.plotter.START` - priority -2. The stage of the plot. Formatoptions that influence how the data is - visualized are updated here (e.g. the colormap or formatoptions that do the - plotting). They have the :attr:`psyplot.plotter.BEFOREPLOTTING` priority. -3. The stage of the plot where additional informations are inserted. Here all - the labels are updated, e.g. the title, xlabel, etc.. This is the default - priority of the :class:`Formatoption.priority` attribute, the - :attr:`psyplot.plotter.END` priority. - -If there is any formatoption updated within the first two groups, the plot of -the plotter is updated. This brings us to the third important attribute, the -:attr:`~Formatoption.plot_fmt`. This boolean tells the plotter, whether the -corresponding formatoption is assumed to make a plot at the end of the second -stage (the :attr:`~psyplot.plotter.BEFOREPLOTTING` stage). If this attribute is -``True``, then the plotter will call the :meth:`Formatoption.make_plot` method -of the formatoption instance. - -Finally, the :meth:`~Formatoption.initialize_plot` and -:meth:`~Formatoption.update` methods, this is were your contribution really is -required. The :meth:`~Formatoption.initialize_plot` method is called when the -plot is created for the first time, the :meth:`~Formatoption.update` method -when it is updated (the default implementation of the -:meth:`~Formatoption.initialize_plot` simply calls the -:meth:`~Formatoption.update` method). Implement these methods in your -formatoption and thereby make use of the interface to the -:ref:`data ` and other -:ref:`formatoptions `. - -.. _fmt_data_interface: - -Interface to the data -^^^^^^^^^^^^^^^^^^^^^ -The next set of attributes help you to interface to the data. There are two -important parts in this section the interface to the data and the -interpretation of the data. - -The first part is mainly represented to the :attr:`Formatoption.data` and -:attr:`Formatoption.raw_data` attributes. The plotter that contains the -formatoption often creates a copy of the data because the data for -the visualization might be modified (see for example the -:class:`psy_reg.plotter.LinRegPlotter`). This modified data can be accessed -through the :attr:`Formatoption.data` and should be the standard approach to -access the data within a formatoption. Nevertheless, the original data can be -accessed through the :attr:`Formatoption.raw_data` attribute. However, it only -makes sense to access this data for formatoption with :attr:`START` -:attr:`~Formatoption.priority`. - -The result of these two attributes depend on the -:attr:`Formatoption.index_in_list` attribute. The data objects in the psyplot -framework are either a :class:`xarray.DataArray` or a list of those in a -:class:`psyplot.data.InteractiveList`. If the -:attr:`~Formatoption.index_in_list` attribute is not None, and the data object -is an :class:`~psyplot.data.InteractiveList`, then only the array at the -specified position is returned. To completely avoid this issue, you might also -use the :attr:`~Formatoption.iter_data` or :attr:`~Formatoption.iter_raw_data` -attributes. - -The second part in this section is the interpretation of the data and here, -the formatoption can use the :attr:`Formatoption.decoder` attribute. This -subclass of the :class:`psyplot.data.CFDecoder` helps you to identify the -x- and y-variables in the data. - - -.. _fmt_fmt_interface: - -Interfacing to other formatoptions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -A formatoption is the lowest level in the psyplot framework. It is represented -at multiple levels: - -1. at the lowest level through the subclass of the :class:`Formatoption` class -2. at the :class:`Plotter` class level which includes the formatoption class - as a descriptor (in our example above it's ``MyPlotter.my_fmt``) -3. at the :class:`Plotter` instance level through - - i. a personalized instance of the corresponding :class:`Formatoption` class - (i.e. ``plotter = MyPlotter(); plotter.my_fmt is not MyPlotter.my_fmt``) - ii. an item in the plotter (i.e. ``plotter = MyPlotter(); plotter['my_fmt']``) -4. In the update methods of the :class:`Plotter`, - :class:`psyplot.data.InteractiveBase` and :class:`psyplot.data.ArrayList` - as a keyword (i.e. - ``plotter = MyPlotter(); plotter.update(my_fmt='new value')``) - -Hence, there is one big to the entire framework, that is: the functionality -of a new formatoption has to be completely defined through exactly one argument, -i.e. it must be possible to assign a value to the formatoption in the plotter. - -For complex formatoption, this might indeed be quite a challenge for the -developer and there are two solutions to it: - -1. The simple solution for the developer: Allow a dictionary as a formatoption, - here we also have the :class:`psyplot.plotter.DictFormatoption` to help you. -2. Interface to other formatoptions - -First solution: Use a :class:`dict` -___________________________________ -That said, to implement a formatoption that inserts a custom text and let the -user define the size of the text, you either create a formatoption that accepts -a text via - -.. code-block:: python - - class CustomText(DictFormatoption): - - default = {'text': ''} - - text = None - - def validate(self, value): - if not isinstance(value, dict): - return {'text': value} - return value - - def initialize_plot(self, value): - self.text = self.ax.text(0.2, 0.2, value['text'], - fontsize=value.get('size', 'large')) - - def update(self, value): - self.text.set_text(value['text']) - self.text.set_fontsize(value.get('size', 'large')) - - - class MyPlotter(Plotter): - - my_fmt = CustomText('my_fmt') - -and then you could create and update a plotter via - -.. code-block:: python - - p = MyPlotter(xarray.DataArray([])) - p.update(my_fmt='my text') # updates the text - p.update(my_fmt={'size': 14}) # updates the size - p.update(my_fmt={'size': 14, 'text': 'Something'}) # updates text and size - -This solution has the several advantages: - -- The user does not get confused through too many formatoptions -- It is easy to allow more keywords for this formatoption - -Indeed, the :class:`psy_simple.plotter.Legend` formatoption uses this framework -since the :func:`matplotlib.pyplot.legend` function accepts that many keywords -that it would be not informative to create a formatoption for each of them. - -Otherwise you could of course avoid the :class:`DictFormatoption` and just -force the user to always provide a new dictionary. - -Second solution: Interact with other formatoptions -__________________________________________________ -Another possibility is to implement a second formatoption for the size of the -text. And here, the psyplot framework helps you with several attributes of the -:class:`Formatoption` class: - -the :attr:`~Formatoption.children` attribute - Forces the listed formatoptions in this list to be updated before the - current formatoption is updated -the :attr:`~Formatoption.dependencies` attributes - Same as :attr:`~Formatoption.children` but also forces an update if one - of the named formatoptions are updated -the :attr:`~Formatoption.parents` attribute - Skip the update if one of the :attr:`~Formatoption.parents` is updated -the :attr:`~Formatoption.connections` attribute - just provides connections to the listed formatoptions - -Each of those attributes accept a list of strings that represent the -formatoption keys of other formatoptions. Those formatoptions are then -accessible within the formatoption via the usual :func:`getattr`. I.e. if you -list a formatoption in the :attr:`~Formatoption.children` attribute, you can -access it inside the formatoption (``self``) via ``self.other_formatoption``. - -In our example of the ``CustomText``, this could be implemented via - -.. code-block:: python - - class CustomTextSize(Formatoption): - """ - Set the fontsize of the custom text - - Possible types - -------------- - int - The fontsize of the text - """ - - default = int - - def validate(self, value): - return int(value) - - # this text has not to be updated if the custom text is updated - children = ['text'] - - def update(self, value): - self.text.text.set_fontsize(value) - - - class CustomText(Formatoption): - """ - Place a text - - Possible types - -------------- - str - The text to display"""" - - def initialize_plot(self, value): - self.text = self.ax.text(0.2, 0.2, value['text']) - - def update(self, value): - self.text.set_text(value) - - - class MyPlotter(Plotter): - - my_fmt = CustomText('my_fmt') - my_fmtsize = CustomTextSize('my_fmtsize', text='my_fmt') - -the update in that sense would be like - -and then you could create and update a plotter via - -.. code-block:: python - - p = MyPlotter(xarray.DataArray([])) - p.update(my_fmt='my text') # updates the text - p.update(my_fmtsize=14) # updates the size - p.update(my_fmt='Something', my_fmtsize=14) # updates text and size - -The advantages of this methodology are basically: - -- The user straight away sees two formatoptions that can be interpreted - easiliy -- The formatoption that controls the font size could easily be subclassed and - replaced in a subclass of ``MyPlotter``. In the first framework using the - :class:`DictFormatoption`, this would mean that the entire process has to be - rewritten. - - As you see in the above definition - ``my_fmtsize = CustomTextSize('my_fmtsize', text='my_fmt')``, we provide an - additional ``text`` keyword. That is because we explicitly named the - ``text`` key in the ``children`` attribute of the ``CustomTextSize`` - formatoption. In that way we can tell the ``my_fmtsize`` formatoption how to - find the necessary formatoption. That works for all keys listed in the - :attr:`~Formatoption.children`, :attr:`~Formatoption.dependencies`, - :attr:`~Formatoption.parents` and :attr:`~Formatoption.connections` - attributes. - - -.. _new_plugins: - -Creating new plugins --------------------- -Now that you have created your plotter, you may want to include it in the -plot methods of the :class:`~psyplot.project.Project` class such that you can -do something like - -.. code-block:: python - - import psyplot.project as psy - psy.plot.my_plotter('netcdf-file.nc', name='varname') - -There are three possibilities how you can do this: - -1. The easy and fast solution for one session: register the plotter using the - :func:`psyplot.project.register_plotter` function -2. The easy and steady solution: Save the calls you used in step 1 in the - ``'project.plotter.user'`` key of the - :attr:`~psyplot.config.rcsetup.rcParams` -3. The steady and shareable solution: Create a new plugin - -The third solution has been used for the psy-maps_ and psy-simple_ plugins. To -create a skeleton for your plugin, you can use the ``psyplot-plugin`` command -that is installed when you install psyplot. - -For our demonstration, let's create a plugin named my-plugin. This is simply -done via - -.. ipython:: - - In [1]: !psyplot-plugin my-plugin - - In [2]: import glob - - In [3]: glob.glob('my-plugin/**', recursive=True) - -The following files are created in a directory named ``'my-plugin'``: - -``'setup.py'`` - The installation script -``'my_plugin/plugin.py'`` - The file that sets up the configuration of our plugin. This file should - define the ``rcParams`` for the plugin (see also :ref:`plugins-rcParams`) -``'my_plugin/plotters.py'`` - The file in which we define the plotters. This file should define the - plotters and formatoptions. - -If you want to see more, look into the comments in the created files. - -.. ipython:: - - @suppress - In [4]: !rm -r my-plugin - -.. _psy-maps: https://psyplot.readthedocs.io/projects/psy-maps/en/latest/ -.. _psy-simple: https://psyplot.readthedocs.io/projects/psy-simple/en/latest/ - -.. _plugins-rcParams: - -``rcParams`` handling in plugins --------------------------------- -Every formatoption does have default values. In -:ref:`our example above `, we simply set it via the -:attr:`~psyplot.plotter.Formatoption.default` attribute. This is a hard-coded, -but easy, stable and quick solution. - -However, your formatoption could also be used in different plotters, each -requiring a different default value. Or you want to give the user the -possibility to set his own default value. For this, we implemented the - -.. autosummary:: - - psyplot.plotter.Plotter._rcparams_string - -attribute. Here you can specify a string for this plotter which is used to -get the default value of the formatoptions in this plotter from the -:attr:`rcParams `. The expected -:attr:`~psyplot.plotter.Formatoption.default_key` for one formatoption would -then be ``the_chosen_string + fmt_key``. - -The following example illustrates this: - -.. ipython:: - - In [1]: from psyplot.config.rcsetup import rcParams - ...: from psyplot.plotter import Plotter, Formatoption - - -First we define our defaultParams, a mapping from default key to the -default value, a validation function, and a description (see the -:data:`psyplot.config.rcsetup.defaultParams` dictionary). - -.. ipython:: - - In [2]: defaultParams = { - ...: 'plotter.example_plotter.fmt1': [ - ...: 1, lambda val: int(val), 'Example formatoption'] - ...: } - -Then we update the :attr:`~psyplot.config.rcsetup.RcParams.defaultParams` of -the :attr:`psyplot.rcParams ` and set the -value - -.. ipython:: - - In [3]: rcParams.defaultParams.update(defaultParams) - - In [4]: rcParams.update_from_defaultParams(defaultParams) - ...: print(rcParams['plotter.example_plotter.fmt1']) - -Now we define a formatoption for our new plotter class and implement it in a -new plotter object. - -.. ipython:: - - In [5]: class ExampleFmt(Formatoption): - ...: def update(self, value): - ...: pass - - In [6]: class ExamplePlotter(Plotter): - ...: # we use our base string, 'plotter.example_plotter.' - ...: _rcparams_string = ['plotter.example_plotter.'] - ...: # and register a formatoption for the plotter - ...: fmt1 = ExampleFmt('fmt1') - -If we now create a new instance of this ``ExamplePlotter``, the ``fmt1`` -formatoption will have a value of ``1``, as we defined it in the above -``defaultParams``: - -.. ipython:: - - In [7]: plotter = ExamplePlotter() - - In [8]: print(plotter['fmt1']) - - # and the default_key is our string in the defaultParams, a combination - # of the _rcparams_string and the formatoption key - In [9]: print(plotter.fmt1.default_key) - - In [10]: print(plotter.fmt1.default) - -Changing the value in the :attr:`~psyplot.config.rcsetup.rcParams`, also -changes the default value for the plotter - -.. ipython:: - - In [11]: rcParams['plotter.example_plotter.fmt1'] = 2 - - In [12]: print(plotter.fmt1.default) - -Also, if we subclass this plotter, the default_key will not change - -.. ipython:: - - In [13]: class SecondPlotter(ExamplePlotter): - ....: # we set a new _rcparams_string - ....: _rcparams_string = ['plotter.another_plotter.'] - - In [14]: plotter = SecondPlotter() - - # still the same key, although we defined a different _rcparams_string - In [15]: print(plotter.fmt1.default_key) - - @suppress - In [10]: rcParams.pop('plotter.example_plotter.fmt1', None) - ....: rcParams.defaultParams.pop('plotter.example_plotter.fmt1', None) - -If you're developing a new plugin you would then have to define the -``rcParams`` and ``defaultParams`` in the ``plugin.py`` script (see -:ref:`new_plugins`) and they will then be automatically implemented in -:attr:`psyplot.rcParams `. diff --git a/docs/environment.yml b/docs/environment.yml deleted file mode 100644 index a279780..0000000 --- a/docs/environment.yml +++ /dev/null @@ -1,24 +0,0 @@ -name: psyplot_docs -channels: - - psyplot/label/master - - psyplot - - chilipp/label/conda-forge -dependencies: - - python>3.6 - - dask - - xarray - - netCDF4 - - matplotlib=3.2 # mainly for matplotlib compatibility - - seaborn - - ipython - - nbconvert - - jupyter_client - - ipykernel - - sphinx - - psy-maps - - pip - - pip: - - autodocsumm - - cdo - - sphinx-argparse - - sphinx-nbexamples diff --git a/docs/getting_started.rst b/docs/getting_started.rst deleted file mode 100644 index 99647af..0000000 --- a/docs/getting_started.rst +++ /dev/null @@ -1,746 +0,0 @@ -.. _getting-started: - -Getting started -=============== - -.. include:: - -.. currentmodule:: psyplot.project - - -Initialization and interactive usage ------------------------------------- - -This section shall introduce you how to read data from a netCDF file and -visualize it via psyplot. For this, you need to have netCDF4_ and the -psy-maps_ psyplot plugin to be installed (see :ref:`install`). - -Furthermore we use the :download:`demo.nc` netCDF file for our -demonstrations. - -.. _netCDF4: https://github.com/Unidata/netcdf4-python -.. _psy-maps: https://psy-maps.readthedocs.io/en/latest - -.. note:: - - We recommend to either run this example using our - :ref:`GUI `. However, you can also either use - IPython_ from the terminal via - - .. code-block:: bash - - conda install ipython # or pip install ipython - ipython # starts the ipython console - - and copy-paste the commands in this - example, or you use a `jupyter notebook`_ via - - .. code-block:: bash - - conda install jupyter # or pip install jupyter - jupyter notebook # starts the notebook server - - Then create a new notebook in the desired location and copy-paste the - examples below. If you want, we also recommend to include the following - commands in the notebook - - .. code-block:: python - - import psyplot.project as psy - # show the figures inline in the notebook and not in a separate window - %matplotlib inline - # don't close the figures after showing them, because than the update - # would not work - %config InlineBackend.close_figures = False - # show the figures after they are drawn or updated. This is useful - # for the visualization in the jupyter notebook - psy.rcParams['auto_show'] = True - - .. _IPython: http://ipython.readthedocs.io/en/stable/ - .. _jupyter notebook: http://jupyter.org/install.html - -After you :ref:`installed psyplot `, you can import the package via - -.. ipython:: - - In [1]: import psyplot - -Psyplot has several modules and subpackages. The main module for the use of -psyplot is the :mod:`~psyplot.project` module. - -.. ipython:: - - In [2]: import psyplot.project as psy - -Plots can be created using the attributes of the :attr:`plot` instance of -the :class:`ProjectPlotter`. - -Each new plugin defines several plot methods. In case of the psy-maps_ -package, those are - -.. ipython:: - - In [3]: psy.plot.show_plot_methods() - -So to create a simple 2D plot of the temperature field ``'t2m'``, you can -type - -.. ipython:: - - @savefig docs_getting_started.png width=4in - In [4]: p = psy.plot.mapplot('demo.nc', name='t2m') - -.. note:: - - If you're not using the :ref:`GUI `, you have to - call the :meth:`~Project.show` method to display the plot, i.e. just run - - .. code-block:: python - - p.show() - -Now you created your first project - -.. ipython:: - - In [5]: p - -which contains the :class:`xarray.DataArray` that stores the data and the -corresponding plotter that visualizes it - -.. ipython:: - - In [6]: p[0] - - In [7]: type(p[0].psy.plotter) - -The visualization and data handling within the psyplot framework is designed to -be as easy, flexible and interactive as possible. The appearance of a plot is -controlled by the formatoptions of the plotter. In our case, they are the -following: - -.. ipython:: - - In [8]: p.keys() - -they can be investigated through the :meth:`Project.keys`, -:meth:`~Project.summaries` and :meth:`~Project.docs`, or the corresponding -low level methods of the :class:`~psyplot.plotter.Plotter` class, -:meth:`~psyplot.plotter.Plotter.show_keys`, -:meth:`~psyplot.plotter.Plotter.show_summaries` and -:meth:`~psyplot.plotter.Plotter.show_docs`. - -Updating a formatoption is straight forward. Each formatoption accepts a certain -type of data. Let's say, we want to have a different projection. Then we can -look at the types this formatoption accepts using the :meth:`Project.docs` - -.. ipython:: - - In [9]: p.docs('projection') - -Let's use an orthogonal projection. The update goes via the -:meth:`Project.update` method which goes all the way down to the -:meth:`psyplot.plotter.Plotter.update` and the -:meth:`psy_maps.plotters.Projection.update` method of the formatoption. - -.. ipython:: - - @savefig docs_getting_started_1.png width=4in - In [10]: p.update(projection='ortho') - -.. note:: - - Actually, in this case an update of the projection requires that the entire - axes is cleared and the plot is drawn again. If you want to know more about - it, check the :attr:`~psyplot.plotter.Formatoption.requires_clearing` - attribute of the formatoption. - -Our framework also let's us update the dimensions of the data we show. For -example, if we want to display the field for february, we can type - -.. ipython:: - - # currently we are displaying january - In [11]: p[0].time.values - - In [12]: p.update(time='1979-02', method='nearest') - - # now its february - In [13]: p[0].time.values - -which is in our case equivalent for choosing the second index in our time -coordinate via - -.. ipython:: - :verbatim: - - In [14]: p.update(time=1) - -So far for the first quick introduction. If you are interested you are welcomed -to visit our :ref:`example galleries ` or continue with this -guide. - -In the end, don't forget to close the project in order to delete the data from -the memory and close the figures - -.. ipython:: - - In [15]: p.close(True, True, True) - -.. _intro_dims: - -Choosing the dimension ----------------------- - -As you saw already above, the scalar variable ``'t2m'`` has multiple time -steps and we can control what is shown via the :meth:`~Project.update` -method. By default, the :meth:`~psyplot.project.ProjectPlotter.mapplot` -plot method chooses the first time step and the first vertical level -(if those dimensions exist). - -However, you can also specify the exact data slice for your visualization based -upon the dimensions in you dataset. When doing that, you basically do not have -to care about the exact dimension names in the netCDF files, because those are -decoded following the `CF Conventions `__. Hence -each of the above dimensions are assigned to one of the general dimensions -``'t'`` (time), ``'z'`` (vertical dimension), ``'y'`` (horizontal North-South -dimension) and ``'x'`` (horizontal East-West dimension). In our demo file, -the dimensions are therefore decoded as ``'time'`` |rarr| ``'t'``, -``'lev'`` |rarr| ``'z'``, ``'lon'`` |rarr| ``'x'``, -``'lat'`` |rarr| ``'y'``. - -Hence it is equivalent if you type - -.. ipython:: - - In [7]: psy.plot.mapplot('demo.nc', name='t2m', t=1) - - @suppress - In [8]: psy.close('all') - -or - -.. ipython:: - - In [8]: psy.plot.mapplot('demo.nc', name='t2m', time=1) - - @suppress - In [8]: psy.close('all') - -Finally you can also be very specific using the `dims` keyword via - -.. ipython:: - - In [9]: psy.plot.mapplot('demo.nc', name='t2m', dims={'time': 1}) - - @suppress - In [8]: psy.close('all') - -You can also use the `method` keyword from the plotting function to use the -advantages of the :meth:`xarray.DataArray.sel` method. E.g. to plot the data -corresponding to March 1979 you can use - -.. ipython:: - - In [10]: psy.plot.mapplot('demo.nc', name='t2m', t='1979-03', - ....: method='nearest', z=100000) - - @suppress - In [8]: psy.close('all') - -.. note:: - - If your netCDF file does (for whatever reason) not follow the CF Conventions, - we interprete the last dimension as the *x*-dimension, the second - last dimension (if existent) as the *y*-dimension, the third last dimension as - the *z*-dimension. The time dimension however has to have the name - ``'time'``. If that still does not fit your netCDF files, you can specify - the correct names in the :attr:`~psyplot.config.rcsetup.rcParams`, namely - - .. ipython:: - - In [11]: psy.rcParams.find_all('decoder.(x|y|z|t)') - -.. _intro_fmt: - -Configuring the appearance of the plot --------------------------------------- - -psyplot is build upon the great and extensive features of the matplotlib -package. Hence, our framework can in principle be seen as a high-level -interface to the matplotlib functionalities. However you can always access -the basic matplotlib objects like figures and axes if you need. - -In the psyplot framework, the communication to matplotlib is done via -*formatoptions* that control the appearence of a plot. Each plot method -(i.e. each attribute of :attr:`psyplot.project.plot`) has several a set of -them and they set up the corresponding plotter. - -Formatoptions are all designed for an interactive usage and can usually be -controlled with very simple commands. They range from simple formatoptions -like :attr:`choosing the title ` to -:attr:`choosing the latitude-longitude box of the data `. - -The formatoptions depend on the specific plotting method and can be seen via -the methods - -.. autosummary:: - - ~psyplot.project.PlotterInterface.keys - ~psyplot.project.PlotterInterface.summaries - ~psyplot.project.PlotterInterface.docs - -For example to look at the formatoptions of the -:attr:`~psyplot.project.ProjectPlotter.mapplot` method in an interactive -session, type - -.. ipython:: - - In [24]: psy.plot.mapplot.keys(grouped=True) # to see the fmt keys - - In [25]: psy.plot.mapplot.summaries(['title', 'cbar']) # to see the fmt summaries - - In [26]: psy.plot.mapplot.docs('title') # to see the full fmt docs - -But of course you can also use the -:class:`online documentation ` of the -method your interested in. - -To include a formatoption from the beginning, you can simply pass in the key -and the desired value as keyword argument, e.g. - -.. ipython:: - - In [27]: psy.plot.mapplot('demo.nc', name='t2m', title='my title', - ....: cbar='r') - - @suppress - In [28]: psy.close('all') - -This works generally well as long as there are no dimensions in the desired -data with the same name as one of the passed in formatoptions. If you want to -be really sure, use the `fmt` keyword via - -.. ipython:: - - In [28]: psy.plot.mapplot('demo.nc', name='t2m', fmt={'title': 'my title', - ....: 'cbar': 'r'}) - -The same methodology works for the interactive usage, i.e. you can use - -.. ipython:: - - In [29]: p.update(title='my title', cbar='r') - - # or - In [30]: p.update(fmt={'title': 'my title', 'cbar': 'r'}) - - @suppress - In [28]: psy.close('all') - - -.. _intro_update: - -Controlling the update ----------------------- - -.. _intro_auto_updates: - -Automatic update -^^^^^^^^^^^^^^^^ - -By default, a call of the :meth:`~psyplot.data.ArrayList.update` method -forces an automatic update and redrawing of all the plots. There are -however several ways to modify this behavior: - -1. Changing the behavior of one single project - - 1. in the initialization of a project using the `auto_update` keyword - - .. ipython:: - - In [9]: p = psy.plot.mapplot('demo.nc', name='t2m', auto_update=False) - - 2. setting the :attr:`~psyplot.data.ArrayList.no_auto_update` attribute - - .. ipython:: - - In [10]: p.no_auto_update = True - -2. Changing the default configuration in the ``'lists.auto_update'`` - key in the :attr:`~psyplot.config.rcsetup.rcParams` - - .. ipython:: - - In [11]: psy.rcParams['lists.auto_update'] = False - - @suppress - In [11]: psy.rcParams['lists.auto_update'] = True - -3. Using the :attr:`~psyplot.data.ArrayList.no_auto_update` attribute as a - context manager - - .. ipython:: - - In [12]: with p.no_auto_update: - ....: p.update(title='test') - -If you disabled the automatical update via one of the above methods, you have -to start the registered updates manually via - -.. ipython:: - - In [12]: p.update(auto_update=True) - - # or - In [13]: p.start_update() - - @suppress - In [28]: psy.close('all') - - -Direct control on formatoption update -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -By default, when updating a formatoption, it is checked for each plot whether -the formatoption would change during the update or not. If not, the -formatoption is not updated. However, sometimes you may want to do that and -for this, you can use the *force* keyword in the -:meth:`~psyplot.data.ArrayList.update` method. - - -.. _intro_multiple: - -Creating and managing multiple plots ------------------------------------- - -Creating multiple plots -^^^^^^^^^^^^^^^^^^^^^^^ - -One major advantage of the psyplot framework is the systematic management of -multiple plots at the same time. To create multiple plots, simply pass in a -list of dimension values and/or names. For example - -.. ipython:: - - In [12]: psy.plot.mapplot('demo.nc', name='t2m', time=[0, 1]) - - @suppress - In [12]: psy.close('all') - -created two plots: one for the first and one for the second time step. - -Furthermore - -.. ipython:: - - In [13]: psy.plot.mapplot('demo.nc', name=['t2m', 'u'], time=[0, 1]) - - @suppress - In [13]: psy.close('all') - -created four plots. By default, each plot is made in an own figure but you can -also use the `ax` keyword to setup how the plots will be arranged. The `sort` -keyword allows you to sort the plots. - -As an example we plot the variables ``'t2m'`` and ``'u'`` for the first and -second time step into one figure and sort by time. This will produce - -.. ipython:: - - @savefig docs_multiple_plots.png width=4in - In [16]: psy.plot.mapplot( - ....: 'demo.nc', name=['t2m', 'u'], time=[0, 1], ax=(2, 2), sort=['time'], - ....: title='%(long_name)s, %b') - - @suppress - In [18]: psy.close('all') - -.. warning:: - - As the xarray package, the slicing is based upon positional indexing with - lists (see `the xarray documentation on ositional indexing - `__). - Hence you might think of choosing your data slice via - ``psy.plot.mapplot(..., x=[1, 2, 3, 4, 5], ...)``. However this would result - in 5 different plots! Instead you have to write - ``psy.plot.mapplot(..., x=[[1, 2, 3, 4, 5]], ...)``. The same is true - for plotting methods like the - :attr:`~psyplot.project.ProjectPlotter.mapvector` method. Since this - method needs two variables (one for the latitudinal and one for the - longitudinal direction), typing - - .. ipython:: - :verbatim: - - In [18]: psy.plot.mapvector('demo.nc', name=['u', 'v']) - ValueError: Can only plot 3-dimensional data! - - results in a :class:`ValueError`. Instead you have to write - - .. ipython:: - - In [19]: psy.plot.mapvector('demo.nc', name=[['u', 'v']]) - - @suppress - In [20]: psy.close('all') - - Please have a look into the documentations of the - :attr:`~psyplot.project.ProjectPlotter.mapvector` and - :attr:`~psyplot.project.ProjectPlotter.mapcombined` for getting examples - on how to use this methods. - -Slicing and filtering the project -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Managing a whole lot of plots is basically the same as managing a single plot. -However, you can always get the single array and handle it separately. - -You can either get it through the usual list slicing (the :class:`Project` class -actually is a simple :class:`list` subclass) or you can use meta attributes, -dimensions and the specific :attr:`~psyplot.data.InteractiveBase.arr_name` -attribute. For the latter one, just call the project with your filtering -attributes - -.. ipython - - @suppress - In [16]: p = psy.plot.mapplot( - ....: 'demo.nc', name=['t2m', 'u'], time=[0, 1], ax=(2, 2), sort=['time'], - ....: title='%(long_name)s, %b') - - In [20]: p(t=0) - - In [21]: p(t='1979-01') - - In [22]: p(name='t2m') - - In [23]: p(long_name='Temperature') - -This behavior is especially useful if you want to address only some arrays -with your update. For example, let's consider we want to choose a ``'winter'`` -colormap for the zonal wind variable and a colormap ranging from blue to red -for the temperature. Then we could do this via - -.. ipython:: - - In [24]: p(name='t2m').update(cmap='RdBu_r') - - In [26]: p(name='u').update(cmap='winter') - -.. note:: - - When doing so, we recommend to temporarily disable the automatic update - because then the figure will only be drawn once and the update will be - done in parallel. - - Hence, it is better to use the context manager - :attr:`~psyplot.data.ArrayList.no_auto_update` (see :ref:`intro_auto_updates`) - - .. ipython:: - - In [27]: with p.no_auto_update: - ....: p(name='t2m').update(cmap='RdBu_r') - ....: p(name='u').update(cmap='winter') - ....: p.start_update() - - @suppress - In [28]: p.close(True, True) - -Finally you can access the plots created by a specific plotting method -through the corresponding attribute in the :class:`~psyplot.project.Project` -class. In this case this is of course useless because all plots in ``maps`` -were created by the same plotting method, but it may be helpful when having -different plotters in one project (see :ref:`framework`). Anyway, the plots -created by the :attr:`~psyplot.project.ProjectPlotter.mapplot` method could be -accessed via - -.. ipython:: - - In [24]: p.mapplot - - - -.. _save_and_load: - -Saving and loading your project -------------------------------- - -Within the psyplot framework, you can also save and restore your plots easily -and flexibel. - -To save your project, use the :meth:`~psyplot.project.Project.save_project` -method: - -.. ipython:: - - @suppress - In [28]: p = psy.plot.mapplot('demo.nc', name='t2m', time=[0, 1], ax=(1, 2)) - - In [28]: p.save_project('my_project.pkl') - -This saves the plot-settings into the file ``'my_project.pkl'``, a simple pickle -file that you could open by yourself using - -.. ipython:: - - In [29]: import pickle - - In [30]: with open('my_project.pkl', 'rb') as f: - ....: d = pickle.load(f) - - @ suppress - In [31]: import os - ....: os.remove('my_project.pkl') - -In order to not avoid large project files, we do not store the data but only the -filenames of the datasets. Hence, if you want to load the project again, make -sure that the datasets are accessible through the path as they are listed in the -:attr:`~psyplot.project.Project.dsnames` attribute. - -Otherwise you have several options to avoid wrong paths: - -1. Use the `alternative_paths` parameter and provide for each filename a - specific path when you *save* the project - - .. ipython:: - - In [29]: p.dsnames - - @verbatim - In [30]: p.save_project( - ....: 'test.pkl', alternative_paths={'demo.nc': 'other_path.nc'}) - -2. pack the whole data to the place where you want to store the project file - - .. ipython:: - - @verbatim - In [31]: p.save_project('target-folder/test.pkl', pack=True) - -3. specify where the datasets can be found when you *load* the project: - - .. ipython:: - - @verbatim - In [32]: p = psy.Project.load_project( - ....: 'test.pkl', alternative_paths={'demo.nc': 'other_path.nc'}) - -4. Save the data in the pickle file, too - - .. ipython:: - - @verbatim - In [33]: p.save_project('test.pkl', ds_description={'arr'}) - - @suppress - In [33]: psy.close('all') - -To restore your project, simply use the -:meth:`~psyplot.project.Project.load_project` method via - -.. ipython:: - - @verbatim - In [33]: maps = psy.Project.load_project('test.pkl') - -.. note:: - - Saving a project stores the figure informations like axes positions, - background colors, etc. However only the axes informations from from the - axes within the project are stored. Other axes in the matplotlib figures are - not considered and will not be restored. You can, however, use the - `alternative_axes` keyword in the :meth:`Project.load_project` method if - you want to restore your settings and/or customize your plot with the - :attr:`~psyplot.plotter.Plotter.post` formatoption (see - :ref:`own-scripts`) - - -.. _presets: - -Using presets -------------- -You can save and load presets to reuse the formatoption settings. For instance, -let's say temperature should always use a ``'Reds'`` cmap, the colorbar label -should show the long name and the title should be ``'time'``. This is of course -possible via - -.. ipython:: - - @savefig docs_presets_1.png width=4in - In [34]: sp = psy.plot.mapplot( - ....: 'demo.nc', name='t2m', cmap="Reds", clabel="%(long_name)s", - ....: title='%(time)s') - -But instead of writing this all the time, you can also save it as a preset - -.. ipython:: - - In [35]: sp.save_preset("t2m-preset") - - @suppress - In [35]: psy.close('all') - -and reload this preset either via the `preset` keyword - -.. ipython:: - - @savefig docs_presets_2.png width=4in - In [36]: sp = psy.plot.mapplot('demo.nc', name='t2m', preset='t2m-preset') - -or the :meth:`~psyplot.project.Project.load_preset` method - -.. ipython:: - - In [37]: sp.load_preset('t2m-preset') - -You can list the available presets from the command line - -.. ipython:: - - In [38]: !psyplot --list-presets - - @suppress - In [37]: !rm {sp._resolve_preset_path('t2m-preset')} - ....: psy.close('all') - -.. _own-scripts: - -Adding your own script: The :attr:`~psyplot.plotter.Plotter.post` formatoption ------------------------------------------------------------------------------- -Very likely, you will face the problem that not all your needs are satisfied -by the formatoptions in one plotter. You then have two choices: - -1. define your own plotter with new formatoptions (see :ref:`plugins_guide`) - - Pros - - more structured approach - - you can enhance the plotter with other formatoptions afterwards and - reuse it - Cons - - more complicated - - you always have to ship the module where you define your plotter when - you want to :ref:`save and load ` your project - - can get messy if you define a lot of different plotters -2. use the :attr:`~psyplot.plotter.Plotter.post` formatoption - - Pros - - fast and easy - - easy to :ref:`save and load ` - Cons - - may get complicated for large scripts - - has to be enabled manually by the user - -For most of the cases, the :attr:`~psyplot.plotter.Plotter.post` formatoptions -is probably what you are looking for (the first option is described in our -:ref:`developers guide `). - -This formatoption is designed for applying your own postprocessing script to -your plot. It accepts a string that is executed using the built-in :func:`exec` -function and is executed at the very end of the plotting. In this python -script, the formatoption itself (and therefore the -:attr:`~psyplot.plotter.Formatoption.plotter` and -:attr:`axes ` can be accessed inside the -script through the ``self`` variable. An example how to handle this -formatoption can be found in -:ref:`our example gallery `. diff --git a/docs/index.rst b/docs/index.rst index cc7a89a..acfb712 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,224 +1,18 @@ .. psyplot documentation master file, created by - sphinx-quickstart on Mon Jul 20 18:01:33 2015. + sphinx-quickstart on Wed Sep 22 19:43:59 2021. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -.. _psyplot: +Welcome to psyplot's documentation! +=================================== -Interactive data visualization with python -========================================== +.. raw:: html -.. image:: _static/psyplot.png - :width: 50% - :alt: psyplot logo - :align: center - -Welcome! Looking for a fast and flexible visualization software? Here we -present **psyplot**, an open source python project that mainly combines the -plotting utilities of matplotlib_ and the data management of the xarray_ -package and integrates them into a software that can be used via command-line -and via a GUI! - -The main purpose is to have a framework that allows a fast, attractive, -flexible, easily applicable, easily reproducible and especially an interactive -visualization of your data. - -The ultimate goal is to help scientists in their daily work by providing a -flexible visualization tool that can be enhanced by their own visualization -scripts. ``psyplot`` can be used via command line and with the -graphical user interface (GUI) from the -:ref:`psyplot-gui ` and -:ref:`psy-view ` module. - -If you want more motivation: Have a look into the :ref:`about` section. - -The package is very new and there are many features that will be included in -the future. So we are very pleased for feedback! Please simply raise an issue -on `GitHub `__. - - -.. start-badges - -.. only:: html and not epub - - .. list-table:: - :stub-columns: 1 - :widths: 10 90 - - * - docs - - |docs| |joss| - * - tests - - |travis| |appveyor| |requires| |codecov| - * - package - - |version| |conda| |github| - * - implementations - - |supported-versions| |supported-implementations| - * - get in touch - - |gitter| |mailing-list| |issues| - - .. |docs| image:: http://readthedocs.org/projects/psyplot/badge/?version=latest - :alt: Documentation Status - :target: http://psyplot.readthedocs.io/en/latest/?badge=latest - - .. |travis| image:: https://travis-ci.org/psyplot/psyplot.svg?branch=master - :alt: Travis - :target: https://travis-ci.org/psyplot/psyplot - - .. |appveyor| image:: https://ci.appveyor.com/api/projects/status/4nt6qrw66iw65w33/branch/master?svg=true - :alt: AppVeyor - :target: https://ci.appveyor.com/project/psyplot/psyplot/branch/master - - .. |codecov| image:: https://codecov.io/gh/psyplot/psyplot/branch/master/graph/badge.svg - :alt: Coverage - :target: https://codecov.io/gh/psyplot/psyplot - - .. |requires| image:: https://requires.io/github/psyplot/psyplot/requirements.svg?branch=master - :alt: Requirements Status - :target: https://requires.io/github/psyplot/psyplot/requirements/?branch=master - - .. |version| image:: https://img.shields.io/pypi/v/psyplot.svg?style=flat - :alt: PyPI Package latest release - :target: https://pypi.python.org/pypi/psyplot - - .. |conda| image:: https://anaconda.org/conda-forge/psyplot/badges/version.svg - :alt: conda - :target: https://anaconda.org/conda-forge/psyplot - - .. |supported-versions| image:: https://img.shields.io/pypi/pyversions/psyplot.svg?style=flat - :alt: Supported versions - :target: https://pypi.python.org/pypi/psyplot - - .. |supported-implementations| image:: https://img.shields.io/pypi/implementation/psyplot.svg?style=flat - :alt: Supported implementations - :target: https://pypi.python.org/pypi/psyplot - - .. |joss| image:: http://joss.theoj.org/papers/3535c28017003f0b5fb63b1b64118b60/status.svg - :alt: Journal of Open Source Software - :target: http://joss.theoj.org/papers/3535c28017003f0b5fb63b1b64118b60 - - .. |github| image:: https://img.shields.io/github/release/psyplot/psyplot.svg - :target: https://github.com/psyplot/psyplot/releases/latest - :alt: Latest github release - - .. |gitter| image:: https://img.shields.io/gitter/room/psyplot/community.svg?style=flat - :target: https://gitter.im/psyplot/community - :alt: Gitter - - .. |mailing-list| image:: https://img.shields.io/badge/join-mailing%20list-brightgreen.svg?style=flat - :target: https://www.listserv.dfn.de/sympa/subscribe/psyplot - :alt: DFN mailing list - - .. |issues| image:: https://img.shields.io/github/issues-raw/psyplot/psyplot.svg?style=flat - :target: https://github.com/psyplot/psyplot/issues - :alt: GitHub issues - -.. end-badges - - -Documentation -------------- +

If you are not redirected, click here.

.. toctree:: - :maxdepth: 1 - - about - installing - getting_started - configuration - projects - accessors - plugins - command_line - examples/index - develop/index - contribute - api/psyplot - todos - changelog - - -Examples --------- - -.. linkgalleries:: - - psyplot - psy_simple - psy_maps - psy_reg - - -Get in touch ------------- -Any quesions? Do not hessitate to get in touch with the psyplot developers. - -- Create an issue at the `bug tracker`_ -- Chat with the developers in out `channel on gitter`_ -- Subscribe to the `mailing list`_ and ask for support - -See also the `code of conduct`_, and our -:ref:`contribution guide `_ for more information and a guide -about good bug reports. - -.. _bug tracker: https://github.com/psyplot/psyplot -.. _channel on gitter: https://gitter.im/psyplot/community -.. _mailing list: https://www.listserv.dfn.de/sympa/subscribe/psyplot -.. _code of conduct: https://github.com/psyplot/psyplot/blob/master/CODE_OF_CONDUCT.md -.. _contribution guide: https://github.com/psyplot/psyplot/blob/master/CONTRIBUTING.md - -.. _citation: - -How to cite psyplot -------------------- - -When using psyplot, you should at least cite the publication in -`the Journal of Open Source Software`_: - -.. only:: html and not epub - - .. image:: http://joss.theoj.org/papers/3535c28017003f0b5fb63b1b64118b60/status.svg - :alt: Journal of Open Source Software - :target: http://joss.theoj.org/papers/3535c28017003f0b5fb63b1b64118b60 - -Sommer, P. S.: The psyplot interactive visualization framework, -*The Journal of Open Source Software*, 2, doi:10.21105/joss.00363, -https://doi.org/10.21105/joss.00363, 2017. - -:download:`BibTex ` - :download:`EndNote ` - -Furthermore, each release of psyplot and it's :ref:`subprojects ` is -associated with a DOI using zenodo.org_. If you want to cite a specific -version or plugin, please refer to the `releases page of psyplot` or the -releases page of the corresponding subproject. - - -.. _the Journal of Open Source Software: http://joss.theoj.org/ -.. _zenodo.org: https://zenodo.org/ -.. _releases page of psyplot: https://github.com/psyplot/psyplot/releases/ - -Acknowledgment --------------- -This package has been developed by Philipp Sommer. - -I want to thank the matplotlib_, xarray_ and cartopy_ developers -for their great packages and of course the python developers for their -fascinating work on this beautiful language. - -A special thanks to Stefan Hagemann and Tobias Stacke from the -Max-Planck-Institute of Meteorology in Hamburg, Germany for the motivation on -this project and to the people of the `Not yet visible`_ agency for their -advice in designing the logo and webpage. - -Finally the author thanks the Swiss National Science Foundation (SNF) for their -support. Funding for the author came from the `ACACIA grant (CR10I2_146314)`_ -and the `HORNET grant (200021_169598)`_. - -.. _matplotlib: http://matplotlib.org -.. _xarray: http://xarray.pydata.org/ -.. _cartopy: http://scitools.org.uk/cartopy -.. _Not yet visible: https://notyetvisible.de/ -.. _ACACIA grant (CR10I2_146314): http://p3.snf.ch/project-146314 -.. _HORNET grant (200021_169598): http://p3.snf.ch/project-169598 + :maxdepth: 2 + :caption: Contents: diff --git a/docs/installing.rst b/docs/installing.rst deleted file mode 100644 index a6394af..0000000 --- a/docs/installing.rst +++ /dev/null @@ -1,209 +0,0 @@ -.. _install: - -.. highlight:: bash - -Installation -============ - -How to install --------------- -There basically three different methodologies for the installation. You should -choose the one, which is the most appropriate solution concerning your skills -and your usage: - -The recommended installation - We recommend to use anaconda for installing python and psyplot (see - :ref:`install-conda`). If you however already have python installed on - your system, you can also use pip (see :ref:`install-pip`). -The developer installation - Install it from source (see :ref:`install-source`) - - -.. _install-conda: - -Installation using conda -^^^^^^^^^^^^^^^^^^^^^^^^ -We highly recommend to use conda_ for installing psyplot. After having -downloaded the installer from anaconda_ or miniconda_, you can install psyplot -and the optional plugins (see :ref:`optional_deps`) via:: - - $ conda install -c conda-forge psy-view psy-reg - -If you only want to install the core, i.e. the raw framework, run:: - - $ conda install -c conda-forge psyplot - -If you want to be able to read GeoTiff Raster files, you will need to have -gdal_ installed:: - - $ conda install gdal - -Please also visit the `xarray installation notes`_ -for more informations on how to best configure the `xarray`_ -package for your needs. - -.. _install-pip: - -Installation using pip -^^^^^^^^^^^^^^^^^^^^^^ -If you do not want to use conda for managing your python packages, you can also -use the python package manager ``pip`` and install via:: - - $ pip install psyplot - -However to be on the safe side, make sure you have the :ref:`dependencies` -installed. - -.. _install-source: - -Installation from source -^^^^^^^^^^^^^^^^^^^^^^^^ -To install it from source, make sure you have the :ref:`dependencies` -installed, clone the github_ repository via:: - - git clone https://github.com/psyplot/psyplot.git - -and install it via:: - - python setup.py install - -.. _dependencies: - -Dependencies ------------- -Required dependencies -^^^^^^^^^^^^^^^^^^^^^ -Psyplot supports officially python 3.6 and 3.7. Previous versions are also -available for python 2.7. Furthermore the package is built upon multiple other -packages, mainly - -- xarray_>=0.8: Is used for the data management in the psyplot package -- matplotlib_>=1.4.3<3.1: **The** python visualiation package -- `PyYAML `__: Needed for the configuration of psyplot -- docrep_: A package for efficient documentation processing for large APIs -- funcargparse_: A package to create command line parsers from function - docstrings - - -.. _optional_deps: - -Optional dependencies -^^^^^^^^^^^^^^^^^^^^^ -We furthermore recommend to use - -- :ref:`psyplot-gui `: A graphical user interface to psyplot -- :ref:`psy-view `: An ncview-like interface based on psyplot - and psy-maps -- :ref:`psy-simple `: A psyplot plugin to make simple plots -- :ref:`psy-maps `: A psyplot plugin for visualizing data on a - map -- :ref:`psy-reg `: A psyplot plugin for visualizing fits to - your data -- cdo_: The python bindings for cdos (see also the - :ref:`cdo example `) - -.. _netCDF4: https://github.com/Unidata/netcdf4-python -.. _gdal: http://www.gdal.org/ -.. _conda: https://conda.io/docs/ -.. _anaconda: https://www.anaconda.com/download/ -.. _miniconda: https://conda.io/miniconda.html -.. _matplotlib: http://matplotlib.org -.. _docrep: https://docrep.readthedocs.io -.. _funcargparse: https://funcargparse.readthedocs.io -.. _xarray installation notes: http://xarray.pydata.org/en/stable/installing.html -.. _xarray: http://xarray.pydata.org/ -.. _cdo: https://code.zmaw.de/projects/cdo/wiki/Anaconda - - -Running the tests ------------------ -We us pytest_ to run our tests. So you can either run clone out the github_ -repository and run:: - - $ python setup.py test - -or install pytest_ by yourself and run:: - - $ py.test - -To also test the plugin functionality, install the ``psyplot_test`` module in -``tests/test_plugin`` via:: - - $ cd tests/test_plugin && python setup.py install - -and run the tests via one of the above mentioned commands. - - -Building the docs ------------------ -To build the docs, check out the github_ repository and install the -requirements in ``'docs/environment.yml'``. The easiest way to do this is via -anaconda by typing:: - - $ conda env create -f docs/environment.yml - $ source activate psyplot_docs - -Then build the docs via:: - - $ cd docs - $ make html - -.. note:: - - The building of the docs always preprocesses the examples. You might want to - disable that by setting ``process_examples = False``. Otherwise please note - that the examples are written as python3 notebooks, hence you may have to - install a python3 kernel through ipykernel_. Just create a new environment - ``'py37'`` and install it via:: - - conda create -n py37 python=3.7 - source activate py37 - conda install notebook ipykernel - ipython kernel install --user - - You then have to install the necessary modules for each of the examples in - the new ``'py37'`` environment. - -.. _github: https://github.com/psyplot/psyplot -.. _ipykernel: https://ipykernel.readthedocs.io -.. _pytest: https://pytest.org/latest/contents.html - - -.. _uninstall: - -Uninstallation --------------- -The uninstallation depends on the system you used to install psyplot. Either -you did it via :ref:`conda ` (see -:ref:`uninstall-conda`), via :ref:`pip ` or from the -:ref:`source files ` (see :ref:`uninstall-pip`). - -Anyway, if you may want to remove the psyplot configuration files. If you did -not specify anything else (see :func:`psyplot.config.rcsetup.psyplot_fname`), -the configuration files for psyplot are located in the user home directory. -Under linux and OSX, this is ``$HOME/.config/psyplot``. On other platforms it -is in the ``.psyplot`` directory in the user home. - -.. _uninstall-conda: - -Uninstallation via conda -^^^^^^^^^^^^^^^^^^^^^^^^ -If you installed psyplot via :ref:`conda `, simply run:: - - conda remove psyplot - -or, if you installed it into an own conda environment, remove the environment -via:: - - conda env remove -n - -.. _uninstall-pip: - -Uninstallation via pip -^^^^^^^^^^^^^^^^^^^^^^ -Uninstalling via pip simply goes via:: - - pip uninstall psyplot - -Note, however, that you should use :ref:`conda ` if you also -installed it via conda. diff --git a/docs/plugins.rst b/docs/plugins.rst deleted file mode 100644 index 8526215..0000000 --- a/docs/plugins.rst +++ /dev/null @@ -1,170 +0,0 @@ -.. _plugins: - -Psyplot plugins -=============== -psyplot only provides the abstract framework on how to make the interactive -visualization and data analysis. The real work is implemented in -:ref:`plugins to this framework `. Each -plugin is a separate package that has to be installed independent of psyplot and -each plugin registers new plot methods for :attr:`psyplot.project.plot`. - -.. _existing_plugins: - -Existing plugins ----------------- - -:mod:`psy_simple.plugin` - A psyplot plugin for simple visualization tasks. This plugin provides a - bases for all the other plugins - - - :ref:`Examples Gallery ` - - plot methods - - :attr:`psy_simple:psyplot.project.plot.density` - Make a density plot of point data - :attr:`psy_simple:psyplot.project.plot.plot2d` - Make a simple plot of a 2D scalar field - :attr:`psy_simple:psyplot.project.plot.combined` - Plot a 2D scalar field with an overlying vector field - :attr:`psy_simple:psyplot.project.plot.violinplot` - Make a violin plot of your data - :attr:`psy_simple:psyplot.project.plot.lineplot` - Make a line plot of one-dimensional data - :attr:`psy_simple:psyplot.project.plot.vector` - Make a simple plot of a 2D vector field - :attr:`psy_simple:psyplot.project.plot.barplot` - Make a bar plot of one-dimensional data - - .. linkgalleries:: - - psy_simple - -:mod:`psy_maps.plugin` - A psyplot plugin for visualizing data on a map - - - :ref:`Examples Gallery ` - - plot methods - - :attr:`psy_maps:psyplot.project.plot.mapplot` - Plot a 2D scalar field on a map - :attr:`psy_maps:psyplot.project.plot.mapvector` - Plot a 2D vector field on a map - :attr:`psy_maps:psyplot.project.plot.mapcombined` - Plot a 2D scalar field with an overlying vector field on a map - - .. linkgalleries:: - - psy_maps - -:mod:`psy_reg.plugin` - A psyplot plugin for visualizing and calculating regression fits - - - :ref:`Examples Gallery ` - - plot methods - - :attr:`psy_reg:psyplot.project.plot.densityreg` - Make a density plot and draw a fit from x to y of points - :attr:`psy_reg:psyplot.project.plot.linreg` - Draw a fit from x to y - - .. linkgalleries:: - - psy_reg - -If you have new plugins that you think should be included in this list, please -do not hesitate to open an issue on the `github project page of psyplot`_ or -implement it by yourself in `this file`_ and make a pull request. - -.. _this file: https://github.com/psyplot/psyplot/blob/master/docs/plugins.rst - -.. note:: - - Because psyplot plugins are imported right at the startup time of psyplot - but nevertheless use the :class:`psyplot.config.rcsetup.RcParams` class, - you always have to import psyplot first if you want to load a psyplot - plugin. In other words, if you want to import one of the above mentiond - modules manually, you always have to type - - .. code-block:: python - - import psyplot - import PLUGIN_NAME.plugin - - instead of - - .. code-block:: python - - import PLUGIN_NAME.plugin - import psyplot - - where ``PLUGIN_NAME`` is any of ``psy_simple, psy_maps``, etc. - -.. _github project page of psyplot: https://github.com/psyplot/psyplot - - -.. _excluding_plugins: - -How to exclude plugins ----------------------- -The psyplot package loads all plugins right when the `psyplot` is imported. In -other words, the statement - -.. code-block:: python - - import psyplot - -already includes that all the psyplot plugin packages are loaded. - -You can however exclude plugins from the automatic loading via the -``PSYPLOT_PLUGINS`` environment variable and exclude specific plot methods of a -plugin via the ``PSYPLOT_PLOTMETHODS`` variable. - -.. _plugins_env: - -The ``PSYPLOT_PLUGINS`` environment variable -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This environment variable is a ``::`` separated string with plugin names. If a -plugin name is preceded by a ``no:``, this plugin is excluded. Otherwise, only -this plugin is included. - -To show this behaviour, we can use ``psyplot --list-plugins`` which shows the -plugins that are used. By default, all plugins are included - -.. ipython:: - - In [1]: !psyplot --list-plugins - -Excluding psy-maps works via - -.. ipython:: - - In [2]: !PSYPLOT_PLUGINS=no:psy_maps.plugin psyplot --list-plugins - -Including only psy-maps works via - -.. ipython:: - - In [3]: !PSYPLOT_PLUGINS='yes:psy_maps.plugin' psyplot --list-plugins - - -.. _plot_methods_env: - -The ``PSYPLOT_PLOTMETHODS`` environment variable -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The same principle is used when the plot methods are loaded from the plugins. -If you want to manually exclude a plot method from loading, you include it via -``no::``. For example, to exclude the -:attr:``mapplot `` plot method from the -psy-maps plugin, you can use - -.. ipython:: - - In [4]: !PSYPLOT_PLOTMETHODS=no:psy_maps.plugin:mapplot psyplot --list-plot-methods - -and the same if you only want to include the -:attr:``mapplot `` and the -:attr:``lineplot `` methods - -.. ipython:: - - In [4]: !PSYPLOT_PLOTMETHODS='yes:psy_maps.plugin:mapplot::yes:psy_simple.plugin:lineplot' psyplot --list-plot-methods diff --git a/docs/projects.rst b/docs/projects.rst deleted file mode 100644 index 32029c1..0000000 --- a/docs/projects.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. _projects: - -Subprojects -=========== - -``psyplot`` is only the over-arching framework. It's capabilities are -splitted into several subprojects. Each of them is accessible via -``https://psyplot.readthedocs.io/projects/`` - -- the :ref:`psyplot_gui ` package: The GUI to psyplot - |psyplot-gui-github| |psyplot-gui-release| -- the :ref:`psy_view ` package: An ncview-like interface for - psyplot |psy-view-github| |psy-view-release| -- the :ref:`psy-simple ` package: A plugin for simple - visualization |psy-simple-github| |psy-simple-release| -- the :ref:`psy-maps ` package: A psyplot plugin for - visualizing data on a map |psy-maps-github| |psy-maps-release| -- the :ref:`psy-reg ` package: A psyplot plugin for visualizing - and calculating regression fits |psy-reg-github| |psy-reg-release| - -See :ref:`plugins` for more informations on the plugins. - -.. |psyplot-gui-github| image:: GitHub-Mark-16px.png - :target: https://github.com/psyplot/psyplot-gui - :alt: github - -.. |psyplot-gui-release| image:: https://img.shields.io/github/release/psyplot/psyplot-gui.svg?style=flat-square - :target: https://github.com/psyplot/psyplot-gui/releases/latest - :alt: Latest release - -.. |psy-view-github| image:: GitHub-Mark-16px.png - :target: https://github.com/psyplot/psy-view - :alt: github - -.. |psy-view-release| image:: https://img.shields.io/github/release/psyplot/psy-view.svg?style=flat-square - :target: https://github.com/psyplot/psy-view/releases/latest - :alt: Latest release - -.. |psy-simple-github| image:: GitHub-Mark-16px.png - :target: https://github.com/psyplot/psy-simple - :alt: github - -.. |psy-simple-release| image:: https://img.shields.io/github/release/psyplot/psy-simple.svg?style=flat-square - :target: https://github.com/psyplot/psy-simple/releases/latest - :alt: Latest release - -.. |psy-maps-github| image:: GitHub-Mark-16px.png - :target: https://github.com/psyplot/psy-maps - :alt: github - -.. |psy-maps-release| image:: https://img.shields.io/github/release/psyplot/psy-maps.svg?style=flat-square - :target: https://github.com/psyplot/psy-maps/releases/latest - :alt: Latest release - -.. |psy-reg-github| image:: GitHub-Mark-16px.png - :target: https://github.com/psyplot/psy-reg - :alt: github - -.. |psy-reg-release| image:: https://img.shields.io/github/release/Chilipp/psy-reg.svg?style=flat-square - :target: https://github.com/psyplot/psy-reg/releases/latest - :alt: Latest release diff --git a/docs/todos.rst b/docs/todos.rst deleted file mode 100644 index 5b6c5dc..0000000 --- a/docs/todos.rst +++ /dev/null @@ -1,4 +0,0 @@ -ToDos -===== - -.. todolist:: diff --git a/readthedocs.yml b/readthedocs.yml deleted file mode 100644 index 72abb85..0000000 --- a/readthedocs.yml +++ /dev/null @@ -1,11 +0,0 @@ -version: 2 - -# Build all formats -formats: all -conda: - environment: docs/environment.yml -python: - version: 3.7 - install: - - method: pip - path: .