Utilities
=========

.. verified:: 2025-01-21
   :reviewer: Christof Buchbender

This page documents utilities for database initialization and data loading. These are
used for setting up a fresh database instance.

Database Initialization
-----------------------

The ``opsdb_init`` command-line tool initializes a fresh ops-db instance with
observatory infrastructure, instruments, and observation units.

.. autofunction:: ccat_ops_db.opsdb_init.opsdb_initialization

Command-Line Usage::

   # Initialize with default settings
   opsdb_init

   # Initialize and drop existing tables
   opsdb_init --drop

   # Initialize with local data-center repository
   opsdb_init --local_url /path/to/data-center

   # Initialize for production mode
   opsdb_init --data_archive_mode production

   # Verbose output
   opsdb_init -v --drop

Observation Unit Initialization
-------------------------------

.. autofunction:: ccat_ops_db.init_obs_units.init_obs_units

.. autofunction:: ccat_ops_db.init_obs_units.read_obs_units

.. autofunction:: ccat_ops_db.init_obs_units.read_sources

.. autofunction:: ccat_ops_db.init_obs_units.read_pre_scheduled_slots

These functions parse YAML/CSV files from the data-center repository and populate the
database with sources, observation units, and scheduling information.

Utility Functions
-----------------

These functions provide helpers for adding or updating database entities.

Sources
^^^^^^^

.. autofunction:: ccat_ops_db.utils.add_or_update_source

Example::

   from ccat_ops_db.utils import add_or_update_source

   values = {
       "name": "Orion-KL",
       "slam": "05:35:14.5",
       "sbet": "-05:22:30.0",
       "frame": "icrs",
       "vlsr": 9.0
   }
   add_or_update_source(session, values, source_type="fixed_source")

Observation Units
^^^^^^^^^^^^^^^^^

.. autofunction:: ccat_ops_db.utils.add_or_update_obs_unit

.. autofunction:: ccat_ops_db.utils.add_inpar_and_tiling

Pre-Scheduled Slots
^^^^^^^^^^^^^^^^^^^

.. autofunction:: ccat_ops_db.utils.add_pre_scheduled_slot

Data Center Repository Structure
--------------------------------

The initialization process expects data files in the `data-center <https://github.com/ccatobs/data-center>`_
repository with the following structure::

   data-center/
   ├── observatory/
   │   └── *.toml (observatory definitions)
   ├── telescope/
   │   └── *.toml (telescope definitions)
   ├── instruments/
   │   └── *.toml (instrument and module definitions)
   ├── roles/
   │   └── *.toml (user role definitions)
   ├── users/
   │   └── *.toml (user definitions)
   ├── observing_programs/
   │   └── *.toml (observing program definitions)
   ├── lines/
   │   └── *.toml (spectral line definitions)
   ├── obs_modes/
   │   └── *.toml (observation mode definitions)
   ├── sites/
   │   ├── sites.development.toml
   │   ├── sites.staging.toml
   │   └── sites.production.toml (site and location definitions)
   └── obs_units/
       ├── input_file_obs_units_to_db.yaml (master input file)
       ├── sources/
       ├── obsunits/
       ├── inpar_parameters/
       └── tiling_parameters/

The ``--data_archive_mode`` flag selects which sites configuration to load
(development, staging, or production).

Related Documentation
---------------------

* Core functions: :doc:`core`
* Models API: :doc:`models`
* Database concepts: :doc:`../concepts/overview`