Introduction

The Cole-Cole decomposition tools are a collection of Python tools to analyze spectral electrical induced polarization (SIP) signatures using the Debye decomposition (DD), or its generalization, the Cole-Cole decomposition (CCD) scheme. These schemes as physically motivated phenomenological models than can fit and describe a large number of differently formed SIP signatures, which makes them a good choice if detailed process-based models are not available. The SIP signatures are described by a superposition of a large number of logarithmically distributed elementary polarization terms and the fitting procedure determines the relative weights of these elementary polarization responses, resulting in a so called relaxation time distribution (RTD). This procedure is similar to a Fourier analysis, which describes a given time series by a superposition of Sine and Cosine terms. The RTD can then be used to infer summarizing parameters than yield a strong descriptive character and can be used to analyze characteristics and trends in the underlying SIP data. This package was developed in a geophysical context.
We here present an open-source implementation of the DD and CCD schemes written in the Python programming language, free for everyone to use. The code is discussed in an corresponding peer-reviewed publication (see publications)
. This page is meant to provide information about the installation, usage, and underlying theory of the DD and CCD schemes, as well as a starting place for possible contributers.

View on GitHub Download .zip Download .tar.gz

Installation and Documentation

CCD documentation

Usage

unix style command line


	dd_single.py --frequency_file frequencies.dat --data_file data.dat --output results

python module

			  
 1 #!/usr/bin/env python
 2 # *-* coding: utf-8 *-*
 3 # simple example for using the ccd_single module directly with Python
 4 import lib_dd.decomposition.ccd_single as ccd_single
 5 import lib_dd.config.cfg_single as cfg_single
 6 import numpy as np
 7
 8 frequencies = np.loadtxt('data/frequencies.dat')
 9 data = np.loadtxt('data/data.dat')
10
11 # set options using this dict-like object
12 config = cfg_single.cfg_single()
13 config['frequency_file'] = frequencies
14 config['data_file'] = data
15 config['fixed_lambda'] = 10
16
17 # generate a ccd object
18 ccd_obj = ccd_single.ccd_single(config)
19
20 # commence with the actual fitting
21 ccd_obj.fit_data()
22
23 # extract the last iteration
24 last_it = ccd_obj.results[0].iterations[-1]
25
26 print(dir(last_it))
27 print('fit parameters', last_it.m)
28 print('stat_pars', last_it.stat_pars)
29
30 # save to directory
31 ccd_obj.save_to_directory()
)

web interface

We are planning to include a web interface usable as a local GUI replacement. This, however, is still work in progress.


Theory

Electrical polarization measurements are widely used to infer electrical material properties of laboratory samples. Here the electrical impedance (alternating-current resistance) is measured as a complex number. By taking into account the measurement geometry of the sample and the position of the measurement electrodes, the impedance can be transferred to a material property, the resistivity (with the inverse, the conductivity). Resistivities and conductivities are still complex numbers, which can be represented as a real and imaginary parts, or as magnitude and phase values.
The real part of the conductivity denotes the ohmic conduction properties of the sample, dominated by ionic conductivity of the poor fluid or interface conduction properties of geophysical samples. Metallic conduction can play an important role in other fields of applications.
The imaginary part of the conductivity represents non-ohmic polarization signals which, in geophysical applications, as mostly of a capacitive nature. Possible source of polarization are manifold, but low-frequency polarization in geophysical contexts is believed to be dominated by ionic dislocation at the electrical double layer (EDL).
Polarization processes are usually frequency dependent and correspondingly are measured a various frequencies ranging from the low mHz range to the kHz range (or even further). This results in a spectrum of the complex impedance, which is why the method is also called electrical impedance spectroscopy (EIS).

Download

Please refer to the github download page .

Publications

The code base is described in the publication:

Weigand M. and Kemna A. - Debye decomposition of time-lapse spectral induced polarisation data. Computers & Geosciences 2016. Open Access! (Link to Sciencedirect) Download PDF

Spectral parameters recovered from the Debye decomposition are compared with Cole-Cole parameters in this paper:

Weigand M. and Kemna A. - Relationship between Cole–Cole model parameters and spectral decomposition parameters derived from SIP data. Geophysical Journal International 2016. Open Access! (Link to Sciencedirect) Download PDF


Contact and Feedback

We welcome any kind of feedback. Especially we would really like to hear from you why you use the CCD tools, or why not. What can we do to improve the toolbox?

Please file bug reports or feature requests in the bug tracker on the github-page: issue tracker

Pull request are welcome, however, in case you plan larger changes please contact as in advance to make sure the changes don't collide with any internal progress not yet public.

Alternatives

The following projects/publications have working implementations of the Debye- or Warburg decompositions:

  1. Nordsiek & Weller, 2008
  2. Zisser et. al 2010
  3. TODO: add missing implementations
If you are just looking for a traditional Cole-Cole fit, have a look at the projects/publications:
  • https://github.com/m-weigand/Cole-Cole-fit
  • Kemna, 2000