diff --git a/docs/_extras/stylesheets/extra.css b/docs/_extras/stylesheets/extra.css index f31df25..55fcf35 100644 --- a/docs/_extras/stylesheets/extra.css +++ b/docs/_extras/stylesheets/extra.css @@ -38,4 +38,4 @@ h1 { .add-bottom-space { margin-bottom: 5px; -} \ No newline at end of file +} diff --git a/docs/code/advanced_usage/advanced_conjunctions.md b/docs/code/advanced_usage/search/advanced_conjunctions.md similarity index 91% rename from docs/code/advanced_usage/advanced_conjunctions.md rename to docs/code/advanced_usage/search/advanced_conjunctions.md index 838157a..9d5e82c 100644 --- a/docs/code/advanced_usage/advanced_conjunctions.md +++ b/docs/code/advanced_usage/search/advanced_conjunctions.md @@ -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 @@ -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) @@ -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) @@ -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) @@ -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. diff --git a/docs/code/advanced_usage/asynchronous_search.md b/docs/code/advanced_usage/search/asynchronous_search.md similarity index 80% rename from docs/code/advanced_usage/asynchronous_search.md rename to docs/code/advanced_usage/search/asynchronous_search.md index 0dd839c..2511a72 100644 --- a/docs/code/advanced_usage/asynchronous_search.md +++ b/docs/code/advanced_usage/search/asynchronous_search.md @@ -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) @@ -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() @@ -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() @@ -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() @@ -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() @@ -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() diff --git a/docs/code/advanced_usage/authentication.md b/docs/code/advanced_usage/search/authentication.md similarity index 94% rename from docs/code/advanced_usage/authentication.md rename to docs/code/advanced_usage/search/authentication.md index 16df2ea..eced62e 100644 --- a/docs/code/advanced_usage/authentication.md +++ b/docs/code/advanced_usage/search/authentication.md @@ -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" diff --git a/docs/code/advanced_usage/availability_and_stats.md b/docs/code/advanced_usage/search/availability.md similarity index 54% rename from docs/code/advanced_usage/availability_and_stats.md rename to docs/code/advanced_usage/search/availability.md index 6d6ff3a..202e3e0 100644 --- a/docs/code/advanced_usage/availability_and_stats.md +++ b/docs/code/advanced_usage/search/availability.md @@ -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"}. @@ -14,12 +12,13 @@ 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) @@ -27,9 +26,9 @@ Below, we'll have a look at an example of retrieving data availability informati 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) @@ -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') @@ -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 -> 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 - ``` diff --git a/docs/code/advanced_usage/contributing_data.md b/docs/code/advanced_usage/search/contributing_data.md similarity index 56% rename from docs/code/advanced_usage/contributing_data.md rename to docs/code/advanced_usage/search/contributing_data.md index a262b61..a83965a 100644 --- a/docs/code/advanced_usage/contributing_data.md +++ b/docs/code/advanced_usage/search/contributing_data.md @@ -39,27 +39,27 @@ There are four account types in AuroraX: ## Data sources -After obtaining sufficient privileges, the first step in uploading data to AuroraX is to create a data source. This data source will be associated with ephemeris and data product records in the database. In PyAuroraX the [`sources`](/code/pyaurorax_api_reference/pyaurorax/sources/index.html){:target="_blank"} module has the [`DataSource`](/code/pyaurorax_api_reference/pyaurorax/sources/index.html#pyaurorax.sources.DataSource){:target="_blank"} class and the [`add`](/code/pyaurorax_api_reference/pyaurorax/sources/index.html#pyaurorax.sources.add){:target="_blank"} function to facilitate this. +After obtaining sufficient privileges, the first step in uploading data to AuroraX is to create a data source. This data source will be associated with ephemeris and data product records in the database. In PyAuroraX the [`sources`](/code/pyaurorax_api_reference/pyaurorax/search/sources/index.html){:target="_blank"} module has the [`DataSource`](/code/pyaurorax_api_reference/pyaurorax/search/sources/index.html#pyaurorax.search.sources.DataSource){:target="_blank"} class and the [`add`](/code/pyaurorax_api_reference/pyaurorax/search/sources/index.html#pyaurorax.search.sources.add){:target="_blank"} function to facilitate this. ### Adding a data source -The [`DataSource`](/code/pyaurorax_api_reference/pyaurorax/sources/index.html#pyaurorax.sources.DataSource){:target="_blank"} class is used to add data sources to AuroraX. Some of the class attributes are required to create the data source in the database, while others are optional and can be added later: +The [`DataSource`](/code/pyaurorax_api_reference/pyaurorax/search/sources/index.html#pyaurorax.sources.DataSource){:target="_blank"} class is used to add data sources to AuroraX. Some of the class attributes are required to create the data source in the database, while others are optional and can be added later: **Required attributes:** -* [`program`](/code/pyaurorax_api_reference/pyaurorax/sources/index.html#pyaurorax.sources.DataSource.program){:target="_blank"} -* [`platform`](/code/pyaurorax_api_reference/pyaurorax/sources/index.html#pyaurorax.sources.DataSource.platform){:target="_blank"} -* [`instrument_type`](/code/pyaurorax_api_reference/pyaurorax/sources/index.html#pyaurorax.sources.DataSource.instrument_type){:target="_blank"} -* [`source_type`](/code/pyaurorax_api_reference/pyaurorax/sources/index.html#pyaurorax.sources.DataSource.source_type){:target="_blank"} -* [`display_name`](/code/pyaurorax_api_reference/pyaurorax/sources/index.html#pyaurorax.sources.DataSource.display_name){:target="_blank"} +* [`program`](/code/pyaurorax_api_reference/pyaurorax/search/sources/index.html#pyaurorax.search.sources.DataSource.program){:target="_blank"} +* [`platform`](/code/pyaurorax_api_reference/pyaurorax/search/sources/index.html#pyaurorax.search.sources.DataSource.platform){:target="_blank"} +* [`instrument_type`](/code/pyaurorax_api_reference/pyaurorax/search/sources/index.html#pyaurorax.search.sources.DataSource.instrument_type){:target="_blank"} +* [`source_type`](/code/pyaurorax_api_reference/pyaurorax/search/sources/index.html#pyaurorax.search.sources.DataSource.source_type){:target="_blank"} +* [`display_name`](/code/pyaurorax_api_reference/pyaurorax/search/sources/index.html#pyaurorax.search.sources.DataSource.display_name){:target="_blank"} **Optional attributes:** -* [`identifier`](/code/pyaurorax_api_reference/pyaurorax/sources/index.html#pyaurorax.sources.DataSource.identifier){:target="_blank"} -* [`metadata`](/code/pyaurorax_api_reference/pyaurorax/sources/index.html#pyaurorax.sources.DataSource.metadata){:target="_blank"} -* [`maintainers`](/code/pyaurorax_api_reference/pyaurorax/sources/index.html#pyaurorax.sources.DataSource.maintainers){:target="_blank"} -* [`ephemeris_metadata_schema`](/code/pyaurorax_api_reference/pyaurorax/sources/index.html#pyaurorax.sources.DataSource.ephemeris_metadata_schema){:target="_blank"} -* [`data_product_metadata_schema`](/code/pyaurorax_api_reference/pyaurorax/sources/index.html#pyaurorax.sources.DataSource.data_product_metadata_schema){:target="_blank"} +* [`identifier`](/code/pyaurorax_api_reference/pyaurorax/search/sources/index.html#pyaurorax.search.sources.DataSource.identifier){:target="_blank"} +* [`metadata`](/code/pyaurorax_api_reference/pyaurorax/search/sources/index.html#pyaurorax.search.sources.DataSource.metadata){:target="_blank"} +* [`maintainers`](/code/pyaurorax_api_reference/pyaurorax/search/sources/index.html#pyaurorax.search.sources.DataSource.maintainers){:target="_blank"} +* [`ephemeris_metadata_schema`](/code/pyaurorax_api_reference/pyaurorax/search/sources/index.html#pyaurorax.search.sources.DataSource.ephemeris_metadata_schema){:target="_blank"} +* [`data_product_metadata_schema`](/code/pyaurorax_api_reference/pyaurorax/search/sources/index.html#pyaurorax.search.sources.DataSource.data_product_metadata_schema){:target="_blank"} ### Example: adding a data source @@ -68,6 +68,7 @@ In this example we add a data source using the required attributes along with th ```python # imports import pyaurorax +aurorax = pyaurorax.PyAuroraX() # set data source values program = "example-program" @@ -105,15 +106,15 @@ metadata_schema_data_products = [ ] # make DataSource object -data_source = pyaurorax.sources.DataSource(program=program, - platform=platform, - instrument_type=instrument_type, - source_type=source_type, display_name=display_name, - ephemeris_metadata_schema=metadata_schema_ephemeris, - data_product_metadata_schema=metadata_schema_data_products) +data_source = pyaurorax.search.DataSource(program=program, + platform=platform, + instrument_type=instrument_type, + source_type=source_type, display_name=display_name, + ephemeris_metadata_schema=metadata_schema_ephemeris, + data_product_metadata_schema=metadata_schema_data_products) # add to AuroraX -r = pyaurorax.sources.add(source) +r = aurorax.search.sources.add(source) identifier = r.identifier ``` @@ -121,11 +122,11 @@ When the adding operation is successful, the return value `r` from the API is a ### Updating data sources -There are two functions for updating the information associated with a data source in the AuroraX database: [`sources.update_partial`](/code/pyaurorax_api_reference/pyaurorax/sources/index.html#pyaurorax.sources.update_partial){:target="_blank"}, which updates the values for specified attributes, and a full [`sources.update`](/code/pyaurorax_api_reference/pyaurorax/sources/index.html#pyaurorax.sources.update){:target="_blank"} function that replaces the database record with a new DataSource object passed in. We recommend using `sources.update_partial` whenever possible because it reduces the risk of accidental data loss. +There are two functions for updating the information associated with a data source in the AuroraX database: [`sources.update_partial`](/code/pyaurorax_api_reference/pyaurorax/search/sources/index.html#pyaurorax.search.sources.update_partial){:target="_blank"}, which updates the values for specified attributes, and a full [`sources.update`](/code/pyaurorax_api_reference/pyaurorax/search/sources/index.html#pyaurorax.search.sources.update){:target="_blank"} function that replaces the database record with a new DataSource object passed in. We recommend using `sources.update_partial` whenever possible because it reduces the risk of accidental data loss. ### Example: partial update of a data source -In this example we perform partial updates to the data source `r` we created in the previous example. To use the [`sources.update_partial`](/code/pyaurorax_api_reference/pyaurorax/sources/index.html#pyaurorax.sources.update_partial){:target="_blank"} function we have to include the identifier of the data source, then any fields we want to modify. We will change the display name of the data source and add an existing AuroraX account as a maintainer. +In this example we perform partial updates to the data source `r` we created in the previous example. To use the [`sources.update_partial`](/code/pyaurorax_api_reference/pyaurorax/search/sources/index.html#pyaurorax.sources.update_partial){:target="_blank"} function we have to include the identifier of the data source, then any fields we want to modify. We will change the display name of the data source and add an existing AuroraX account as a maintainer. ```python identifier = r.identifier @@ -136,44 +137,44 @@ updated_r = pyaurorax.sources.update_partial(identifier=ds.identifier, ### Example: full update of a data source -The same task of modifying data source attributes can be accomplished with the [`sources.update`](/code/pyaurorax_api_reference/pyaurorax/sources/index.html#pyaurorax.sources.update){:target="_blank"} function. The difference in using this function is that we must pass in a full `DataSource` as the argument, and this object must have the changes we wish to be made. +The same task of modifying data source attributes can be accomplished with the [`sources.update`](/code/pyaurorax_api_reference/pyaurorax/search/sources/index.html#pyaurorax.search.sources.update){:target="_blank"} function. The difference in using this function is that we must pass in a full `DataSource` as the argument, and this object must have the changes we wish to be made. Continuing with the example of adding a data source, `r`, we will update its display name and maintainers list. For the sake of completeness, let us retrieve the data source from the database first. Note that since `sources.update` will rewrite the database with the argument we pass in, it's important to retrieve our working data source with the `format="full_record"` option so that it contains all the information. ```python -ds = pyaurorax.sources.get(program="example-program", - platform="example-platform", - instrument_type="example-instrument", - format="full_record") +ds = aurorax.search.sources.get(program="example-program", + platform="example-platform", + instrument_type="example-instrument", + format="full_record") # update data source's attributes ds.display_name = "New Display Name" ds.maintainers = ["maintainer@program.com"] # update on AuroraX -updated_ds = pyaurorax.sources.update(ds) +updated_ds = aurorax.search.sources.update(ds) ``` ## Ephemeris records -Ephemeris records uploaded to AuroraX can be found in conjunction searches and ephemeris searches by anyone using the platform. Using the [`ephemeris`](/code/pyaurorax_api_reference/pyaurorax/ephemeris/index.html){:target="_blank"} module, records are uploaded and updated using the [`Ephemeris`](/code/pyaurorax_api_reference/pyaurorax/ephemeris/index.html#pyaurorax.ephemeris.Ephemeris){:target="_blank"} class and [`upload`](/code/pyaurorax_api_reference/pyaurorax/ephemeris/index.html#pyaurorax.ephemeris.upload){:target="_blank"} function. +Ephemeris records uploaded to AuroraX can be found in conjunction searches and ephemeris searches by anyone using the platform. Using the [`ephemeris`](/code/pyaurorax_api_reference/pyaurorax/search/ephemeris/index.html){:target="_blank"} module, records are uploaded and updated using the [`Ephemeris`](/code/pyaurorax_api_reference/pyaurorax/search/ephemeris/index.html#pyaurorax.search.ephemeris.Ephemeris){:target="_blank"} class and [`upload`](/code/pyaurorax_api_reference/pyaurorax/search/ephemeris/index.html#pyaurorax.search.ephemeris.upload){:target="_blank"} function. ### Example: uploading an ephemeris record In this example we create two `Ephemeris` objects associated with the same data source and upload them to the database. `Ephemeris` objects hold a reference to their data source, and so we first have to retrieve the data source. ```python -ds = pyaurorax.sources.get(program="example-program", - platform="example-platform", - instrument_type="example-instrument") +ds = aurorax.search.sources.get(program="example-program", + platform="example-platform", + instrument_type="example-instrument") ``` -Next, we create two `Ephemeris` objects one minute apart. Note that the location attributes are passed in as a [`pyaurorax.Location`](/code/pyaurorax_api_reference/pyaurorax/location.html#pyaurorax.location.Location){:target="_blank"} object. +Next, we create two `Ephemeris` objects one minute apart. Note that the location attributes are passed in as a [`pyaurorax.search.Location`](/code/pyaurorax_api_reference/pyaurorax/search/location.html#pyaurorax.location.Location){:target="_blank"} object. ```python epoch = datetime.datetime(2020, 1, 1, 0, 0) -location_geo = pyaurorax.Location(lat=51.049999, lon=-114.066666) -location_gsm = pyaurorax.Location(lat=150.25, lon=-10.75) +location_geo = pyaurorax.search.Location(lat=51.049999, lon=-114.066666) +location_gsm = pyaurorax.search.Location(lat=150.25, lon=-10.75) nbtrace = pyaurorax.Location(lat=1.23, lon=45.6) sbtrace = pyaurorax.Location(lat=7.89, lon=101.23) metadata = { @@ -182,13 +183,13 @@ metadata = { } # create first Ephemeris object -e1 = pyaurorax.ephemeris.Ephemeris(data_source=ds, - epoch=epoch, - location_geo=location_geo, - location_gsm=location_gsm, - nbtrace=nbtrace, - sbtrace=sbtrace, - metadata=metadata) +e1 = pyaurorax.search.Ephemeris(data_source=ds, + epoch=epoch, + location_geo=location_geo, + location_gsm=location_gsm, + nbtrace=nbtrace, + sbtrace=sbtrace, + metadata=metadata) # create second Ephemeris object epoch2 = datetime.datetime(2020, 1, 1, 0, 1) @@ -196,16 +197,16 @@ metadata2 = { "example_meta1": "testing12", "example_meta2": "testing22", } -e2 = pyaurorax.ephemeris.Ephemeris(data_source=ds, - epoch=epoch2, - location_geo=location_geo, - location_gsm=location_gsm, - nbtrace=nbtrace, - sbtrace=sbtrace, - metadata=metadata2) +e2 = pyaurorax.search.Ephemeris(data_source=ds, + epoch=epoch2, + location_geo=location_geo, + location_gsm=location_gsm, + nbtrace=nbtrace, + sbtrace=sbtrace, + metadata=metadata2) ``` -To upload the records, we pass them in a list to the [`upload`](/code/pyaurorax_api_reference/pyaurorax/ephemeris/index.html#pyaurorax.ephemeris.upload){:target="_blank"} function along with the identifier of the data source. `validate_source` is an optional argument that, if True, will independently check the validity of each record's `data_source` attribute against the data source associated with the `identifier` argument in the database. It is recommended to use this optional check. +To upload the records, we pass them in a list to the [`upload`](/code/pyaurorax_api_reference/pyaurorax/search/ephemeris/index.html#pyaurorax.search.ephemeris.upload){:target="_blank"} function along with the identifier of the data source. `validate_source` is an optional argument that, if True, will independently check the validity of each record's `data_source` attribute against the data source associated with the `identifier` argument in the database. It is recommended to use this optional check. ```python pyaurorax.ephemeris.upload(identifier=ds.identifier, @@ -227,23 +228,23 @@ e1.metadata = { "example_meta2": "testing2_updated", } -pyaurorax.ephemeris.upload(identifier=ds.identifier, - records=[e1], - validate_source=True) +aurorax.search.ephemeris.upload(identifier=ds.identifier, + records=[e1], + validate_source=True) ``` ## Data product records -Data product records uploaded to AuroraX can be found in data product searches by anyone using the platform. Using the [`data_products`](/code/pyaurorax_api_reference/pyaurorax/data_products/index.html){:target="_blank"} module, records are uploaded and updated using the [`DataProduct`](/code/pyaurorax_api_reference/pyaurorax/data_products/index.html#pyaurorax.data_products.DataProduct){:target="_blank"} class and [`upload`](/code/pyaurorax_api_reference/pyaurorax/data_products/index.html#pyaurorax.data_products.upload){:target="_blank"} function. +Data product records uploaded to AuroraX can be found in data product searches by anyone using the platform. Using the [`data_products`](/code/pyaurorax_api_reference/pyaurorax/search/data_products/index.html){:target="_blank"} module, records are uploaded and updated using the [`DataProduct`](/code/pyaurorax_api_reference/pyaurorax/search/data_products/index.html#pyaurorax.search.data_products.DataProduct){:target="_blank"} class and [`upload`](/code/pyaurorax_api_reference/pyaurorax/search/data_products/index.html#pyaurorax.search.data_products.upload){:target="_blank"} function. ### Example: uploading a data product record In this example we create two `DataProduct` objects associated with the same data source and upload them to the database. `DataProduct` objects hold a reference to their data source, and so we first have to retrieve the data source. ```python -ds = pyaurorax.sources.get(program="example-program", - platform="example-platform", - instrument_type="example-instrument") +ds = aurorax.search.sources.get(program="example-program", + platform="example-platform", + instrument_type="example-instrument") ``` Next, we create two `DataProduct` objects one day apart. @@ -260,31 +261,31 @@ start_dt = datetime.datetime(2020, 1, 1, 0, 0, 0) end_dt = start_dt.replace(hour=23, minute=59, second=59) # create first DataProduct object -dp1 = pyaurorax.data_products.DataProduct(data_source=ds, - data_product_type=data_product_type, - url=url, - start=start_dt, - end=end_dt, - metadata=metadata) +dp1 = pyaurorax.search.DataProduct(data_source=ds, + data_product_type=data_product_type, + url=url, + start=start_dt, + end=end_dt, + metadata=metadata) # create second DataProduct object start_dt2 = datetime.datetime(2020, 1, 2, 0, 0, 0) end_dt2 = start_dt2.replace(hour=23, minute=59, second=59) url2 = "example2.jpg" -dp2 = pyaurorax.data_products.DataProduct(data_source=ds, - data_product_type=data_product_type, - url=url2, - start=start_dt2, - end=end_dt2, - metadata=metadata) +dp2 = pyaurorax.search.DataProduct(data_source=ds, + data_product_type=data_product_type, + url=url2, + start=start_dt2, + end=end_dt2, + metadata=metadata) ``` -To upload the records, we pass them in a list to the [`upload`](/code/pyaurorax_api_reference/pyaurorax/data_products/index.html#pyaurorax.data_products.upload){:target="_blank"} function along with the identifier of the data source. `validate_source` is an optional argument that, if True, will independently check the validity of each record's `data_source` attribute against the data source associated with the `identifier` argument in the database. It is recommended to use this optional check. +To upload the records, we pass them in a list to the [`upload`](/code/pyaurorax_api_reference/pyaurorax/search/data_products/index.html#pyaurorax.search.data_products.upload){:target="_blank"} function along with the identifier of the data source. `validate_source` is an optional argument that, if True, will independently check the validity of each record's `data_source` attribute against the data source associated with the `identifier` argument in the database. It is recommended to use this optional check. ```python -pyaurorax.data_products.upload(identifier=ds.identifier, - records=[dp1, dp2], - validate_source=True) +aurorax.search.data_products.upload(identifier=ds.identifier, + records=[dp1, dp2], + validate_source=True) ``` ### Updating data product records @@ -301,7 +302,7 @@ dp1.metadata = { "example_meta2": "example2_updated", } -pyaurorax.data_products.upload(identifier=ds.identifier, - records=[dp1], - validate_source=True) +aurorax.search.data_products.upload(identifier=ds.identifier, + records=[dp1], + validate_source=True) ``` \ No newline at end of file diff --git a/docs/code/advanced_usage/searches_with_metadata_filters.md b/docs/code/advanced_usage/search/searches_with_metadata_filters.md similarity index 89% rename from docs/code/advanced_usage/searches_with_metadata_filters.md rename to docs/code/advanced_usage/search/searches_with_metadata_filters.md index 3a1206c..932e3cf 100644 --- a/docs/code/advanced_usage/searches_with_metadata_filters.md +++ b/docs/code/advanced_usage/search/searches_with_metadata_filters.md @@ -50,8 +50,9 @@ To include a metadata filter in a conjunction search, place it within the criter ```python # imports - import pyaurorax import datetime + import pyaurorax + aurorax = pyaurorax.PyAuroraX() # set up search parameters start = datetime.datetime(2019, 1, 1, 0, 0, 0) @@ -94,12 +95,12 @@ To include a metadata filter in a conjunction search, place it within the criter 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) # output data print(s.data) @@ -210,22 +211,19 @@ To include a metadata filter in a conjunction search, place it within the criter To include a metadata filter in an ephemeris search, supply it as an addition argument to the search function. -!!! info "Improvement on its way for PyAuroraX" - - Please note - an improvement to the structure of metadata filters is coming soon to PyAuroraX, as part of release v0.10.0. See the milestone [here](https://github.com/aurorax-space/pyaurorax/milestone/3){:target="_blank"} and the specific issue ticket for the improvement is [!28](https://github.com/aurorax-space/pyaurorax/issues/28){:target="_blank"}. - !!! example "Ephemeris search with metadata filters" In the following example, we are searching for ephemeris records over one day for the "swarm" program and "swarma" platform, where the metadata filter for "nbtrace_region" is either "north polar cap" or "north auroral oval". === "Python" - We use the [`pyaurorax.ephemeris.search()`](/code/pyaurorax_api_reference/pyaurorax/ephemeris/index.html#pyaurorax.ephemeris.search){:target="_blank"} function with the `metadata_filters_logical_operator` and `metadata_filters` parameters supplied. + We use the [`aurorax.search.ephemeris.search()`](/code/pyaurorax_api_reference/pyaurorax/search/ephemeris/index.html#pyaurorax.ephemeris.search){:target="_blank"} function with the `metadata_filters_logical_operator` and `metadata_filters` parameters supplied. ```python # imports - import pyaurorax import datetime + import pyaurorax + aurorax = pyaurorax.PyAuroraX() # set up search parameters start = datetime.datetime(2019, 1, 1, 0, 0, 0) @@ -245,13 +243,13 @@ To include a metadata filter in an ephemeris search, supply it as an addition ar ] # perform the search - s = pyaurorax.ephemeris.search(start=start, - end=end, - programs=programs, - platforms=platforms, - metadata_filters_logical_operator=metadata_filters_logical_operator, - metadata_filters=metadata_filters, - verbose=True) + s = aurorax.search.ephemeris.search(start=start, + end=end, + programs=programs, + platforms=platforms, + metadata_filters_logical_operator=metadata_filters_logical_operator, + metadata_filters=metadata_filters, + verbose=True) # output data print(s.data) @@ -378,22 +376,19 @@ To include a metadata filter in an ephemeris search, supply it as an addition ar To include a metadata filter in a data product search, supply it as an addition argument to the search function. -!!! info "Improvement on its way for PyAuroraX" - - Please note - an improvement to the structure of metadata filters is coming soon to PyAuroraX, as part of release v0.10.0. See the milestone [here](https://github.com/aurorax-space/pyaurorax/milestone/3){:target="_blank"} and the specific issue ticket for the improvement is [!28](https://github.com/aurorax-space/pyaurorax/issues/28){:target="_blank"}. - !!! example "Data product search with metadata filters" In the following example, we are searching for data product records over one day for the one of the TREx RGB instruments (Gillam), where the metadata filter for "keogram_type" is either "daily" or "hourly". === "Python" - We use the [`pyaurorax.data_products.search()`](/code/pyaurorax_api_reference/pyaurorax/data_products/index.html#pyaurorax.data_products.search){:target="_blank"} function with the `metadata_filters_logical_operator` and `metadata_filters` parameters supplied. + We use the [`aurorax.search.data_products.search()`](/code/pyaurorax_api_reference/pyaurorax/search/data_products/index.html#pyaurorax.data_products.search){:target="_blank"} function with the `metadata_filters_logical_operator` and `metadata_filters` parameters supplied. ```python # imports - import pyaurorax import datetime + import pyaurorax + aurorax = pyaurorax.PyAuroraX() # set up search parameters start = datetime.datetime(2020, 1, 1, 0, 0, 0) @@ -414,14 +409,14 @@ To include a metadata filter in a data product search, supply it as an addition ] # perform the search - s = pyaurorax.data_products.search(start=start, - end=end, - programs=programs, - platforms=platforms, - instrument_types=instrument_types, - metadata_filters_logical_operator=metadata_filters_logical_operator, - metadata_filters=metadata_filters, - verbose=True) + s = aurorax.search.data_products.search(start=start, + end=end, + programs=programs, + platforms=platforms, + instrument_types=instrument_types, + metadata_filters_logical_operator=metadata_filters_logical_operator, + metadata_filters=metadata_filters, + verbose=True) # output data print(s.data) diff --git a/docs/code/advanced_usage/swarmaurora.md b/docs/code/advanced_usage/search/swarmaurora.md similarity index 87% rename from docs/code/advanced_usage/swarmaurora.md rename to docs/code/advanced_usage/search/swarmaurora.md index e39f371..c4ede29 100644 --- a/docs/code/advanced_usage/swarmaurora.md +++ b/docs/code/advanced_usage/search/swarmaurora.md @@ -10,7 +10,7 @@ Swarm-Aurora can be a very helpful tool for exploring conjunction searches and e === "Python" - Using the [`conjunctions.swarmaurora`](/code/pyaurorax_api_reference/pyaurorax/conjunctions/swarmaurora/){:target="_blank"} submodule, you can open a conjunction search in Swarm-Aurora using a single line of Python code. This procedure uses Python's built-in [`webbrowser`](https://docs.python.org/3/library/webbrowser.html){:target="_blank"} module to launch a browser tab, with Swarm-Aurora loaded in it. + Using the [`search.conjunctions.swarmaurora`](/code/pyaurorax_api_reference/pyaurorax/search/conjunctions/swarmaurora/){:target="_blank"} submodule, you can open a conjunction search in Swarm-Aurora using a single line of Python code. This procedure uses Python's built-in [`webbrowser`](https://docs.python.org/3/library/webbrowser.html){:target="_blank"} module to launch a browser tab, with Swarm-Aurora loaded in it. PyAuroraX supports two ways of opening conjunction searches in Swarm-Aurora: @@ -21,8 +21,9 @@ Swarm-Aurora can be a very helpful tool for exploring conjunction searches and e ```python # imports - import pyaurorax import datetime + import pyaurorax + aurorax = pyaurorax.PyAuroraX() # define search parameters start = datetime.datetime(2019, 1, 1, 0, 0, 0) @@ -42,30 +43,30 @@ Swarm-Aurora can be a very helpful tool for exploring conjunction searches and e distance = 500 # run conjunction search request - 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) ``` With the search now done and saved to the `s` variable, we can either open the results automatically in a browser: ```python - pyaurorax.conjunctions.swarmaurora.open_in_browser(s) + aurorax.search.conjunctions.swarmaurora.open_in_browser(s) ``` Or, output the URL so you can copy and paste it into your preferred browser manually. ```python - print(pyaurorax.conjunctions.swarmaurora.get_url(s)) + print(aurorax.search.conjunctions.swarmaurora.get_url(s)) ``` - If you run into issues with the default browser, or just want to use a different one, you can set the `browser` parameter to one of the supported browsers from the Python library. To view all browser options, refer to the table [here](https://docs.python.org/3/library/webbrowser.html#webbrowser.get). For example `pyaurorax.conjunctions.swarmaurora.open_in_browser(s, browser='google-chrome')`. + If you run into issues with the default browser, or just want to use a different one, you can set the `browser` parameter to one of the supported browsers from the Python library. To view all browser options, refer to the table [here](https://docs.python.org/3/library/webbrowser.html#webbrowser.get). For example `pyaurorax.search.conjunctions.swarmaurora.open_in_browser(s, browser='google-chrome')`. === "IDL" - Using the [`aurorax_open_conjunctions_in_swarmaurora`](/code/idlaurorax_api_reference/conjunctions/open_in_swarmaurora/){:target="_blank"} procedure, you can open a conjunction search in Swarm-Aurora using a single IDL command. This procedure uses IDL's `widget_browser()` function to render a window that is a functional browser, with Swarm-Aurora loaded in it. + Using the [`aurorax_open_conjunctions_in_swarmaurora`](/code/idlaurorax_api_reference/search/conjunctions/open_in_swarmaurora/){:target="_blank"} procedure, you can open a conjunction search in Swarm-Aurora using a single IDL command. This procedure uses IDL's `widget_browser()` function to render a window that is a functional browser, with Swarm-Aurora loaded in it. !!! danger "Bug in IDL 8.8.1 and earlier" @@ -226,7 +227,7 @@ Swarm-Aurora can be a very helpful tool for exploring conjunction searches and e === "IDL" - Using the [`aurorax_save_swarmaurora_custom_import_file`](/code/idlaurorax_api_reference/conjunctions/save_swarmaurora_import_file/){:target="_blank"} procedure, you can download a Swarm-Aurora "custom import" JSON file. This file can be then shared with others or manually loaded into Swarm-Aurora. + Using the [`aurorax_save_swarmaurora_custom_import_file`](/code/idlaurorax_api_reference/search/conjunctions/save_swarmaurora_import_file/){:target="_blank"} procedure, you can download a Swarm-Aurora "custom import" JSON file. This file can be then shared with others or manually loaded into Swarm-Aurora. To start, we'll do a simple conjunction search. diff --git a/docs/code/basic_usage/overview.md b/docs/code/basic_usage/overview.md index 7e8cbbb..9d9c7e3 100644 --- a/docs/code/basic_usage/overview.md +++ b/docs/code/basic_usage/overview.md @@ -1,30 +1,26 @@ # The Basics -There are a few main categories of functions in the AuroraX programmatic tools: - -- [Interacting with data sources](/code/basic_usage/data_sources/) -- [Performing conjunction searches](/code/basic_usage/conjunctions/) -- [Performing ephemeris searches](/code/basic_usage/ephemeris/) -- [Performing data product searches](/code/basic_usage/data_products/) -- [Retrieving data availability and statistics information](/code/advanced_usage/availability_and_stats/) -- [Uploading ephemeris and data product data](/code/advanced_usage/contributing_data/) - -## What functions can we do - -Below is a list of the different functions that are available to do programmatically. - -- Data Sources - - [retrieve data source information](/code/basic_usage/data_sources/) - - [create and update data sources (advanced)](/code/advanced_usage/contributing_data/) -- Conjunction, ephemeris, and data product searching - - [search for conjunctions](/code/basic_usage/conjunctions/) - - [search for ephemeris data](/code/basic_usage/ephemeris/) - - [search for data product data](/code/basic_usage/data_products/) - - [retrieve information about a search request ID](/code/advanced_usage/asynchronous_search/) -- Managing data - - [upload ephemeris metadata (advanced)](/code/advanced_usage/contributing_data/) - - [upload data product metadata (advanced)](/code/advanced_usage/contributing_data/) - -## Next steps - -The rest of the pages in this "Basic Usage" section have detailed examples of each of these tasks. The examples include the code for doing each in a variety of ways (ie. Python, IDL, Javascript, command line). \ No newline at end of file +!!! warning "Update in progress" + + We are currently in the middle of updating these 'Basic Usage' examples to sync up with the latest 1.0.0 major release of PyAuroraX and IDL-AuroraX. This page will be updated shortly. + + Please view our [comprehensive guides / crib sheets](https://data.phys.ucalgary.ca/working_with_data/#crib-sheets) or [quick examples](https://data.phys.ucalgary.ca/working_with_data/#quick-examples) for now. + +## Data Access + +Will be updated shortly. + +## Analysis Support Software + +Will be updated shortly. + +## TREx Auroral Transport Model (ATM) + +Will be updated shortly. + +## AuroraX Search Engine + +- [Interacting with data sources](search/data_sources.md) +- [Performing conjunction searches](search/conjunctions.md) +- [Performing ephemeris searches](search/ephemeris.md) +- [Performing data product searches](search/data_products.md) diff --git a/docs/code/basic_usage/conjunctions.md b/docs/code/basic_usage/search/conjunctions.md similarity index 92% rename from docs/code/basic_usage/conjunctions.md rename to docs/code/basic_usage/search/conjunctions.md index 384545f..08563c1 100644 --- a/docs/code/basic_usage/conjunctions.md +++ b/docs/code/basic_usage/search/conjunctions.md @@ -20,8 +20,9 @@ Below, we'll have a look at how to run "Example 1" on the Conjunction Search web ```python # imports - import pyaurorax import datetime + import pyaurorax + aurorax = pyaurorax.PyAuroraX() # define search parameters start = datetime.datetime(2019, 1, 1, 0, 0, 0) @@ -42,12 +43,12 @@ Below, we'll have a look at how to run "Example 1" on the Conjunction Search web # run conjunction search request - 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) # have a look at our results print(s.data) @@ -79,7 +80,7 @@ Below, we'll have a look at how to run "Example 1" on the Conjunction Search web === "IDL" - IDL-AuroraX provides the [`aurorax_conjunction_search()`](/code/idlaurorax_api_reference/conjunctions/search/){:target="_blank"} function to perform a conjunction search. Further, there are a couple helper functions to create the necessary objects as parameters to the search function. + IDL-AuroraX provides the [`aurorax_conjunction_search()`](/code/idlaurorax_api_reference/search/conjunctions/search/){:target="_blank"} function to perform a conjunction search. Further, there are a couple helper functions to create the necessary objects as parameters to the search function. ```idl ; define timeframe and distance parameters @@ -148,7 +149,7 @@ Below, we'll have a look at how to run "Example 1" on the Conjunction Search web } ``` - Lastly, you can visualize this conjunction search in the Swarm-Aurora Conjunction Browser using a handy procedure called [`aurorax_open_conjunctions_in_swarmaurora`](/code/idlaurorax_api_reference/conjunctions/open_in_swarmaurora/){:target="_blank"}: + Lastly, you can visualize this conjunction search in the Swarm-Aurora Conjunction Browser using a handy procedure called [`aurorax_open_conjunctions_in_swarmaurora`](/code/idlaurorax_api_reference/search/conjunctions/open_in_swarmaurora/){:target="_blank"}: ```idl IDL> aurorax_open_conjunctions_in_swarmaurora,response.request_id diff --git a/docs/code/basic_usage/data_products.md b/docs/code/basic_usage/search/data_products.md similarity index 94% rename from docs/code/basic_usage/data_products.md rename to docs/code/basic_usage/search/data_products.md index a341739..462cfe3 100644 --- a/docs/code/basic_usage/data_products.md +++ b/docs/code/basic_usage/search/data_products.md @@ -18,8 +18,9 @@ Let's say we want to retrieve all the data product records the TREx RGB in Fort ```python # imports - import pyaurorax import datetime + import pyaurorax + aurorax = pyaurorax.PyAuroraX() # define search params start = datetime.datetime(2020, 1, 1, 0, 0, 0) @@ -29,12 +30,12 @@ Let's say we want to retrieve all the data product records the TREx RGB in Fort instrument_types = ["RGB ASI"] # perform the data product search - s = pyaurorax.data_products.search(start, - end, - programs=programs, - platforms=platforms, - instrument_types=instrument_types, - verbose=True) + s = aurorax.search.data_products.search(start, + end, + programs=programs, + platforms=platforms, + instrument_types=instrument_types, + verbose=True) # have a look at our results print(s.data) @@ -80,7 +81,7 @@ Let's say we want to retrieve all the data product records the TREx RGB in Fort === "IDL" - IDL-AuroraX provides the [`aurorax_data_product_search()`](/code/idlaurorax_api_reference/data_products/search/){:target="_blank"} function to perform a data product search. + IDL-AuroraX provides the [`aurorax_data_product_search()`](/code/idlaurorax_api_reference/search/data_products/search/){:target="_blank"} function to perform a data product search. ```idl IDL> response = aurorax_data_product_search('2020-01-01T00:00','2020-01-01T23:59',programs=['trex'],platforms=['fort smith'],instrument_types=['RGB ASI']) diff --git a/docs/code/basic_usage/data_sources.md b/docs/code/basic_usage/search/data_sources.md similarity index 89% rename from docs/code/basic_usage/data_sources.md rename to docs/code/basic_usage/search/data_sources.md index 04a578c..d50e8b5 100644 --- a/docs/code/basic_usage/data_sources.md +++ b/docs/code/basic_usage/search/data_sources.md @@ -23,7 +23,8 @@ You can retrieve all data sources, or retrieve data sources matching a certain s ```python import pyaurorax - sources = pyaurorax.sources.list() + aurorax = pyaurorax.PyAuroraX() + sources = aurorax.search.sources.list() print(sources) ``` @@ -31,7 +32,8 @@ You can retrieve all data sources, or retrieve data sources matching a certain s ```python import pyaurorax - sources = pyaurorax.sources.list(format=pyaurorax.FORMAT_BASIC_INFO) + aurorax = pyaurorax.PyAuroraX() + sources = aurorax.search.sources.list(format=pyaurorax.FORMAT_BASIC_INFO) print(sources) ``` @@ -39,13 +41,14 @@ You can retrieve all data sources, or retrieve data sources matching a certain s ```python import pyaurorax - sources = pyaurorax.sources.list(program="swarm") + aurorax = pyaurorax.PyAuroraX() + sources = aurorax.search.sources.list(program="swarm") print(sources) ``` === "IDL" - You can retrieve ALL data sources using the [`aurorax_sources_list()`](/code/idlaurorax_api_reference/sources/list/){:target="_blank"} function with no parameters. + You can retrieve ALL data sources using the [`aurorax_sources_list()`](/code/idlaurorax_api_reference/search/sources/list/){:target="_blank"} function with no parameters. ```idl IDL> sources = aurorax_sources_list() diff --git a/docs/code/basic_usage/ephemeris.md b/docs/code/basic_usage/search/ephemeris.md similarity index 94% rename from docs/code/basic_usage/ephemeris.md rename to docs/code/basic_usage/search/ephemeris.md index ab8557b..9eb744b 100644 --- a/docs/code/basic_usage/ephemeris.md +++ b/docs/code/basic_usage/search/ephemeris.md @@ -18,8 +18,9 @@ Let's say we want to retrieve all the ephemeris data for the THEMIS ASI in Gilla ```python # imports - import pyaurorax import datetime + import pyaurorax + aurorax = pyaurorax.PyAuroraX() # define search params start = datetime.datetime(2019, 1, 1, 6, 0, 0) @@ -29,12 +30,12 @@ Let's say we want to retrieve all the ephemeris data for the THEMIS ASI in Gilla instrument_types = ["panchromatic ASI"] # perform the ephemeris search - s = pyaurorax.ephemeris.search(start, - end, - programs=programs, - platforms=platforms, - instrument_types=instrument_types, - verbose=True) + s = aurorax.search.ephemeris.search(start, + end, + programs=programs, + platforms=platforms, + instrument_types=instrument_types, + verbose=True) # have a look at our results print(s.data) @@ -83,7 +84,7 @@ Let's say we want to retrieve all the ephemeris data for the THEMIS ASI in Gilla === "IDL" - IDL-AuroraX provides the [`aurorax_ephemeris_search()`](/code/idlaurorax_api_reference/ephemeris/search/){:target="_blank"} function to perform an ephemeris search. + IDL-AuroraX provides the [`aurorax_ephemeris_search()`](/code/idlaurorax_api_reference/search/ephemeris/search/){:target="_blank"} function to perform an ephemeris search. ```idl IDL> response = aurorax_ephemeris_search('2019-01-01T06:00','2019-01-01T06:59',programs=['themis-asi'],platforms=['gillam'],instrument_types=['panchromatic ASI']) diff --git a/docs/code/idlaurorax_api_reference/overview.md b/docs/code/idlaurorax_api_reference/overview.md index ec4f936..01764f9 100644 --- a/docs/code/idlaurorax_api_reference/overview.md +++ b/docs/code/idlaurorax_api_reference/overview.md @@ -28,6 +28,7 @@ The below pages provide the documentation for each function. Examples can be fou - [`aurorax_keogram_create_custom`](/code/idlaurorax_api_reference/tools/aurorax_keogram_create_custom/) - [`aurorax_keogram_create`](/code/idlaurorax_api_reference/tools/aurorax_keogram_create/) - [`aurorax_keogram_plot`](/code/idlaurorax_api_reference/tools/aurorax_keogram_plot/) +- [`aurorax_montage_create`](/code/idlaurorax_api_reference/tools/aurorax_montage_create/) - [`aurorax_mosaic_plot`](/code/idlaurorax_api_reference/tools/aurorax_mosaic_plot/) - [`aurorax_mosaic_oplot`](/code/idlaurorax_api_reference/tools/aurorax_mosaic_oplot/) - [`aurorax_mosaic_prep_images`](/code/idlaurorax_api_reference/tools/aurorax_mosaic_prep_images/) diff --git a/docs/code/idlaurorax_api_reference/search/availability/data_products.md b/docs/code/idlaurorax_api_reference/search/availability/data_products.md index 3313d8b..f43b07b 100644 --- a/docs/code/idlaurorax_api_reference/search/availability/data_products.md +++ b/docs/code/idlaurorax_api_reference/search/availability/data_products.md @@ -1,8 +1,3 @@ ---- -hide: - - toc ---- - # aurorax_data_products_availability ``` diff --git a/docs/code/idlaurorax_api_reference/tools/aurorax_montage_create.md b/docs/code/idlaurorax_api_reference/tools/aurorax_montage_create.md new file mode 100644 index 0000000..32371df --- /dev/null +++ b/docs/code/idlaurorax_api_reference/tools/aurorax_montage_create.md @@ -0,0 +1,47 @@ +--- +hide: + - toc +--- + +# aurorax_montage_create + +``` +;------------------------------------------------------------- +;+ +; NAME: +; AURORAX_MONTAGE_CREATE +; +; PURPOSE: +; Create and display a montage. +; +; EXPLANATION: +; Create a montage from a set of images, and display +; it, accompanied by timestamps. +; +; CALLING SEQUENCE: +; aurorax_montage_create, images, time_stamp, n_cols, n_rows +; +; PARAMETERS: +; images array of images to create the montage for +; timestamps timestamps corresponding to each frame of images +; n_cols integer specifying the number of columns in the montage +; n_rows integer specifying the number of rows in the montage +; colortable integer specifying the IDL colortable to use, optional (default is 0) +; timestamps_fontsize font size for the timestamp labals, optional +; frame_step interval to add frames from images to the montage, optional (default is 1) +; dimensions two-element array giving dimensions of the plotting window in device coordinates, optional +; location two-element array giving location of the plotting window in device coordinates, optional +; timestamps_color a string giving the color to overplot timestamps, optional (default is 'white') +; +; KEYWORDS: +; /NO_TIMESTAMPS disable default behaviour of plotting timestamps +; +; OUTPUT +; +; OUTPUT TYPE: +; +; EXAMPLES: +; aurorax_montage_create, images, timestamps, 5, 5, colortable=7, timestamps_fontsize=16 +;+ +;------------------------------------------------------------- +``` \ No newline at end of file diff --git a/docs/code/installation.md b/docs/code/installation.md index 847b195..f590671 100644 --- a/docs/code/installation.md +++ b/docs/code/installation.md @@ -34,6 +34,6 @@ This is the recommended way of installing the IDL-AuroraX library, but, refer to .run aurorax_startup ``` -3. Reset your IDL session by either clicking the Reset button in the IDL editor or by typing `.reset` into the IDL command prompt. +3. [OPTIONAL] If you added the above line to your startup file, you must reset your IDL session. Do this by either clicking the Reset button in the IDL editor or by typing `.reset` into the IDL command prompt. For further information, you can view what packages are installed using `ipm,/list`. You can also view the package details using `ipm,/query,'idl-aurorax'`. diff --git a/docs/code/overview.md b/docs/code/overview.md index 6bdaccd..4ca3f5c 100644 --- a/docs/code/overview.md +++ b/docs/code/overview.md @@ -1,19 +1,10 @@ # Developer Zone -AuroraX tools are built on top of a set of APIs, so using the platform programmatically is very easily supported. We have several tools available for this purpose, with more in development. - -## Programmatic methods - -There are four main ways of interacting with AuroraX programmatically: - -1. Making raw HTTP/HTTPS requests to the RESTful APIs -2. Writing Python code with [PyAuroraX](https://github.com/aurorax-space/pyaurorax){:target="_blank"} -3. Using the command line with aurorax-cli (part of PyAuroraX) -4. Writing IDL code with [IDL-AuroraX](https://github.com/aurorax-space/idl-aurorax){:target="_blank"} +AuroraX has several tools available for writing software. The PyAuroraX and IDL-AuroraX libraries are available to use for data analysis support of All-Sky Imager (ASI) data, and for interacting with with the AuroraX Search Engine (e.g., performing conjunction searches, ephemeris searches, uploading data, etc.). ## Getting started -The easiest way to get started is to use the Python library [PyAuroraX](https://github.com/aurorax-space/pyaurorax){:target="_blank"}, or the IDL library [IDL-AuroraX](https://github.com/aurorax-space/idl-aurorax){:target="_blank"}. You can also interact with the API directly, using HTTPS-based RESTful requests (GET, POST, etc.) in any programming language. +The easiest way to get started is to delve into the Python library [PyAuroraX](https://github.com/aurorax-space/pyaurorax){:target="_blank"}, or the IDL library [IDL-AuroraX](https://github.com/aurorax-space/idl-aurorax){:target="_blank"}. [Install Software  :material-console:](/code/installation/){.md-button .add-bottom-space}   [Getting Started Guide  :octicons-arrow-right-16:](/getting_started/7_interacting_programmatically/){.md-button .add-bottom-space}   diff --git a/mkdocs.yml b/mkdocs.yml index 554f346..c645a61 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -109,55 +109,56 @@ nav: - Basic Usage: - Overview: code/basic_usage/overview.md - AuroraX Search Engine: - - Data Sources: code/basic_usage/data_sources.md - - Conjunctions: code/basic_usage/conjunctions.md - - Ephemeris: code/basic_usage/ephemeris.md - - Data Products: code/basic_usage/data_products.md + - Data Sources: code/basic_usage/search/data_sources.md + - Conjunctions: code/basic_usage/search/conjunctions.md + - Ephemeris: code/basic_usage/search/ephemeris.md + - Data Products: code/basic_usage/search/data_products.md - Advanced Usage: - AuroraX Search Engine: - - Authentication: code/advanced_usage/authentication.md - - Advanced conjunction searches: code/advanced_usage/advanced_conjunctions.md - - Asynchronous searches: code/advanced_usage/asynchronous_search.md - - Searches with metadata filters: code/advanced_usage/searches_with_metadata_filters.md - - Uploading data to AuroraX: code/advanced_usage/contributing_data.md - - Data availability and statistics: code/advanced_usage/availability_and_stats.md - - Interact with Swarm-Aurora: code/advanced_usage/swarmaurora.md - - PyAuroraX API Reference: /code/pyaurorax_api_reference/pyaurorax + - Authentication: code/advanced_usage/search/authentication.md + - Advanced conjunction searches: code/advanced_usage/search/advanced_conjunctions.md + - Asynchronous searches: code/advanced_usage/search/asynchronous_search.md + - Searches with metadata filters: code/advanced_usage/search/searches_with_metadata_filters.md + - Uploading data to AuroraX: code/advanced_usage/search/contributing_data.md + - Data availability: code/advanced_usage/search/availability.md + - Interact with Swarm-Aurora: code/advanced_usage/search/swarmaurora.md + - PyAuroraX API Reference: code/pyaurorax_api_reference/pyaurorax - IDL-AuroraX API Reference: - Overview: code/idlaurorax_api_reference/overview.md - Data Access: - - aurorax_list_datasets: /code/idlaurorax_api_reference/data/aurorax_list_datasets/ - - aurorax_list_observatories: /code/idlaurorax_api_reference/data/aurorax_list_observatories/ - - aurorax_ucalgary_get_urls: /code/idlaurorax_api_reference/data/aurorax_ucalgary_get_urls/ - - aurorax_ucalgary_download: /code/idlaurorax_api_reference/data/aurorax_ucalgary_download/ - - aurorax_ucalgary_download_best_skymap: /code/idlaurorax_api_reference/data/aurorax_ucalgary_download_best_skymap/ - - aurorax_ucalgary_read: /code/idlaurorax_api_reference/data/aurorax_ucalgary_read/ - - aurorax_ucalgary_is_read_supported: /code/idlaurorax_api_reference/data/aurorax_ucalgary_is_read_supported/ + - aurorax_list_datasets: code/idlaurorax_api_reference/data/aurorax_list_datasets.md + - aurorax_list_observatories: code/idlaurorax_api_reference/data/aurorax_list_observatories.md + - aurorax_ucalgary_get_urls: code/idlaurorax_api_reference/data/aurorax_ucalgary_get_urls.md + - aurorax_ucalgary_download: code/idlaurorax_api_reference/data/aurorax_ucalgary_download.md + - aurorax_ucalgary_download_best_skymap: code/idlaurorax_api_reference/data/aurorax_ucalgary_download_best_skymap.md + - aurorax_ucalgary_read: code/idlaurorax_api_reference/data/aurorax_ucalgary_read.md + - aurorax_ucalgary_is_read_supported: code/idlaurorax_api_reference/data/aurorax_ucalgary_is_read_supported.md - Analyis Support Software: - - aurorax_bounding_box_extract_metric: /code/idlaurorax_api_reference/tools/aurorax_bounding_box_extract_metric/ - - aurorax_calibrate_rego: /code/idlaurorax_api_reference/tools/aurorax_calibrate_rego/ - - aurorax_calibrate_trex_nir: /code/idlaurorax_api_reference/tools/aurorax_calibrate_trex_nir/ - - aurorax_keogram_add_axis: /code/idlaurorax_api_reference/tools/aurorax_keogram_add_axis/ - - aurorax_keogram_create_custom: /code/idlaurorax_api_reference/tools/aurorax_keogram_create_custom/ - - aurorax_keogram_create: /code/idlaurorax_api_reference/tools/aurorax_keogram_create/ - - aurorax_keogram_plot: /code/idlaurorax_api_reference/tools/aurorax_keogram_plot/ - - aurorax_mosaic_plot: /code/idlaurorax_api_reference/tools/aurorax_mosaic_plot/ - - aurorax_mosaic_oplot: /code/idlaurorax_api_reference/tools/aurorax_mosaic_oplot/ - - aurorax_mosaic_prep_images: /code/idlaurorax_api_reference/tools/aurorax_mosaic_prep_images/ - - aurorax_mosaic_prep_skymap: /code/idlaurorax_api_reference/tools/aurorax_mosaic_prep_skymap/ - - aurorax_get_decomposed_color: /code/idlaurorax_api_reference/tools/aurorax_get_decomposed_color/ - - aurorax_movie: /code/idlaurorax_api_reference/tools/aurorax_movie/ + - aurorax_bounding_box_extract_metric: code/idlaurorax_api_reference/tools/aurorax_bounding_box_extract_metric.md + - aurorax_calibrate_rego: code/idlaurorax_api_reference/tools/aurorax_calibrate_rego.md + - aurorax_calibrate_trex_nir: code/idlaurorax_api_reference/tools/aurorax_calibrate_trex_nir.md + - aurorax_keogram_add_axis: code/idlaurorax_api_reference/tools/aurorax_keogram_add_axis.md + - aurorax_keogram_create_custom: code/idlaurorax_api_reference/tools/aurorax_keogram_create_custom.md + - aurorax_keogram_create: code/idlaurorax_api_reference/tools/aurorax_keogram_create.md + - aurorax_keogram_plot: code/idlaurorax_api_reference/tools/aurorax_keogram_plot.md + - aurorax_montage_create: code/idlaurorax_api_reference/tools/aurorax_montage_create.md + - aurorax_mosaic_plot: code/idlaurorax_api_reference/tools/aurorax_mosaic_plot.md + - aurorax_mosaic_oplot: code/idlaurorax_api_reference/tools/aurorax_mosaic_oplot.md + - aurorax_mosaic_prep_images: code/idlaurorax_api_reference/tools/aurorax_mosaic_prep_images.md + - aurorax_mosaic_prep_skymap: code/idlaurorax_api_reference/tools/aurorax_mosaic_prep_skymap.md + - aurorax_get_decomposed_color: code/idlaurorax_api_reference/tools/aurorax_get_decomposed_color.md + - aurorax_movie: code/idlaurorax_api_reference/tools/aurorax_movie.md - AuroraX Search Engine: - - aurorax_conjunction_search: /code/idlaurorax_api_reference/search/conjunctions/search/ - - aurorax_open_conjunctions_in_aurorax: /code/idlaurorax_api_reference/search/conjunctions/open_in_aurorax/ - - aurorax_open_conjunctions_in_swarmaurora: /code/idlaurorax_api_reference/search/conjunctions/open_in_swarmaurora/ - - aurorax_save_swarmaurora_custom_import_file: /code/idlaurorax_api_reference/search/conjunctions/save_swarmaurora_import_file/ - - aurorax_create_advanced_distances_hash: /code/idlaurorax_api_reference/search/conjunctions/create_advanced_distances/ - - aurorax_create_criteria_block: /code/idlaurorax_api_reference/search/conjunctions/create_criteria_block/ - - aurorax_create_metadata_filter: /code/idlaurorax_api_reference/search/metadata_filters/create_metadata_filter/ - - aurorax_create_metadata_filter_expression: /code/idlaurorax_api_reference/search/metadata_filters/create_expression/ - - aurorax_data_products_availability: /code/idlaurorax_api_reference/search/availability/data_products/ - - aurorax_data_product_search: /code/idlaurorax_api_reference/search/data_products/search/ - - aurorax_ephemeris_availability: /code/idlaurorax_api_reference/search/availability/ephemeris/ - - aurorax_ephemeris_search: /code/idlaurorax_api_reference/search/ephemeris/search/ - - aurorax_sources_list: /code/idlaurorax_api_reference/search/sources/list/ + - aurorax_conjunction_search: code/idlaurorax_api_reference/search/conjunctions/search.md + - aurorax_open_conjunctions_in_aurorax: code/idlaurorax_api_reference/search/conjunctions/open_in_aurorax.md + - aurorax_open_conjunctions_in_swarmaurora: code/idlaurorax_api_reference/search/conjunctions/open_in_swarmaurora.md + - aurorax_save_swarmaurora_custom_import_file: code/idlaurorax_api_reference/search/conjunctions/save_swarmaurora_import_file.md + - aurorax_create_advanced_distances_hash: code/idlaurorax_api_reference/search/conjunctions/create_advanced_distances.md + - aurorax_create_criteria_block: code/idlaurorax_api_reference/search/conjunctions/create_criteria_block.md + - aurorax_create_metadata_filter: code/idlaurorax_api_reference/search/metadata_filters/create_metadata_filter.md + - aurorax_create_metadata_filter_expression: code/idlaurorax_api_reference/search/metadata_filters/create_expression.md + - aurorax_data_products_availability: code/idlaurorax_api_reference/search/availability/data_products.md + - aurorax_data_product_search: code/idlaurorax_api_reference/search/data_products/search.md + - aurorax_ephemeris_availability: code/idlaurorax_api_reference/search/availability/ephemeris.md + - aurorax_ephemeris_search: code/idlaurorax_api_reference/search/ephemeris/search.md + - aurorax_sources_list: code/idlaurorax_api_reference/search/sources/list.md