How to get started?¶

Installation¶

Clone from GitHub, or use your favourite dependency management tool to install from PyPi. Despite the increasing traction of uv, the standard in Statistics Norway is still Poetry:

poetry add ssb-timeseries

If you are lucky, the library works out of the box with default or predefined settings.

Note that the defaults are for local testing, ie not be suitable for the production setting.

Configuration¶

The library expects an environment variable TIMESERIES_CONFIG to provide the path to a valid configuration file. The name or location of the file does not really matter, but some environments may require specific locations.

For users in Statistics Norway:

/home/onyxia/work/ for your own testing and development in Dapla Lab.
/home/onyxia/buckets/<bucket-name> for working with sharp data.
gs://<team>/<timeseries-config-path> for GCP service configuration.

The configuration file should be in JSON format. A minimal working example suitable for testing can look like this:

{
    "bucket": "/home/onyxia/work/timeseries/",
    "configuration_file": "/home/onyxia/work/timeseries/configuration/minimal.json",
    "logging": {},
    "repositories": {
        "my_repo": {
            "name": "my-repo",
            "catalog": "/home/onyxia/work/timeseries/my_repo/metadata",
            "directory": "/home/onyxia/work/timeseries/my_repo/data",
            "default": true
        }
    }
}

The easiest way to set the environment variable within a Dapla Lab session is with a cell magic. Assuming the configuration file is /home/onyxia/work/timeseries/configuration/minimal.json:

%env TIMESERIES_CONFIG=/home/onyxia/work/timeseries/configuration/minimal.json

Note that managed this way, TIMESERIES_CONFIG will not be persisted between subshells. The procedure need to be repeated for every new session or kernel restart. Refer to the Dapla documentation for setting the variable at the project level or in a startup script.

With the environment variable pointing to the configuration file you should be ready to go.

See the [API reference] or tutorials section (coming soon) for more.

Helper CLI¶

The library exposes some configuration management features in a helper CLI.

The command poetry run timeseries-config <OPTION> can be run from a terminal in order to shift between defaults.

Disclaimer¶

Note that while the library is in a workable state and should work both locally and (for SSB users) in JupyterLab, it is still in early development. There is a risk that fundamental choices are reversed and breaking changes introduced.

Do not be shy about asking questions or giving feedback. The best channel for that is via https://github.com/statisticsnorway/ssb-timeseries/issues.