Basic usage
===========

To start using pingwyn, import it like any other Python module. Throughout the documentation, we will use the short-hand ``pg`` to refer to pingwyn. So, import pingwyn as follows:

.. code-block:: python3

	import pingwyn as pg

Following this, the next step is to load in data. This can be achieved using :func:`pingwyn.open` or :func:`pingwyn.open_all`. Often, it is preferable to load in multiple pieces of data, so we'll use the latter. To effectively make use of loading multiple pieces of data, we can make use of the wildcard character, \*, to select multiple files. In the code block below, all Matrix data (indicated using `*_mtrx`) is loaded for all experiments in 2026 (indicated using `2026-*`).

.. code-block:: python3

	directory = "/path/to/files/2026-*/*_mtrx"
	files = pg.open_all(directory)

When data is loaded using :func:`pingwyn.open_all`, a list of lists is returned. As an example, if you load five files, you'll receive a list containing five lists. The inner lists contain all the data that was found in the loaded file. This means it may contain one or multiple channels. These channels can correspond to different scan directions (up/down) and/or different data measurements (topography, current, adhesion, etc.). What each file contains, is dependent on which device the measurement was taken on. For the purposes of this documentation, we'll assume measurements taken with Omicron Matrix electronics. Here, each data channel has its own files (.Z_mtrx, .I_mtrx, etc.), with each file containing channels for forward/backward and up/down data.

To properly distinguish between data, we must filter the data based on its channel. In the following code block, we select the first channel of the file (often forward+up or forward+down) for each data file we are interested in. This can be extended to any number of data types.

.. code-block:: python3

	topography = [i[0] for i in files if i[0].metadata["channel"][0] == "Z"]
	iv_spectroscopy = [i[0] for i in files if i[0].metadata["channel"][0] == "I(V)"]

Each pingwyn :doc:`data type <types>` houses a ``metadata`` property. This metadata houses information such as the filename, setpoints and the original type of data that was measured, amongst other information. The code block below shows that the two variables contain different types of data and house different metadata:

.. code-block:: python3

	print(type(topography[0]))
	dir(topography[0])
	print(type(iv_spectroscopy[0]))
	dir(iv_spectroscopy[0])

Now that the data is loaded and filtered into separate bins, it becomes possible to perform operations on the data. For instance, you can apply flattening to the topography images and show the results. This makes use of the :py:func:`pingwyn.remove_plane` and :py:func:`pingwyn.align_rows` functions to modify the image, and :py:func:`pingwyn.plot` to plot the result.

.. code-block:: python3

	for image in topography:
	    # Apply flattening to the image
	    image = image.remove_plane().align_rows(method="median_diff")

	    # Plot the image
	    fig, ax = plt.subplots(1, 1)
	    pg.plot(ax, image)
	    plt.show()

.. note::

	Pingwyn functions can be used in two different ways. You can either call functions using the pingwyn prefix, i.e. ``image2 = pg.align_rows(image)``, or by calling them inline, i.e. ``image2 = image.align_rows()``. There is a significant difference between these two methods, which is explained in further detail :doc:`here <func-inline>`. Generally, if you want to re-use your data, you want to use the pingwyn prefix.