Skip to content

Commit

Permalink
updated docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@dchaddock
dchaddock committed Jun 24, 2024
1 parent 3283e41 commit c3ba984
Show file tree
Hide file tree
Showing 19 changed files with 337 additions and 409 deletions.
2 changes: 1 addition & 1 deletion docs/_extras/stylesheets/extra.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,4 +38,4 @@ h1 {

.add-bottom-space {
margin-bottom: 5px;
}
}
31 changes: 17 additions & 14 deletions ...e/advanced_usage/advanced_conjunctions.md → ...ced_usage/search/advanced_conjunctions.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Advanced conjunction searches

AuroraX's search engine provides an interface for running powerful and highly customizable conjunction search requests. While the [basic usage](/code/basic_usage/conjunctions/) section covers the quickest way to get started with conjunction searches, there are additional options for more advanced uses. This section will provide examples for some common complex searches.
AuroraX's search engine provides an interface for running powerful and highly customizable conjunction search requests. While the [basic usage](/code/basic_usage/search/conjunctions/) section covers the quickest way to get started with conjunction searches, there are additional options for more advanced uses. This section will provide examples for some common complex searches.

## Multi-conjunction searches

Expand All @@ -24,8 +24,9 @@ Below, we'll have a look at an example of a quadruple-conjunction search, using

```python
# imports
import pyaurorax
import datetime
import pyaurorax
aurorax = pyaurorax.PyAuroraX()

# set query parameters
start = datetime.datetime(2020, 1, 1, 0, 0, 0)
Expand All @@ -41,12 +42,12 @@ Below, we'll have a look at an example of a quadruple-conjunction search, using
distance = 500

# perform the search
s = pyaurorax.conjunctions.search(start=start,
end=end,
distance=distance,
ground=ground_params,
space=space_params,
verbose=True)
s = aurorax.search.conjunctions.search(start=start,
end=end,
distance=distance,
ground=ground_params,
space=space_params,
verbose=True)

# view the results
print(s.data)
Expand Down Expand Up @@ -173,8 +174,9 @@ Below is an example of a conjunction search using the advanced distances functio

```python
# imports
import pyaurorax
import datetime
import pyaurorax
aurorax = pyaurorax.PyAuroraX()

# set search parameters
start = datetime.datetime(2019, 1, 1, 0, 0, 0)
Expand All @@ -195,11 +197,12 @@ Below is an example of a conjunction search using the advanced distances functio
distance = 500

# create search object
s = pyaurorax.conjunctions.Search(start=start,
end=end,
distance=distance,
ground=ground_params,
space=space_params)
s = pyaurorax.search.ConjunctionSearch(aurorax_obj=aurorax,
start=start,
end=end,
distance=distance,
ground=ground_params,
space=space_params)
```

Now that we've created our search object, we can adjust the advanced distances to what we want.
Expand Down
63 changes: 32 additions & 31 deletions ...ode/advanced_usage/asynchronous_search.md → ...anced_usage/search/asynchronous_search.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,9 @@ This example will go through the steps of executing an asynchronous conjunction

```python
# imports
import pyaurorax
import datetime
import pyaurorax
aurorax = pyaurorax.PyAuroraX()

# set up search parameters
start = datetime.datetime(2019, 1, 1, 0, 0, 0)
Expand Down Expand Up @@ -64,12 +65,12 @@ This example will go through the steps of executing an asynchronous conjunction
}]

# initiate search
s = pyaurorax.conjunctions.search(start=start,
end=end,
distance=500,
ground=ground_params,
space=space_params
return_immediately=True)
s = aurorax.search.conjunctions.search(start=start,
end=end,
distance=500,
ground=ground_params,
space=space_params
return_immediately=True)

# do other useful things while waiting for results...
foo()
Expand Down Expand Up @@ -100,12 +101,12 @@ Asynchronous searches are set up and executed the same as regular searches. The

```python hl_lines="0-7"
# initiate search
s = pyaurorax.conjunctions.search(start=start,
end=end,
distance=500,
ground=ground_params,
space=space_params
return_immediately=True)
s = aurorax.search.conjunctions.search(start=start,
end=end,
distance=500,
ground=ground_params,
space=space_params
return_immediately=True)

# do other useful things while waiting for results...
foo()
Expand Down Expand Up @@ -134,12 +135,12 @@ Our working example illustrates this using a simple loop that checks for data ev

```python hl_lines="13-15"
# initiate search
s = pyaurorax.conjunctions.search(start=start,
end=end,
distance=500,
ground=ground_params,
space=space_params
return_immediately=True)
s = aurorax.search.conjunctions.search(start=start,
end=end,
distance=500,
ground=ground_params,
space=space_params
return_immediately=True)

# do other useful things while waiting for results...
foo()
Expand All @@ -166,12 +167,12 @@ When the [`check_for_data()`](/code/pyaurorax_api_reference/pyaurorax/conjunctio

```python hl_lines="17-18"
# initiate search
s = pyaurorax.conjunctions.search(start=start,
end=end,
distance=500,
ground=ground_params,
space=space_params
return_immediately=True)
s = aurorax.search.conjunctions.search(start=start,
end=end,
distance=500,
ground=ground_params,
space=space_params
return_immediately=True)

# do other useful things while waiting for results...
foo()
Expand All @@ -198,12 +199,12 @@ Included with every Search object is a [`wait()`](/code/pyaurorax_api_reference/

```python hl_lines="13-14"
# initiate search
s = pyaurorax.conjunctions.search(start=start,
end=end,
distance=500,
ground=ground_params,
space=space_params
return_immediately=True)
s = aurorax.search.conjunctions.search(start=start,
end=end,
distance=500,
ground=ground_params,
space=space_params
return_immediately=True)

# do other useful things while waiting for results...
foo()
Expand Down
7 changes: 3 additions & 4 deletions docs/code/advanced_usage/authentication.md → ...e/advanced_usage/search/authentication.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,16 +28,15 @@ Below we'll show an example of how to use your API key for interacting with secu

```python
import pyaurorax
pyaurorax.authenticate("API_KEY_HERE")
aurorax = pyaurorax.PyAuroraX(api_key="API_KEY_HERE")
```
If needed, you can get the currently-set API key for your application:

```python
import pyaurorax
pyaurorax.authenticate("API_KEY_HERE")
api_key = pyaurorax.api.get_api_key()
print(api_key)
aurorax = pyaurorax.PyAuroraX(api_key="API_KEY_HERE")
print(aurorax.api_key)
```

=== "Command Line"
Expand Down
127 changes: 9 additions & 118 deletions .../advanced_usage/availability_and_stats.md → ...ode/advanced_usage/search/availability.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@
# Data Availability and Statistics
# Data Availability

Since the AuroraX platform is built around metadata in a database, we lose a bit of visibility regarding what data is in the system at any given time. To help with this, we have two functions that can quickly provide data availability and statistics information to users. Below, we'll have a closer look at each of these functions and how they can be used.

## Data availability
Since the AuroraX platform is built around metadata in a database, we lose a bit of visibility regarding what data is in the system at any given time. To help with this, we have a function that provides data availability information to users.

Data availability information from AuroraX consists of the number of ephemeris or data product records for a given day and a given data source. We visualize it using the [Data Availability webpage](https://aurorax.space/data/availability){:target="_blank"}.

Expand All @@ -14,22 +12,23 @@ Below, we'll have a look at an example of retrieving data availability informati

=== "Python"

The [`availability`](/code/pyaurorax_api_reference/pyaurorax/availability/index.html){:target="_blank"} module has functions for retrieving the availability of ephemeris and data product records. These functions return a list of [`AvailabilityResult`](/code/pyaurorax_api_reference/pyaurorax/availability/index.html#pyaurorax.availability.AvailabilityResult){:target="_blank"} objects for every data source that matches the filter criteria provided to the function.
The [`search.availability`](/code/pyaurorax_api_reference/pyaurorax/search/availability/index.html){:target="_blank"} module has functions for retrieving the availability of ephemeris and data product records. These functions return a list of [`AvailabilityResult`](/code/pyaurorax_api_reference/pyaurorax/search/availability/index.html#pyaurorax.search.AvailabilityResult){:target="_blank"} objects for every data source that matches the filter criteria provided to the function.

```python
# imports
import pyaurorax
import datetime
import pyaurorax
aurorax = pyaurorax.PyAuroraX()

# set up availability params
start = datetime.date(2019, 1, 1)
end = datetime.date(2019, 1, 5)
program = "swarm"

# get availability information
availability = pyaurorax.availability.ephemeris(start,
end,
program=program)
availability = aurorax.search.availability.ephemeris(start,
end,
program=program)

# have a look at the availability data
print(availability)
Expand Down Expand Up @@ -68,7 +67,7 @@ Below, we'll have a look at an example of retrieving data availability informati

=== "IDL"

Use the [`aurorax_ephemeris_availability()`](/code/idlaurorax_api_reference/availability/ephemeris/){:target="_blank"} and [`aurorax_data_product_availability()`](/code/idlaurorax_api_reference/availability/data_products/){:target="_blank"} functions to retrieve data availability information from AuroraX in IDL.
Use the [`aurorax_ephemeris_availability()`](/code/idlaurorax_api_reference/search/availability/ephemeris/){:target="_blank"} and [`aurorax_data_product_availability()`](/code/idlaurorax_api_reference/search/availability/data_products/){:target="_blank"} functions to retrieve data availability information from AuroraX in IDL.

```idl
IDL> data = aurorax_ephemeris_availability('20200101','20200105',program='swarm')
Expand Down Expand Up @@ -158,111 +157,3 @@ Below, we'll have a look at an example of retrieving data availability informati
```
https://api.aurorax.space/api/v1/availability/ephemeris?start=2020-01-01&end=2020-01-31&program=swarm
```

## Data statistics

AuroraX also has the ability to inform on the total number of ephemeris or data product records there exists for each data source, along with the earliest/latest timestamp values. This information is part of the "stats" API endpoints, and visualized on the [Data Statistics webpage](https://aurorax.space/data/statistics){:target="_blank"}.

Below, we'll have a look at an example of retrieving data source statistics information programmatically.

!!! example "Example - get data statistics information"

In this example, the data source statistics of the TREx RGB in Gillam are retrieved.

=== "Python"

The [`sources`](/code/pyaurorax_api_reference/pyaurorax/sources/index.html){:target="_blank"} module has a function for retrieving statistics of a data source. The information retrieved includes the earliest and latest dates for ephemeris and data product records associated with the data source. A [`DataStatisticsResult`](/code/pyaurorax_api_reference/pyaurorax/sources/index.html#pyaurorax.sources.DataStatisticsResult){:target="_blank"} object is returned by this function.

```python
# imports
import pyaurorax
import datetime

# get identifier for the TREx RGB in Gillam
data_source = pyaurorax.sources.list(program="trex", platform="gillam", instrument_type="RGB ASI")
# retrieve stats for this data source
stats = pyaurorax.sources.get_stats(data_source[0].identifier, format=pyaurorax.FORMAT_IDENTIFIER_ONLY)

# have a look at the stats info we retrieved
print(stats)
```

Example output would look like:

```
DataSourceStatistics(data_source=DataSource(identifier=103),
earliest_ephemeris_loaded=datetime.datetime(2019, 9, 27, 1, 25),
latest_ephemeris_loaded=datetime.datetime(2020, 11, 30, 23, 59),
ephemeris_count=222573,
earliest_data_product_loaded=datetime.datetime(2019, 9, 27, 0, 0),
latest_data_product_loaded=datetime.datetime(2021, 10, 22, 23, 59),
data_product_count=28312)
```

=== "IDL"

Use the [`aurorax_sources_get_stats()`](/code/idlaurorax_api_reference/sources/stats/){:target="_blank"} function to retrieve additional information about a data source.

```idl
IDL> source = aurorax_sources_list(program='swarm', platform='swarma')
IDL> stats = aurorax_sources_get_stats(source[0].identifier)
IDL> help,stats
** Structure <69a75b30>, 7 tags, length=168, data length=168, refs=1:
DATA_SOURCE STRUCT -> <Anonymous> Array[1]
EARLIEST_EPHEMERIS_LOADED STRING '2013-11-26T00:00:00'
LATEST_EPHEMERIS_LOADED STRING '2021-12-10T23:59:00'
EPHEMERIS_COUNT LONG64 4229280
EARLIEST_DATA_PRODUCT_LOADED STRING '!NULL'
LATEST_DATA_PRODUCT_LOADED STRING '!NULL'
DATA_PRODUCT_COUNT LONG64 0
```

=== "Command Line"

You can use the aurorax-cli tool to retrieve data source statistics information too.

```console
$ aurorax-cli sources get_stats 103
```

Example output would be:

```
Data source: DataSource(identifier=103, program='trex', platform='gillam', instrument_type='RGB ASI', source_type='ground', display_name='TREx RGB GILL')
Ephemeris count: 222,573
Earliest ephemeris loaded: 2019-09-27 01:25:00
Latest ephemeris loaded: 2020-11-30 23:59:00
Data product count: 28,312
Earliest data product loaded: 2019-09-27 00:00:00
Latest data product loaded: 2021-10-22 23:59:00
```

!!! warning "Input is identifier number of data source"
This command requires the input be the identifier number of a data source, so before the below command we used the "list" command to find that TREx RGB in Gillam is identifier `103`.

For more usage details, you can look at the aurorax-cli help too.

```console
$ aurorax-cli sources get_stats --help
```

=== "Javascript"

There are many different ways in Javascript to send a GET request, so we'll show it using a basic HTTP request. You can do this with AJAX, JQuery, Node, React, etc.

```javascript
var xhr = new XMLHttpRequest();
xhr.open("GET", "https://api.aurorax.space/api/v1/data_sources/103");
xhr.send();
console.log(xhr.responseText)
```

=== "Browser"

You can also just make the request right from your browser. Copy the following URL and paste it in your browser URL bar.

```
https://api.aurorax.space/api/v1/data_sources/103
```
Loading

0 comments on commit c3ba984

Please sign in to comment.