|
| 1 | +<center><a href="http://hapi-server.org/">HAPI</a> client for Python 2/3</center> |
| 2 | + |
| 3 | +[<img src="https://travis-ci.org/hapi-server/client-python.svg?branch=master"/>](https://travis-ci.org/hapi-server/client-python) |
| 4 | + |
| 5 | +# Installation |
| 6 | + |
| 7 | +```bash |
| 8 | +pip install hapiclient --upgrade |
| 9 | +# or |
| 10 | +pip install 'git+https://github.com/hapi-server/client-python' --upgrade |
| 11 | +``` |
| 12 | + |
| 13 | +The optional [hapiplot package](https://github.com/hapi-server/plot-python) provides basic preview plotting capabilities of data from a HAPI server. The [Plotting section](https://colab.research.google.com/github/hapi-server/client-python-notebooks/blob/master/hapi_demo.ipynb#plotting) of the `hapiclient` Jupyter Notebook shows how to plot the output of `hapiclient` using many other plotting libraries. |
| 14 | + |
| 15 | +To install `hapiplot`, use |
| 16 | + |
| 17 | +```bash |
| 18 | +pip install hapiplot --upgrade |
| 19 | +# or |
| 20 | +pip install 'git+https://github.com/hapi-server/plot-python' --upgrade |
| 21 | +``` |
| 22 | + |
| 23 | +See the [Appendix](#appendix) for a fail-safe installation method. |
| 24 | + |
| 25 | +# Basic Example |
| 26 | + |
| 27 | +```python |
| 28 | +# Get Dst index from CDAWeb HAPI server |
| 29 | +from hapiclient import hapi |
| 30 | + |
| 31 | +# See http://hapi-server.org/servers/ for a list of |
| 32 | +# other HAPI servers and datasets. |
| 33 | +server = 'https://cdaweb.gsfc.nasa.gov/hapi' |
| 34 | +dataset = 'OMNI2_H0_MRG1HR' |
| 35 | +start = '2003-09-01T00:00:00' |
| 36 | +stop = '2003-12-01T00:00:00' |
| 37 | +parameters = 'DST1800' |
| 38 | +opts = {'logging': True} |
| 39 | + |
| 40 | +# Get data |
| 41 | +data, meta = hapi(server, dataset, parameters, start, stop, **opts) |
| 42 | +print(meta) |
| 43 | +print(data) |
| 44 | + |
| 45 | +# Plot all parameters |
| 46 | +from hapiplot import hapiplot |
| 47 | +hapiplot(data, meta) |
| 48 | +``` |
| 49 | + |
| 50 | +# Documentation |
| 51 | + |
| 52 | +Basic usage examples for various HAPI servers are given in [hapi_demo.py](https://github.com/hapi-server/client-python/blob/master/hapi_demo.py>) and the [Examples section](https://colab.research.google.com/github/hapi-server/client-python-notebooks/blob/master/hapi_demo.ipynb#examples) |
| 53 | + |
| 54 | +See http://hapi-server.org/servers/ for a list of HAPI servers and datasets. |
| 55 | + |
| 56 | +All of the features are extensively demonstrated in [hapi_demo.ipynb](https://colab.research.google.com/github/hapi-server/client-python-notebooks/blob/master/hapi_demo.ipynb#data-model), a Jupyter Notebook that can be viewed an executed on Google Colab. |
| 57 | + |
| 58 | +# Metadata Model |
| 59 | + |
| 60 | +See also the examples in the [Metadata Model section](https://colab.research.google.com/github/hapi-server/client-python-notebooks/blob/master/hapi_demo.ipynb) of the `hapiclient` Jupyter Notebook. |
| 61 | + |
| 62 | +The HAPI client metadata model is intentionally minimal and closely follows that of the [HAPI metadata model](https://github.com/hapi-server/data-specification). We expect that another library will be developed that allows high-level search and grouping of information from HAPI servers. See also [issue #106](https://github.com/hapi-server/data-specification/issues/106). |
| 63 | + |
| 64 | +# Data Model and Time Format |
| 65 | + |
| 66 | +See also the examples in the [Data Model section](https://colab.research.google.com/github/hapi-server/client-python-notebooks/blob/master/hapi_demo.ipynb) of the `hapiclient` Jupyter Notebook. The examples include |
| 67 | + |
| 68 | +1. Fast and well-tested conversion from ISO 8601 timestamp strings to Python `datetime` objects |
| 69 | +2. Putting the content of `data` in a Pandas `DataFrame` object |
| 70 | +3. Creating an Astropy NDArray |
| 71 | + |
| 72 | +A request for data of the form |
| 73 | +``` |
| 74 | +data, meta = hapi(server, dataset, parameters, start, stop) |
| 75 | +``` |
| 76 | + |
| 77 | +returns the [Numpy N-D array](https://docs.scipy.org/doc/numpy-1.15.1/user/quickstart.html) `data` and a Python dictionary `meta` from a HAPI-compliant data server `server`. The structure of `data` and `meta` mirrors the structure of a response from a HAPI server. |
| 78 | + |
| 79 | +The HAPI client data model is intentionally basic. There is an ongoing discussion of a data model for Heliophysics data among the [PyHC community](https://heliopython.org/). When this data model is complete, a function that converts `data` and `meta` to that data model will be included in the `hapiclient` package. |
| 80 | + |
| 81 | +# Development |
| 82 | + |
| 83 | +```bash |
| 84 | +git clone https://github.com/hapi-server/client-python |
| 85 | +cd client-python; pip install -e . |
| 86 | +``` |
| 87 | + |
| 88 | +The command `pip install -e .` creates symlinks so that the local package is |
| 89 | +used instead of an installed package. You may need to execute `pip uninstall hapiclient` to ensure the local package is used. To check the version installed, use `pip list | grep hapiclient`. |
| 90 | + |
| 91 | +To run tests before a commit, execute |
| 92 | + |
| 93 | +```bash |
| 94 | +make repository-test |
| 95 | +``` |
| 96 | + |
| 97 | +To run an individual unit test in a Python session, use, e.g., |
| 98 | + |
| 99 | +```python |
| 100 | +from hapiclient.test.test_hapi import test_reader_short |
| 101 | +test_reader_short() |
| 102 | +``` |
| 103 | + |
| 104 | +# Contact |
| 105 | + |
| 106 | +Submit bug reports and feature requests on the [repository issue |
| 107 | +tracker](https://github.com/hapi-server/client-python/issues>). |
| 108 | + |
| 109 | +# Appendix |
| 110 | + |
| 111 | +Fail-safe installation |
| 112 | + |
| 113 | +Python command line: |
| 114 | + |
| 115 | +```python |
| 116 | +import os |
| 117 | +print(os.popen("pip install hapiclient").read()) |
| 118 | +``` |
| 119 | + |
| 120 | +The above executes and displays the output of the operating system |
| 121 | +command `pip install hapiclient` using the shell environment |
| 122 | +associated with that installation of Python. |
| 123 | + |
| 124 | +This method addresses a problem that is sometimes encountered when |
| 125 | +attempting to use `pip` packages in Anaconda. To use a `pip` package |
| 126 | +in Anaconda, one must use the version of `pip` installed with Anaconda |
| 127 | +(it is usually under a subdirectory with the name `anaconda/`) as |
| 128 | +opposed to the one installed with the operating system. To see the |
| 129 | +location of ``pip`` used in a given Python session, enter |
| 130 | +`print(os.popen("which pip").read())`. |
0 commit comments