# `cso_pal` module

The `cso_pal` module provides classes for accessing data from the Product Algorithm Laboratory.

Data is available from a special portal: S5P-PAL Data Portal.

To browse through the data, use the browser interface.

## PAL API

See the PAL API info for latest info.

S5P-PAL product files can be selected and downloaded using the Spatio Temporal Asset Catalog (STAC). The PySTAC Python interface is used for access.

## Class hierchy

The classes and are defined according to the following hierchy:

- `UtopyaRc`

  - `CSO_PAL_Inquire`

  - `CSO_PAL_Downloader`

## Classes

class cso_pal.CSO_PAL_Inquire(rcfile, rcbase='', env={}, indent='')

  Bases: `UtopyaRc`

  Inquire available Sentinel data from the Product Algorithm Laboratory.

  A query is sent to search for products that are available for a certain time and overlap with a specified region. The result is a list with orbit files and instructions on how to download them.

  In the settings, specify the url of the portal:

      <rcbase>.url              :  https://data-portal.s5p-pal.com/api/s5p-l2/collection.json

  Specify the time range over which files should be downloaded:

      <rcbase>.timerange.start  :  2018-07-01 00:00
      <rcbase>.timerange.end    :  2018-07-01 23:59

  Provide a product type:

      ! product type (always 10 characters!):
      <rcbase>.producttype            :  L2__NO2___

  Eventually specify a target area, only orbits with some pixels within the defined box will be downloaded:

      ! target area, leave empty for globe; format:  west,south:east,north
      <rcbase>.area             :
      !<rcbase>.area             :  -30,30:35,76

  Name of output csv file:

      ! output table, date of today:
      <rcbase>.output.file            :  ${my.work}/PAL_S5P_NO2_%Y-%m-%d.csv

  Example records:

      orbit;         start_time;           end_time;processing;collection;processor_version;filename                                                                              ;href
      02832;2018-05-01 00:00:52;2018-05-01 01:42:22;PAL_      ;01        ;020301           ;S5P_PAL__L2__NO2____20180501T000052_20180501T014222_02832_01_020301_20211108T132200.nc;https://data-portal.s5p-pal.com/cat/sentinel-5p/download/c3e90b62-c1f6-47b6-9ed7-bd70aa6f46ce
      02833;2018-05-01 01:42:22;2018-05-01 03:23:52;PAL_      ;01        ;020301           ;S5P_PAL__L2__NO2____20180501T014222_20180501T032352_02833_01_020301_20211108T163508.nc;https://data-portal.s5p-pal.com/cat/sentinel-5p/download/a08cda20-0018-434e-bdcc-800dd580db0f
      :

class cso_pal.CSO_PAL_Downloader

  Bases: `object`

  Class to download single file from the Product Algorithm Laboratory.

  The `DownloadFile` method should be used to actually download a file.

  Usage:

      # initialize downloader:
      downloader = CSO_PAL_Downloader()
      # download file, store in specified file:
      downloader.DownloadFile( "https://data-portal.s5p-pal.com/cat/sentinel-5p/download/88c15681-db43-4219-b391-c8567e39cccf", "orbit.nc" )

  DownloadFile(href, output_file, maxtry=10, nsec_wait=5, nsec_wait_max=600, dmode=None, indent='')

    Download file from PAL.

    If a request fails it is tried again up to a maximum of `maxtry` times, with an initial delay of `nsec_wait` between requsts.

    Arguments:

    - `href` : download url, for example:

          https://data-portal.s5p-pal.com/cat/sentinel-5p/download/88c15681-db43-4219-b391-c8567e39cccf

    - `output_file` : target file

    Optional arguments:

    - `maxtry` : number of times to try again if download fails

    - `nsec_wait` : initial delay in seconds between requests; with every new attempt, this will be increased up to a maximum of `nsec_wait_max`

    - `dmode`: directory creation mode, e.g. `777`