# Converters We currently provide 4 types of converters. Here, we discuss their basic structure and guidelines for building a custom converter. Use the examples notebooks to understand how to convert data from the respective formats. - **PGM JSON Converter:** Refer to the [PGM JSON Example](../examples/pgm_json_example.ipynb) - **VisonExcelConverter** Refer to the [Vision Example](../examples/vision_example.ipynb) - **Pandapower Converter:** Converts [pandapower network](https://pandapower.readthedocs.io/en/stable/elements.html) (a dictionary of dataframes) to power-grid-model data. Refer to [converters](../power_grid_model_io.md#converters) in API documentation for more details ## Structure All converters are derived from the base {py:class}`power_grid_model_io.converters.base_converter`. The usable functions for loading, saving and converting the data are located in the base class. The private functions (`_load_data`, `_parse_data` and `_serialize_data`) are overloaded based on the specific type of converter (i.e., excel, json or pandapower). The `VisonExcelConverter` extends the [tabular converters](tabular_converter.md) for Excel exports of Vision. It is recommended that custom converters be created in a similar way. ## Instantiation Converter objects can be instantiated in the following way. For instance, for a `PgmJsonConverter`: ```python from power_grid_model_io.converters.pgm_json_converter import PgmJsonConverter converter = PgmJsonConverter(source_file=source, destination_file=destination) ``` ## Common methods for converters The common methods across different converters, including data IO and log level configurations, are described below. Converter specific methods are presented in corresponding sections. ### Loading data Methods load_input_data(), load_update_data(), load_sym_output_data() and load_asym_output_data() are for loading the relevant data to the converter. Input data can be configured at converter initialisation by passing the path to source data to parameter `source_file`. Alternatively, the data can also be provided as an argument to the load function after initialisation. In addition to the input data that will be used in calculations by power-grid-model, other miscellaneous information in the source file is stored in `extra_info`: ```python input_data, extra_info = converter.load_input_data(data=example_data) ``` ### Saving data It is possible to save the data in the format of the converter. The Converter can be instantiated with a path given to `destination_file`. Alternatively, the destination path can be provided in the save function. You can also add additional information about each component in the form of `extra_info` generated by [Load data](converter.md#load-data) to be saved along with it. ```python converter.save(example_data, extra_info=example_extra_info, destination=destination_path) ``` ### Configuring the log output An interface is provided to configure the log level of converters. This configuration can be done at converter initialisation or after. Notice that this log level only belongs to the logger within the converter. Users need to set their basic configuration of the `logging` module to a level that is below what is configuired for the converters. ```python # Examplary usage in your script import logging from power_grid_model_io.converters import VisionExcelConverter logging.basicConfig(level=logging.INFO) # Only levels INFO and above will be logged converter_warning = VisionExcelConverter(input_file, log_level=logging.WARNING) # If there is any logs above WARNING, they will be logged converter_info = VisionExcelConverter(input_file) # Uses default INFO level logging.basicConfig(level=logging.WARNING) # Only levels WARNING and above will be logged assert converter_info.get_log_level() == logging.INFO # Previously created converters will retain their original log level, regardless of system wide configuration converter_ = VisionExcelConverter(input_file, log_level=logging.DEBUG) # Any logs on DEBUG and INFO level will not be logged converter_.set_log_level(logging.WARNING) # Now the converter's log level is set to WARNING ```