========================================
TUTORIAL 2 Logging Data to a SQLite File
========================================

Automated logging and managing of measurement data is one of the most powerful features of PyICe.
This tutorial shows how to create a PyICe logger and begin the process of structured data collection to a SQLite table.

SQLite is a powerful data storage, retrieval and manipulation tool.

Rather than working in Excel making calculations column by column, SQLite offers a plain English, easy to learn, scripting method to make such calculations within a single line of code.

Using this method also, at no additional cost, documents the calculations made as does all work generally performed in Python.

Each channel registered with the *channel_master* results in a SQLite table *column*.

New rows are generated by calling the logger's method log() for each iteration of the test sweep or script.

Building on TUTORIAL 1 we have the following infrastructure:

.. code-block:: python

   from PyICe import lab_core
   from PyICe import lab_interfaces
   from PyICe import lab_instruments

   interface_factory = lab_interfaces.interface_factory()
   my_a34401_interface = interface_factory.get_visa_serial_interface("COM10", baudrate=9600, dsrdtr=True, timeout=5)
   my_a34401 = lab_instruments.agilent_34401a(my_a34401_interface)
   
   my_a34401.add_channel("vmeas")
   my_a34401.config_dc_voltage()
   
   channel_master = lab_core.channel_master()
   channel_master.add(my_a34401)

To create an instance of a logger object, simply request one from **lab_core**.
The only required argument is a *channel_master* instance.

.. code-block:: python

   logger = lab_core.logger(channel_master)

The logger must then create (or append to) a table.

SQLite files can have many tables.

Normally, *replace_table* would be set to **False** to avoid accidentally overwriting data.

If replace_table is not set to True and the table already exists, then the script will stop.

.. code-block:: python

   logger.new_table(table_name='tutorial_2_table', replace_table=True)

To take 10 voltage readings, we can loop 10 times, and record everything the channel_master knows about each time.
Once the circuit is configured to take the desired data, simply call the logger's log() method.

.. code-block:: python

   print("Logging all channels...")
   for measurement in range(10):
       print(f"Logging measurement number: {measurement}")
       logger.log()
   print("\n\nConsider opening data_log.sqlite with DB Browser https://sqlitebrowser.org/ and opening the [Browse Data] tab.")

There is no explicit need to insert any delays between invocations of an instrument action such as taking a measurement.

If an instrument requires a settling time before its reading is taken, the driver for that instrument will have that information and PyICe will automatically insert the delay.

The logger will create a file in the working directory called *data_log.sqlite*.

Within this file, there will be a table called *tutorial_2_table*.

To view the file, the simplest way is to get "DB Browser for SQLite".

DB Browser is an interactive database program that will display the data and allow queries to be run.

It can usually be found here: https://sqlitebrowser.org/

Notes: when the logger is created it will know about all the channels that exist in the channel_master at creation time.

Channels added to the channel_master after the creation of the logger will not be known to the logger.

Channels may be removed from the logger by using the logger.remove_channel(channel_object) or logger.remove_channel_by_name("channel_name") methods.

If only a few channels are to be logged, use the logger.remove_all_channels_and_sub_groups() method to empty the logger.

channels/instruments can then be added using the logger.add() method.