build_model_from_sset

Command-line usage

usage: cell build_model_from_sset [-h] [-ssf SSET_FILEPATH] [-npoints None]
                                  [-radii None] [-plf None] [-p None] [-me 0]
                                  [-vacancy-atomic-number 0]
                                  [-b trigonometric] [-rm None] [-sm None]
                                  [-thr 0.0] [-nt None]
                                  [-weights-filepath None] [-std] [-ts None]
                                  [-rs 42] [-sh] [-prune True] [-op None]
                                  property_name [selection_must_include]

positional arguments:
  property_name         Property to be modelled. Must be present in the
                        StructuresSet object.
  selection_must_include
                        [[]]

options:
  -h, --help            show this help message and exit
  -ssf, --sset-filepath SSET_FILEPATH
                        Path to a serialized StructuresSet object (training
                        data).
  -npoints None         List of numbers of points of the clusters to build.
  -radii None           List of cluster radii, one per entry of npoints.
  -plf, --plat-filepath None
                        Path to a serialized ParentLattice. Default: the one
                        of the structures set.
  -p, --psc None        Super cell definition where to find clusters.
  -me, --method 0       Method to use to find clusters.
  -vacancy-atomic-number 0
                        Atomic number of vacancy sites when serializing the
                        clusters pool.
  -b, --basis-name trigonometric
                        Cluster basis: indicator-binary, trigonometric,
                        polynomial, or chebyshev.
  -rm, --regression-model None
                        Dictionary of estimator options.
  -sm, --selection-model None
                        Dictionary of estimator options for feature selection
                        model (e.g. LASSO).
  -thr, --selection-threshold 0.0
                        Threshold on feature importance (|coefficient|) of the
                        selection model. The default 0.0 keeps all features.
  -nt, --nonlinear-transformation None
                        Dictionary of nonlinear transformation settings.
  -weights-filepath None
                        Sample weights for fitting and evaluating the weighted
                        MSE.
  -std, --standardize   Standardize the input data.
  -ts, --test-size None
                        Fraction of samples reserved as hold-out test set (no
                        split if not given).
  -rs, --random-state 42
                        Random seed of the optional train/test split.
  -sh, --shuffle        Shuffle samples before the optional split.
  -prune True           Build a model on a pruned clusters pool containing
                        only clusters used by the trained model.
  -op, --output-prefix None
                        Prefix of all created files. Default: property_name.

Arguments and behavior

clusterx.cli.build_model_from_sset.build_model_from_sset(property_name, sset_filepath, npoints=None, radii=None, plat_filepath=None, psc=None, method=0, vacancy_atomic_number=0, basis_name='trigonometric', regression_model=None, selection_model=None, selection_threshold=0.0, selection_must_include=[], nonlinear_transformation=None, weights_filepath=None, standardize=False, test_size=None, random_state=42, shuffle=False, prune=True, output_prefix=None)

Build a (nonlinear) cluster expansion model from a structures set in one step.

Chains the steps of build_cpool, build_ccalc, compute_comat and build_nonlinear_model. Unless prune is false, it then identifies the clusters whose correlations actually influence the trained model (taking the nonlinear transformation, selection model, selection_threshold and selection_must_include into account), builds a pruned clusters pool and correlations calculator with only those clusters, and serializes a second model that takes the pruned correlations as input. A ColumnExpander step at the start of its pipeline zero-pads the pruned correlations to the dimension expected by the trained steps. The prediction is exactly the same as that of the full model.

Created files (<prefix> is output_prefix or property_name):

<prefix>_0_log.md                  Markdown log of the run
<prefix>_1_full_{cpool.json, ccalc.pickle, comat.npz, model.pickle}
<prefix>_2_pruned_{cpool.json, ccalc.pickle, comat.npz, model.pickle}
Parameters:
property_namestr

Property to model. Must be present in the structures set.

sset_filepathstr

Serialized StructuresSet with the training data.

npoints, radiilist or str

Clusters to build: numbers of points and corresponding maximum radii.

plat_filepathstr, optional

Parent lattice file. Default: the parent lattice of the structures set.

psc, method, vacancy_atomic_number

As in build_cpool.

basis_namestr

As in build_ccalc.

regression_model, selection_model, selection_must_include

As in build_nonlinear_model.

nonlinear_transformation, weights_filepath, standardize, test_size

As in build_nonlinear_model.

random_state, shuffle

As in build_nonlinear_model.

selection_thresholdfloat, default 0.0

As in build_nonlinear_model but with a default of 0.0, i.e. the selection model removes no feature (features with exactly zero importance are still dropped from the pruned pool if the final regressor gives them zero weight). Raise it to select features.

prunebool, default True

Whether to build the pruned clusters pool, correlations calculator and model.

output_prefixstr, optional

Prefix of created files (may include a directory, which is created).