The Catalogue Class¶

This page describes the basic usage of the Catalogue class. This class is used for interfacing with the catalogue file. The catalogue provides meta data on all of the materials is in the database. These materials can then be loaded as Material objects into Python using the catalogue.

from dispersion import Catalogue
cat = Catalogue()

The catalogue relies on a specific file system structure in order to find the files in the database. An example of the file structure is the following,

database_root/
    catalogue.csv
    UserData/
        userfile1.txt
        userfile2.yml
        ...
    Module1/
        Module1_subdir1/
            mat1.yml
            mat2.yml
        Module1_subdir2/
            anothermat.yml
        ...
    Module2/
    ...

The catalogue files sits at the root level of the database filesystem. The other folders present in the root directory are the installed modules. By default a module called UserData is installed for the user to keep their data. Other modules consist of literature material databases available for download. See modules for a list of supported modules.

Building the Catalogue¶

Whenever new files are added to the database file system, the catalogue needs to be rebuilt.

To build the catalogue you can use the script included in this package

> dispersion_catalogue_rebuild

or alternatively you can rebuild from inside python

from dispersion import Catalogue
cat = Catalogue(rebuild='All')

When rebuilding the catalogue, you can choose to rebuild either some or all of the modules.

Setting an Alias¶

Many materials have different data files associated with them. In order to uniquely identify materials in the catalogue, a unique alias can be assigned to each material. This alias will be used later to extract the material from the database. By default all materials do not have any alias defined.

In order to set an alias, the catalogue file needs to be edited. This can be done in three ways: Externally, using python or interactively using iPython with the qgrid extension.

The following shows how to edit an alias using python.

row = cat.database[(cat.database.Name == name)]
cat.register_alias(row, "alias")

This will not work if there are multiple materials in the catalogue with the same “Name” attribute. In order to set the alias in this case, either use the path to the file on the inside the module folder as the filter,

row = cat.database[(cat.database.Path == path/to/file.txt)]
cat.register_alias(row, "alias")
cat.save_to_file()

or use the interactive editing. For this the qgrid IPython extension needs to be installed. Note that after installing the package with a package manager, iPython extensions need to be installed using,

jupyter nbextension enable --py --sys-prefix widgetsnbextension
jupyter nbextension enable --py --sys-prefix qgrid

After installation, open the catalogue in an IPython like environment (such as a Jupyter notebook) and use,

cat.edit_interactive()

note that “Interactive” must be set to true in the package configuration file to use interactive editing. After the aliases have been set in the alias column for the appropriate materials, the catalogue must be saved via,

cat.save_interactive()
cat.save_to_file()

The following animation shows the process of interactively editing the catalogue.

Accessing the Catalogue¶

To get a material from the database using the catalogue, use:

mat = cat.get_material("<mat_alias>")

this returns a Material object. If the argument of get_material is a string, then it must refer to the alias of the material in the catalogue. If the argument is an integer, it refers to the row number in the catalogue.

Full API¶

class catalogue.Catalogue(config=None, rebuild='None')¶

administers the set of material data files

this class is used to find and load data files from disk which describe spectrally resolved refractive index or permittivity data into Material objects.

Parameters:

config: dict or None: configuration data
rebuild: list or None: which modules which should be rebuilt
base_path: str: where the database file structure is stored
file_name: str: name of the catalogue file
database: pandas.DataFrame: the catalogue of material files
qgrid_widget: qgrid.widget: iPython widget for interactive editing of the catalogue
make_grid: function: qgrid function for refreshing the interactive interface
reference_spectrum: Spectrum: catalogue will provide n/k values at the reference spectrum value
rii_loader: dict: temporary dict used in constructing the refractive index info catalogue

Methods

`build_catalogue`(self, df, rebuild)	read specified modules and return a dataframe combining all modules
`edit_interactive`(self)	returns an editable qgrid instance for interactively viewing the catalogue.
`get_database`(self)	returns the pandas data frame
`get_material`(self, identifier)	get a material from the catalogue using its alias or row number
`make_reference_spectrum`(self, config)	make the spectrum with which every material in the catalogue will be evaluated
`read_filmetrics_db`(self, db_path)	read the file structure provided my filmetrics.com
`read_ri_info_db`(self, db_path)	read the file structure provided by the refractiveindex.info website
`read_user_data_db`(self, db_path)	read user data files
`register_alias`(self, row_id, alias)	create an alias for a material to easily access it from the catalogue
`save_interactive`(self)	saves changes made to the qgrid when interfactive edit mode has been used
`save_to_file`(self)	save the pandas dataframe to the root path of the catalogue file structure
`set_database`(self, database)	set the pandas data frame
`view_interactive`(self)	returns a read only qgrid instance for interactively viewing the catalogue

build_catalogue(self, df, rebuild)¶: read specified modules and return a dataframe combining all modules

edit_interactive(self)¶: returns an editable qgrid instance for interactively viewing the catalogue. Call the method save_interactive to save any changes made

get_database(self)¶: returns the pandas data frame

get_material(self, identifier)¶: get a material from the catalogue using its alias or row number

make_reference_spectrum(self, config)¶: make the spectrum with which every material in the catalogue will be evaluated

read_filmetrics_db(self, db_path)¶: read the file structure provided my filmetrics.com

read_ri_info_db(self, db_path)¶: read the file structure provided by the refractiveindex.info website

read_user_data_db(self, db_path)¶: read user data files

register_alias(self, row_id, alias)¶: create an alias for a material to easily access it from the catalogue

save_interactive(self)¶: saves changes made to the qgrid when interfactive edit mode has been used

save_to_file(self)¶: save the pandas dataframe to the root path of the catalogue file structure

set_database(self, database)¶: set the pandas data frame

view_interactive(self)¶: returns a read only qgrid instance for interactively viewing the catalogue