yieldplotlib.generate_key_map
=============================

.. py:module:: yieldplotlib.generate_key_map

.. autoapi-nested-parse::

   Generate key_map.py from CSV data or directly from Google Sheets.

   This script creates a key_map.py file that maps parameters between different exoplanet
   simulation libraries (EXOSIMS and AYO). It can either use a local CSV file or directly
   download from a Google Sheet.

   Usage Examples:
   1. Generate from a local CSV file:
      ```
      python generate_key_map.py --csv input_data.csv
      ```

   2. Download from Google Sheets using a service account credentials file:
      ```
      python generate_key_map.py --sheets SHEET_ID --credentials path/to/credentials.json
      ```

   3. Download from Google Sheets using Base64-encoded credentials from environment:
      ```
      # First set the environment variable:
      export GOOGLE_CREDENTIALS_B64=$(cat service-account.json | base64 | tr -d '\n')

      # Then run:
      python generate_key_map.py --sheets SHEET_ID
      ```

   4. Use a temporary file for the downloaded CSV (cleaned up afterward):
      ```
      python generate_key_map.py --sheets SHEET_ID --temp
      ```

   Output:
   ------
   The script creates a key_map.py file in the current directory with a KEY_MAP
   dictionary that maps parameter names to their locations and transformations
   in the EXOSIMS and AYO libraries.



Functions
---------

.. autoapisummary::

   yieldplotlib.generate_key_map.download_from_google_sheets
   yieldplotlib.generate_key_map.parse_csv
   yieldplotlib.generate_key_map.write_key_map
   yieldplotlib.generate_key_map.main


Module Contents
---------------

.. py:function:: download_from_google_sheets(sheet_id, output_path, credentials_json_path=None)

   Download data from Google Sheets and save as CSV.

   This function authenticates with Google Sheets API using service account credentials
   and downloads the specified sheet as a CSV file.

   Args:
       sheet_id:
           The ID of the Google Sheet to download. This is the string from the URL:
           https://docs.google.com/spreadsheets/d/{SHEET_ID}/edit

       output_path:
           Path where the CSV file should be saved.

       credentials_json_path:
           Optional path to a service account credentials JSON file.
           If not provided, will use GOOGLE_CREDENTIALS_B64 environment variable,
           which should contain the Base64-encoded JSON credentials.

   Returns:
       None. The sheet data is saved to the output_path as a CSV file.

   Raises:
       SystemExit: If credentials cannot be loaded or sheet cannot be accessed.


.. py:function:: parse_csv(input_csv)

   Parses the input CSV and constructs the KEY_MAP dictionary.

   Args:
       input_csv (str): Path to the input CSV file.

   Returns:
       OrderedDict: The constructed KEY_MAP with prioritized ordering.


.. py:function:: write_key_map(key_map, output_py)

   Writes the KEY_MAP dictionary to a Python file with a docstring.

   Args:
       key_map (OrderedDict):
           The KEY_MAP dictionary.
       output_py (str):
           Path to the output Python file.


.. py:function:: main()

   Process command line arguments and run the appropriate functions.

   This function parses command line arguments, downloads from Google Sheets if
   requested, processes the CSV file, and generates the key_map.py output file.

   Command-line arguments:
   ----------------------
   --csv: Path to a local CSV file to process
   --sheets: Google Sheet ID to download and process
   --credentials: Path to Google service account credentials JSON file (optional)
   --temp: Use a temporary file for the downloaded CSV (deleted after processing)

   Environment variables:
   --------------------
   GOOGLE_CREDENTIALS_B64: Base64-encoded Google service account JSON (required if
                           using --sheets without --credentials)