Skip to content

Commit 4fd33cf

Browse files
lukecampbelllukecampbell
authored
Merge pull request #34 from axiom-data-science/docs
[OSRA-134] Improves documentation structure
2 parents 91f2309 + 9a3f066 commit 4fd33cf

File tree

4 files changed

+181
-191
lines changed

4 files changed

+181
-191
lines changed

‎docs/api.rst

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,9 @@
1-
:mod:`API`
2-
----------------------------
31

42
``intake-erddap`` Python API
53
=============================
64

75
.. toctree::
86
:maxdepth: 2
9-
:hidden:
107
:caption: Documentation
118

129

@@ -15,7 +12,7 @@
1512

1613

1714
.. autoclass:: intake_erddap.erddap_cat.ERDDAPCatalog
18-
:members: __init__, get_client, get_search_urls
15+
:members: get_client, get_search_urls
1916

2017
``intake-erddap`` source
2118
------------------------

‎docs/conf.py

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -56,11 +56,11 @@
5656
"sphinx.ext.extlinks",
5757
"sphinx.ext.intersphinx",
5858
"numpydoc",
59-
"IPython.sphinxext.ipython_directive",
60-
"IPython.sphinxext.ipython_console_highlighting",
59+
#"IPython.sphinxext.ipython_directive",
60+
#"IPython.sphinxext.ipython_console_highlighting",
6161
"sphinxcontrib.srclinks",
6262
"sphinx_markdown_tables",
63-
"myst_nb",
63+
#"myst_nb",
6464
]
6565

6666
# for compiling notebooks with mystnb

‎docs/index.rst

Lines changed: 177 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,21 +4,190 @@
44
contain the root `toctree` directive.
55
66
Welcome to intake-erddap's documentation!
7-
=======================================
7+
=========================================
8+
9+
.. toctree::
10+
:maxdepth: 2
11+
12+
API <api>
13+
GitHub repository <https://github.com/axiom-data-science/intake-axds>
14+
15+
Intake ERDDAP
16+
=============
17+
18+
Intake is a lightweight set of tools for loading and sharing data in data
19+
science projects. Intake ERDDAP provides a set of integrations for ERDDAP.
20+
21+
- Quickly identify all datasets from an ERDDAP service in a geographic region,
22+
or containing certain variables.
23+
- Produce a pandas DataFrame for a given dataset or query.
24+
- Get an xarray Dataset for the Gridded datasets.
25+
26+
27+
.. image:: https://img.shields.io/github/workflow/status/axiom-data-science/intake-erddap/Tests?logo=github&style=for-the-badge
28+
:alt: Build Status
29+
30+
.. image:: https://img.shields.io/codecov/c/github/axiom-data-science/intake-erddap.svg?style=for-the-badge
31+
:alt: Code Coverage
32+
33+
.. image:: https://img.shields.io/badge/License-BSD--2%20Clause-blue.svg?style=for-the-badge
34+
:alt: License:BSD
35+
36+
.. image:: https://img.shields.io/github/workflow/status/axiom-data-science/intake-erddap/linting%20with%20pre-commit?label=Code%20Style&style=for-the-badge
37+
:alt: Code Style Status
38+
39+
The project is available on `Github <https://github.com/axiom-data-science/intake-erddap/>`_.
40+
41+
42+
TODO: Summary
43+
44+
The Key features are:
45+
46+
- Pandas DataFrames for any TableDAP dataset.
47+
- xarray Datasets for any GridDAP datasets.
48+
- Query by any or all:
49+
- bounding box
50+
- time
51+
- CF ``standard_name``
52+
- variable name
53+
- Plaintext Search term
54+
- Save catalogs locally for future use.
55+
56+
57+
Requirements
58+
------------
59+
60+
- Python >= 3.8
861

962
Installation
1063
------------
1164

12-
To install from PyPI:
13-
>>> pip install intake-erddap
65+
In the very near future, we will be offering the project on conda and PyPI. In
66+
the meantime the project can be installed from github using pip::
1467

15-
.. toctree::
16-
:maxdepth: 2
68+
pip install -e 'git+https://github.com/axiom-data-science/intake-erddap/@master#egg=intake-erddap'
1769

18-
overview
19-
api
20-
GitHub repository <https://github.com/axiom-data-science/intake-axds>
2170

71+
Examples
72+
--------
73+
74+
To create an intake catalog for all of the ERDDAP's TableDAP offerings use::
75+
76+
import intake
77+
catalog = intake.open_erddap_cat(
78+
server="https://erddap.sensors.ioos.us/erddap"
79+
)
80+
81+
82+
The catalog objects behave like a dictionary with the keys representing the
83+
dataset's unique identifier within ERDDAP, and the values being the
84+
``TableDAPSource`` objects. To access a source object::
85+
86+
source = catalog["datasetid"]
87+
88+
From the source object, a pandas DataFrame can be retrieved::
89+
90+
df = source.read()
91+
92+
Scenarios
93+
---------
94+
95+
Consider a case where you need to find all wind data near Florida.::
96+
97+
import intake
98+
from datetime import datetime
99+
bbox = (-87.84, 24.05, -77.11, 31.27)
100+
catalog = intake.open_erddap_cat(
101+
server="https://erddap.sensors.ioos.us/erddap",
102+
bbox=bbox,
103+
start_time=datetime(2022, 1, 1),
104+
end_time=datetime(2023, 1, 1),
105+
standard_names=["wind_speed", "wind_from_direction"],
106+
)
107+
108+
df = next(catalog.values()).read()
109+
110+
111+
.. raw:: html
112+
113+
<table class="docutils align-default">
114+
<thead>
115+
<tr style="text-align: right;">
116+
<th></th>
117+
<th>time (UTC)</th>
118+
<th>wind_speed (m.s-1)</th>
119+
<th>wind_from_direction (degrees)</th>
120+
</tr>
121+
</thead>
122+
<tbody>
123+
<tr>
124+
<th>0</th>
125+
<td>2022-12-14T19:40:00Z</td>
126+
<td>7.0</td>
127+
<td>140.0</td>
128+
</tr>
129+
<tr>
130+
<th>1</th>
131+
<td>2022-12-14T19:20:00Z</td>
132+
<td>7.0</td>
133+
<td>120.0</td>
134+
</tr>
135+
<tr>
136+
<th>2</th>
137+
<td>2022-12-14T19:10:00Z</td>
138+
<td>NaN</td>
139+
<td>NaN</td>
140+
</tr>
141+
<tr>
142+
<th>3</th>
143+
<td>2022-12-14T19:00:00Z</td>
144+
<td>9.0</td>
145+
<td>130.0</td>
146+
</tr>
147+
<tr>
148+
<th>4</th>
149+
<td>2022-12-14T18:50:00Z</td>
150+
<td>9.0</td>
151+
<td>130.0</td>
152+
</tr>
153+
<tr>
154+
<th>...</th>
155+
<td>...</td>
156+
<td>...</td>
157+
<td>...</td>
158+
</tr>
159+
<tr>
160+
<th>48296</th>
161+
<td>2022-01-01T00:40:00Z</td>
162+
<td>4.0</td>
163+
<td>120.0</td>
164+
</tr>
165+
<tr>
166+
<th>48297</th>
167+
<td>2022-01-01T00:30:00Z</td>
168+
<td>3.0</td>
169+
<td>130.0</td>
170+
</tr>
171+
<tr>
172+
<th>48298</th>
173+
<td>2022-01-01T00:20:00Z</td>
174+
<td>4.0</td>
175+
<td>120.0</td>
176+
</tr>
177+
<tr>
178+
<th>48299</th>
179+
<td>2022-01-01T00:10:00Z</td>
180+
<td>4.0</td>
181+
<td>130.0</td>
182+
</tr>
183+
<tr>
184+
<th>48300</th>
185+
<td>2022-01-01T00:00:00Z</td>
186+
<td>4.0</td>
187+
<td>130.0</td>
188+
</tr>
189+
</tbody>
190+
</table>
22191

23192

24193
Indices and tables

0 commit comments

Comments
 (0)