API reference¶
This page provides an auto-generated summary of pyXpcm’s API. For more details and examples, refer to the relevant chapters in the main part of the documentation.
Top-level PCM functions¶
Creating a PCM¶
pcm (K, features[, scaling, reduction, …]) |
Profile Classification Model class constructor |
pyxpcm.load_netcdf (ncfile) |
Load a PCM model from netcdf file |
Attributes¶
pcm.K |
Return the number of classes |
pcm.F |
Return the number of features |
pcm.features |
Return features definition dictionnary |
Computation¶
pcm.fit (self, ds[, features, dim]) |
Estimate PCM parameters |
pcm.fit_predict (self, ds[, features, dim, …]) |
Estimate PCM parameters and predict classes. |
pcm.predict (self, ds[, features, dim, …]) |
Predict labels for profile samples |
pcm.predict_proba (self, ds[, features, dim, …]) |
Predict posterior probability of each components given the data |
pcm.score (self, ds[, features, dim]) |
Compute the per-sample average log-likelihood of the given data |
pcm.bic (self, ds[, features, dim]) |
Compute Bayesian information criterion for the current model on the input dataset |
Low-level PCM properties and functions¶
pcm.timeit |
Return a pandas.DataFrame with Execution time of method called on this instance |
pcm.ravel (self, da[, dim, feature_name]) |
Extract from N-d array a X(feature,sample) 2-d array and vertical dimension z |
pcm.unravel (self, ds, sampling_dims, X) |
Create a DataArray from a numpy array and sampling dimensions |
Plotting¶
pcm.plot |
Access plotting functions |
Plot PCM Contents¶
plot.quantile (m, da[, xlim, classdimname, …]) |
Plot q-th quantiles of a dataArray for each PCM components |
plot.scaler (m[, style, plot_kw, subplot_kw]) |
Plot PCM scalers properties |
plot.reducer (m[, pcalist, style, maxcols, …]) |
Plot PCM reducers properties |
plot.preprocessed (m, ds[, features, dim, n, …]) |
Plot preprocessed features as pairwise scatter plots |
plot.timeit (m[, group, split, subplot_kw, …]) |
Plot PCM registered timing of operations |
Tools¶
plot.cmap (m, name[, palette, usage]) |
Return categorical colormaps |
plot.colorbar (m[, cmap]) |
Add a colorbar to the current plot with centered ticks on discrete colors |
plot.subplots (m[, maxcols, K, subplot_kw]) |
Return (figure, axis) with one subplot per cluster |
plot.latlongrid (ax[, dx, dy, fontsize]) |
Add latitude/longitude grid line and labels to a cartopy geoaxes |
Statistics¶
pcm.stat |
Access statistics functions |
stat.quantile (ds[, q, of, using, outname, …]) |
Compute q-th quantile of a xarray.DataArray for each PCM components |
stat.robustness (ds[, name, classdimname, …]) |
Compute classification robustness |
stat.robustness_digit (ds[, name, …]) |
Digitize classification robustness |
Save/load PCM models¶
pcm.to_netcdf (self, ncfile, \*\*ka) |
Save a PCM to a netcdf file |
pyxpcm.load_netcdf (ncfile) |
Load a PCM model from netcdf file |
Helper¶
tutorial.open_dataset (name) |
Open a dataset from the pyXpcm online data repository (requires internet). |
Xarray pyxpcm name space¶
Provide accessor to enhance interoperability between xarray
and pyxpcm
.
Provide a scope named pyxpcm
as accessor to xarray.Dataset
objects.
-
class
pyxpcm.xarray.
pyXpcmDataSetAccessor
[source]¶ Class registered under scope
pyxpcm
to accessxarray.Dataset
objects.-
add
(self, da)[source]¶ Add a
xarray.DataArray
to thisxarray.Dataset
-
bic
(self, this_pcm, **kwargs)[source]¶ Compute Bayesian information criterion for the current model on the input dataset
Only for a GMM classifier
Parameters: - ds: :class:`xarray.Dataset`
The dataset to work with
- features: dict()
Definitions of PCM features in the input
xarray.Dataset
. If not specified or set to None, features are identified usingxarray.DataArray
attributes ‘feature_name’.- dim: str
Name of the vertical dimension in the input
xarray.Dataset
Returns: - bic: float
The lower the better
-
drop_all
(self)[source]¶ Remove
xarray.DataArray
created with pyXpcm front thisxarray.Dataset
-
feature_dict
(self, this_pcm, features=None)[source]¶ Return dictionary of features for this
xarray.Dataset
and a PCMParameters: - pcm :
pyxpcm.pcmmodel.pcm
- features : dict
Keys are PCM feature name, Values are corresponding
xarray.Dataset
variable names
Returns: - dict()
Dictionary where keys are PCM feature names and values the corresponding
xarray.Dataset
variables
- pcm :
-
fit
(self, this_pcm, **kwargs)[source]¶ Estimate PCM parameters
For a PCM, the fit method consists in the following operations:
- pre-processing
- interpolation to the
feature_axis
levels of the model - scaling
- reduction
- interpolation to the
- estimate classifier parameters
Parameters: - ds: :class:`xarray.Dataset`
The dataset to work with
- features: dict()
Definitions of PCM features in the input
xarray.Dataset
. If not specified or set to None, features are identified usingxarray.DataArray
attributes ‘feature_name’.- dim: str
Name of the vertical dimension in the input
xarray.Dataset
Returns: - self
-
fit_predict
(self, this_pcm, **kwargs)[source]¶ Estimate PCM parameters and predict classes.
This method add these properties to the PCM object:
llh
: The log likelihood of the model with regard to new data
Parameters: - ds: :class:`xarray.Dataset`
The dataset to work with
- features: dict()
Definitions of PCM features in the input
xarray.Dataset
. If not specified or set to None, features are identified usingxarray.DataArray
attributes ‘feature_name’.- dim: str
Name of the vertical dimension in the input
xarray.Dataset
- inplace: boolean, False by default
If False, return a
xarray.DataArray
with predicted labels If True, return the inputxarray.Dataset
with labels added as a newxarray.DataArray
- name: string (‘PCM_LABELS’)
Name of the DataArray holding labels.
Returns: xarray.DataArray
Component labels (if option ‘inplace’ = False)
- or
xarray.Dataset
Input dataset with component labels as a ‘PCM_LABELS’ new
xarray.DataArray
(if option ‘inplace’ = True)
-
mask
(self, this_pcm, features=None, dim=None)[source]¶ Create a mask where all PCM features are defined
Create a mask where all feature profiles are not null over the this_pcm feature axis.
Parameters: - :class:`pyxpcm.pcmmodel.pcm`
- features : dict()
Definitions of this_pcm features in the
xarray.Dataset
. If not specified or set to None, features are identified usingxarray.DataArray
attributes ‘feature_name’.- dim : str
Name of the vertical dimension in the
xarray.Dataset
. If not specified or set to None, dim is identified as thexarray.DataArray
variables with attributes ‘axis’ set to ‘z’.
Returns:
-
predict
(self, this_pcm, inplace=False, **kwargs)[source]¶ Predict labels for profile samples
This method add these properties to the PCM object:
llh
: The log likelihood of the model with regard to new data
Parameters: - ds: :class:`xarray.Dataset`
The dataset to work with
- features: dict()
Definitions of PCM features in the input
xarray.Dataset
. If not specified or set to None, features are identified usingxarray.DataArray
attributes ‘feature_name’.- dim: str
Name of the vertical dimension in the input
xarray.Dataset
- inplace: boolean, False by default
If False, return a
xarray.DataArray
with predicted labels If True, return the inputxarray.Dataset
with labels added as a newxarray.DataArray
- name: str, default is ‘PCM_LABELS’
Name of the
xarray.DataArray
with labels
Returns: xarray.DataArray
Component labels (if option ‘inplace’ = False)
- or
xarray.Dataset
Input dataset with Component labels as a ‘PCM_LABELS’ new
xarray.DataArray
(if option ‘inplace’ = True)
-
predict_proba
(self, this_pcm, **kwargs)[source]¶ Predict posterior probability of each components given the data
This method adds these properties to the PCM instance:
llh
: The log likelihood of the model with regard to new data
Parameters: - ds: :class:`xarray.Dataset`
The dataset to work with
- features: dict()
Definitions of PCM features in the input
xarray.Dataset
. If not specified or set to None, features are identified usingxarray.DataArray
attributes ‘feature_name’.- dim: str
Name of the vertical dimension in the input
xarray.Dataset
- inplace: boolean, False by default
If False, return a
xarray.DataArray
with predicted probabilities If True, return the inputxarray.Dataset
with probabilities added as a newxarray.DataArray
- name: str, default is ‘PCM_POST’
Name of the DataArray with prediction probability (posteriors)
- classdimname: str, default is ‘pcm_class’
Name of the dimension holding classes
Returns: xarray.DataArray
Probability of each Gaussian (state) in the model given each sample (if option ‘inplace’ = False)
- or
xarray.Dataset
Input dataset with Component Probability as a ‘PCM_POST’ new
xarray.DataArray
(if option ‘inplace’ = True)
-
quantile
(self, this_pcm, inplace=False, **kwargs)[source]¶ Compute q-th quantile of a
xarray.DataArray
for each PCM componentsParameters: - q: float in the range of [0,1] (or sequence of floats)
Quantiles to compute, which must be between 0 and 1 inclusive.
- of: str
Name of the
xarray.Dataset
variable to compute quantiles for.- using: str
Name of the
xarray.Dataset
variable with classification labels to use. Use ‘PCM_LABELS’ by default.- outname: ‘PCM_QUANT’ or str
Name of the
xarray.DataArray
with quantile- keep_attrs: boolean, False by default
Preserve
of
xarray.Dataset
attributes or not in the new quantile variable.
Returns: xarray.Dataset
with shape (K, n_quantiles, N_z=n_features)- or
xarray.DataArray
with shape (K, n_quantiles, N_z=n_features)
-
robustness
(self, this_pcm, inplace=False, **kwargs)[source]¶ Compute classification robustness
Parameters: - name: str, default is ‘PCM_POST’
Name of the
xarray.DataArray
with prediction probability (posteriors)- classdimname: str, default is ‘pcm_class’
Name of the dimension holding classes
- outname: ‘PCM_ROBUSTNESS’ or str
Name of the
xarray.DataArray
with robustness- inplace: boolean, False by default
If False, return a
xarray.DataArray
with robustness If True, return the inputxarray.Dataset
with robustness added as a newxarray.DataArray
Returns: xarray.Dataset
if inplace=True- or
xarray.DataArray
if inplace=False
-
robustness_digit
(self, this_pcm, inplace=False, **kwargs)[source]¶ Digitize classification robustness
Parameters: - ds: :class:`xarray.Dataset`
Input dataset
- name: str, default is ‘PCM_POST’
Name of the
xarray.DataArray
with prediction probability (posteriors)- classdimname: str, default is ‘pcm_class’
Name of the dimension holding classes
- outname: ‘PCM_ROBUSTNESS_CAT’ or str
Name of the
xarray.DataArray
with robustness categories- inplace: boolean, False by default
If False, return a
xarray.DataArray
with robustness If True, return the inputxarray.Dataset
with robustness categories added as a newxarray.DataArray
Returns: xarray.Dataset
if inplace=True- or
xarray.DataArray
if inplace=False
-
sampling_dim
(self, this_pcm, features=None, dim=None)[source]¶ Return the list of dimensions to be stacked for sampling
Parameters: - pcm :
pyxpcm.pcm
- features : None (default) or dict()
Keys are PCM feature name, Values are corresponding
xarray.Dataset
variable names. It set to None, all PCM features are used.- dim : None (default) or str()
The
xarray.Dataset
dimension to use as vertical axis in all features. If set to None, it is automatically set to the dimension with an attributeaxis
set toZ
.
Returns: - dict()
Dictionary where keys are
xarray.Dataset
variable names of features and values are another dictionary with the list of sampling dimension in DIM_SAMPLING key and the name of the vertical axis in the DIM_VERTICAL key.
- pcm :
-
score
(self, this_pcm, **kwargs)[source]¶ Compute the per-sample average log-likelihood of the given data
Parameters: - ds: :class:`xarray.Dataset`
The dataset to work with
- features: dict()
Definitions of PCM features in the input
xarray.Dataset
. If not specified or set to None, features are identified usingxarray.DataArray
attributes ‘feature_name’.- dim: str
Name of the vertical dimension in the input
xarray.Dataset
Returns: - log_likelihood: float
In the case of a GMM classifier, this is the Log likelihood of the Gaussian mixture given data
-
split
(self)[source]¶ Split pyXpcm variables from the original
xarray.Dataset
Returns: xarray.Dataset
,xarray.Dataset
Two DataSest: one with pyXpcm variables, one with the original DataSet
-