readabs.read_abs_series

  1"""Get specific ABS data series by their ABS series identifiers."""
  2
  3from collections.abc import Sequence
  4from typing import Unpack, cast
  5
  6from pandas import DataFrame, Index, PeriodIndex, concat
  7
  8from readabs.abs_meta_data import metacol
  9from readabs.read_abs_cat import read_abs_cat
 10from readabs.read_support import ReadArgs, check_kwargs, get_args
 11
 12
 13# --- functions
 14def read_abs_series(
 15    cat: str,
 16    series_id: str | Sequence[str],
 17    url: str = "",
 18    **kwargs: Unpack[ReadArgs],
 19) -> tuple[DataFrame, DataFrame]:
 20    """Get specific ABS data series by their ABS catalogue and series identifiers.
 21
 22    Parameters
 23    ----------
 24    cat : str
 25        The ABS catalogue ID.
 26
 27    series_id : str | Sequence[str]
 28        An ABS series ID or a sequence of ABS series IDs.
 29
 30    url : str = ""
 31        The URL of an ABS landing page. Use this for discontinued series
 32        that are no longer in the ABS Time Series Directory. If provided,
 33        data is retrieved from this URL instead of looking up the catalogue
 34        number. Passed through to read_abs_cat().
 35
 36    **kwargs : Any
 37        Keyword arguments for the read_abs_series function,
 38        which are the same as the keyword arguments for the
 39        read_abs_cat function.
 40
 41    Returns
 42    -------
 43    tuple[DataFrame, DataFrame]
 44        A tuple of two DataFrames, one for the primary data and one for the metadata.
 45
 46    Example
 47    -------
 48
 49    ```python
 50    import readabs as ra
 51    from pandas import DataFrame
 52    cat_num = "6202.0"  # The ABS labour force survey
 53    unemployment_rate = "A84423050A"
 54    seo = "6202001"  # The ABS table name
 55    data, meta = ra.read_abs_series(
 56        cat=cat_num, series_id=unemployment_rate, single_excel_only=seo
 57    )
 58    ```
 59
 60    """
 61    # check for unexpected keyword arguments/get defaults
 62    check_kwargs(kwargs, "read_abs_series")
 63    args = get_args(kwargs, "read_abs_series")
 64
 65    # read the ABS category data
 66    cat_data, cat_meta = read_abs_cat(cat, url=url, **args)
 67
 68    # drop repeated series_ids in the meta data,
 69    # make unique series_ids the index
 70    cat_meta.index = Index(cat_meta[metacol.id])
 71    cat_meta = cat_meta.groupby(cat_meta.index).first()
 72
 73    # get the ABS series data
 74    if isinstance(series_id, str):
 75        series_id = [series_id]
 76    return_data, return_meta = DataFrame(), DataFrame()
 77    for identifier in series_id:
 78        # confirm that the series ID is in the catalogue
 79        if identifier not in cat_meta.index:
 80            if args["verbose"]:
 81                print(f"Series ID {identifier} not found in ABS catalogue ID {cat}")
 82            if args["ignore_errors"]:
 83                continue
 84            raise ValueError(f"Series ID {identifier} not found in catalogue {cat}")
 85
 86        # confirm thay the index of the series is compatible
 87        table = str(cat_meta.loc[identifier, metacol.table])  # str for mypy
 88        data_series = cat_data[table][identifier]
 89        if (
 90            len(return_data) > 0
 91            and cast("PeriodIndex", return_data.index).freq != cast("PeriodIndex", data_series.index).freq
 92        ):
 93            if args["verbose"]:
 94                print(f"Frequency mismatch for series ID {identifier}")
 95            if args["ignore_errors"]:
 96                continue
 97            raise ValueError(f"Frequency mismatch for series ID {identifier}")
 98
 99        # add the series data and meta data to the return values
100        if len(return_data) > 0:
101            return_data = return_data.reindex(return_data.index.union(data_series.index))
102        return_data[identifier] = data_series
103        return_meta = concat([return_meta, cat_meta.loc[identifier]], axis=1)
104
105    return return_data, return_meta.T
106
107
108if __name__ == "__main__":
109
110    def simple_test() -> None:
111        """Test the read_abs_series function."""
112        # simple test
113        # Trimmed Mean - through the year CPI growth (monthly) - seasonally adjusted
114        data, meta = read_abs_series("6401.0", "A130400382R", single_excel_only="640106")
115        print(data.tail())
116        print(meta.T)
117        print("Done")
118
119    simple_test()