Get started

In this section, we will give you all the essential information to correctly start using the microfading package.

The easiest way to use the microfading package is within a Jupyter notebook. If you are not familiar with Python or Jupyter notebooks, you might want to consult our section on Jupyter notebooks, where we briefly describe what they are and why did we choose them for manipulating our microfading data.

Once you have installed Jupyter on your computer and are able to open new notebooks, you will need to install the microfading package (see the section installation). Afterwards, you are good to go ! Below you will find 5 recommendations that will guide you to correctly start using the package.

1. Do you have microfading data files?¶

The whole package is based on microfading data files that you either created yourself when performing microfading measurements or obtained from someone else. Each file corresponds to a single microfading measurement. The files consist of Excel or OpenDocument files with a specific structure organizing the data inside the files. Check the datafiles section for more information about it.

If you don't have any microfading files, the package has a function to load microfading files, so that you can use these files to play with the functionalities of the package (see get_datasets section). To create the required files based on microfading raw files, consult the rawdata processing section of this website.

If you have files, the following lines of code shows how you can import them in the jupyter notebook:

# I use this package to select files on my local computer
from glob import glob

# I use the command 'cd <path>' to change the current directory and be in the folder where the microfading files are.

cd /home/username/Documents/MFT

# Using the glob method, I select the files that contain the words 'BW1' and 'MFT' in the filename.
files = sorted(glob('*BW1*MFT*'))
files

[PosixPath('/home/username/Documents/MFT/2024-144_MF.BWS002.G01_avg_BW1_model_2024-07-30_MFT2.xlsx'),
PosixPath('/home/username/Documents/MFT/2024-144_MF.BWS003.G01_avg_BW1_model_2024-08-02_MFT2.xlsx')]

2. Central role of the `MFT` class¶

Once you have selected microfading files and encapsulated them inside a python list, you will need to create an instance of the MFT class passing the variable for your microfading files as argument (see code below). Most of the functions provided by the package can only be accessed through the MFT class.

import microfading as mf

m = mf.MFT(files=files)

3. Three keywords function: get, plot, compute¶

Once you have created an instance of the MFT class, you can access the functions. The name of each function starts by a verb: get, plot, or compute. Enter one of the verbs and use the auto-completion tool (Tab button) to display a list of available functions.

Alt text — List of all the plotting functions.

The functions can be run without passing any arguments, this will output the default values. To adjust the output to your needs, you will need to modify the values of the arguments. For instance, the function get_cielab() returns the \(\Delta E_{00}\) values by default. If you want to retrieve other CIE colorimetric coordinates, you will need to pass in a new value for the argument coordinates (see code below). To know the role of each argument in a function and which values can you pass in, you will need to read the documentation (see below). The latter can either be access in the jupyter notebook or in the References section of this website.

4. Configuration and databases files¶

If you are planning to perform microfading measurements more than once, we advise you to make use of the configuration and database files.

The use of the configuration file allows you to set up some default behaviours to create some consistency across your measurements. For more information about the configuration, see the Configuration info section.

The database flies will allow you to save metadata about the microfaded object in the excel data file, which can ultimately be used to perform queries. For example, you could ask to retrieve all measurements performed on a given material or on objects created by a specific artist, etc. Unfortunately, such as a possibility has not been implemented yet. To start using the databases, you will first need to create them and fill them with some information. To learn how to create databases, see the Create databases section. To learn how to fill the databases and properly manage them, see the Databases management section.

5. Use the docstrings¶

Whenever you will use functions from the microfading package, you will always be able to access the docstrings. These contain valuable information that will help you to adequately use the functions. To open the dosctrings, you have two possibilites:

Write the name of a function (without parentheses) followed by a question mark (see example below).

Opening a docstring with a question mark.
Write the name of a function (with parentheses), place the cursor inside the parentheses and press Ctrl + Caps Lock (see example below).