magpie.data.materials

Class CompositionDataset

java.lang.Object

magpie.data.Dataset

magpie.data.MultiPropertyDataset

magpie.data.materials.CompositionDataset

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Citable, Commandable, Options, Printable, Savable

Direct Known Subclasses:

CrystalStructureDataset, PrototypeDataset

public class CompositionDataset
extends MultiPropertyDataset

This class stores entries that describe a material based solely on its composition.

Some of the available features include:

• Generate attributes based on composition only
• Read in data from specially-formatted input file
• Store multiple properties for a each entry

When reading data in from text using the importText function, the data must be whitespace-delimited with a header row giving property names and the composition of the material as the first row:

Composition property_1{class1,class2} property_2 ... property_N
As,0.2,B,0.8, class1 0.4 0.8 ...
AsB4, class2 0.9 none ...
Cu2Zr,4, class1 0.1 10.8 ...
<as many entries as you desire>

A few things to know about this format:

1. Format of composition doesn't matter too much. Only real requirement is that element names are capitalized.
2. If a property has discrete classes, you can specify what the allowed values are in the header by adding them to the property name surrounded by "{}"s and separated by commas.
3. If the measured value of a property is not known, put down "None"
4. For entries with duplicate compositions: Either select the values from lowest-energy duplicate entry or, if energy is not available, the average value of continuous properties or the lowest-index class value (i.e. which ever one is listed first in the header of the input file)

Attributes Generates several categories of attributes by default, which are described in CompositionDataset(boolean).

Implemented Commands:

attributes composition <true|false> - Set whether to use composition as attributes
true|false - Whether to use composition as attributes
By default, this class does not use composition (by itself) as attributes

attributes properties add <names...> - Add elemental properties to use when generating attributes
name...: Name of a elemental properties

attributes properties add set <name> - Add in all elemental properties from a pre-defined set
name: Name of the pre-defined set

attributes properties remove <names...> - Remove properties from list of those used when generating attributes
names...: Name of properties to remove

attributes properties pair add <names...> - Add properties of element pairs to use when generating attributes
name...: Name of a elemental properties

attributes properties pair remove <names...> - Remove properties of element pairs from list of those used when generating attributes
names...: Name of properties to remove

attributes properties pair add <difference|ratio> <names...> - Add properties of element pairs generated by computing the difference or ratio of properties of each element in the pair
difference|ratio: Whether to compute the difference or ratio
names...: Name of elemental properties used to generate derivative attributes In order to make the attribute insensitive to the order of elements in the pair, difference is the absolute difference and ratio is the minimum divided by the maximum

attributes properties <directory> - Specify directory that contains the elemental property lookup files
directory: Desired directory

Implemented Save Formats

comp - All properties with composition written by element fraction
Very similar to the "prop" format"

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	DataDirectory Location of lookup date files
protected java.util.List<java.lang.String>	ElementalProperties List of properties used when generating attributes
java.lang.String[]	ElementNames List of element names
protected java.util.List<java.lang.String>	ElementPairProperties List of properties of pairs of elements used when generating attributes
protected double[][]	OxidationStates Oxidation states of every element
protected java.util.SortedMap<java.lang.String,double[][]>	PairPropertyData Map of properties of pairs of elements
protected java.util.SortedMap<java.lang.String,double[]>	PropertyData Map of elemental property names to values
protected int[]	SortingOrder Order in which elements are sorted (used when printing)

Fields inherited from class magpie.data.Dataset

AttributeName, Entries, Expanders, Generators

Constructor Summary

Constructors

Constructor and Description
CompositionDataset() Create a dataset using the default set of attribute generators.
CompositionDataset(boolean useDefaultGenerators) Create a blank dataset.

Method Summary

Modifier and Type	Method and Description
void	addElementalProperty(java.lang.String Name) Define a new elemental property to use when generating attributes.
void	addElementalPropertySet(java.lang.String setName) Add a set of elemental properties to the list of those used when computing attributes.
void	addElementPairProperty(java.lang.String propName) Add a property of a pair of elements that will be used when generating attributes
CompositionEntry	addEntry(java.lang.String input) A new entry by parsing an input string.
java.lang.String	addGeneratedElementPairProperty(java.lang.String basePropName, java.lang.String method) Generate a new lookup table for properties of pairs of elements from properties of single elements
protected void	calculateAttributes() Compute attributes that are specific to this class.
boolean	compositionCanFormIonic(CompositionEntry entry) Whether a composition can form a neutral compound assuming each element takes only a single oxidation state.
CompositionDataset	createTemplate() Create a template designed to be saved using serialization
CompositionDataset	emptyClone() Creates a new instance with the same class and attribute names, but without any entries.
java.lang.String	getDataDirectory() Get path to directory containing elemental property lookup-data
java.util.List<java.lang.String>	getElementalProperties() Get list of elemental properties currently being used to generate attributes.
java.util.List<java.lang.String>	getElementPairProperties() Get list of properties of pairs of elements currently being used to generate attributes.
CompositionEntry	getEntry(int index) Retrieve a single entry from the dataset
double[][]	getOxidationStates() Get the list of known oxidation states
double[][]	getPairPropertyLookupTable(java.lang.String propertyName) Get a lookup table for the properties of pairs of elements
double[]	getPropertyLookupTable(java.lang.String propertyName) Reads in a data file that contains properties for each element.
int[]	getSortingOrder() Get the order in which elements are sorted when storing a composition.
void	importText(java.lang.String filename, java.lang.Object[] options) Read in an dataset from file.
java.lang.String	printEntryDescription(boolean htmlFormat) Print out what the entries to this dataset are.
boolean	removeElementalProperty(java.lang.String name) Remove an elemental property from the list used when generating attributes
boolean	removeElementPairProperty(java.lang.String name) Remove an elemental property from the list used when generating attributes
protected java.lang.Object	runAttributeCommand(java.util.List<java.lang.Object> Command) Run commands related to attributes of each entry.
java.lang.Object	runCommand(java.util.List<java.lang.Object> Command) Process some command described by a list of Objects.
protected java.lang.Object	runPairPropertyCommand(java.util.List<java.lang.Object> command) Run commands that set the element pair properties to be used when generating attributes.
protected java.lang.Object	runPropertyCommand(java.util.List<java.lang.Object> Command) Run commands that control which elemental properties are used when generating attributes
java.lang.String	saveCommand(java.lang.String Basename, java.lang.String Format) Handles complicated saving commands.
void	setDataDirectory(java.lang.String directory) Define whether to look for elemental property lookup tables.
void	useCompositionAsAttributes(boolean decision) Set whether to use composition (i.e.

Methods inherited from class magpie.data.MultiPropertyDataset

addEntries, addEntries, addEntry, addProperty, addProperty, clearPropertyData, combine, definePropertyNames, getClassNames, getMeasuredPropertyArray, getMeasuredPropertyArray, getPredictedPropertyArray, getPredictedPropertyArray, getPropertyClassCount, getPropertyClasses, getPropertyClasses, getPropertyIndex, getPropertyName, getPropertyNames, getTargetPropertyIndex, getTargetPropertyName, hasProperty, importEntryProperties, importPropertyNames, NClasses, NProperties, setClassNames, setPropertyClasses, setTargetProperty, setTargetProperty, toJSON, toString, usingPropertyAsClass

Methods inherited from class magpie.data.Dataset

about, addAttribute, addAttributeExpander, addAttributeGenerator, addAttributes, clearAttributeExpanders, clearAttributeGenerators, clearAttributes, clearData, clone, combine, combine, containsEntry, deleteMeasuredClasses, deletePredictedClasses, finalizeGeneration, generateAttributes, getAttributeArray, getAttributeExpanders, getAttributeGenerators, getAttributeIndex, getAttributeName, getAttributeNames, getCitations, getClassName, getClassProbabilityArray, getDistribution, getDistributionCount, getDuplicates, getEntries, getEntriesWriteAccess, getEntryArray, getMeasuredClassArray, getPredictedClassArray, getRandomSplit, getRandomSplit, getRandomSplit, getRandomSplit, getRandomSubset, getRandomSubset, getSingleAttributeArray, getSubset, getTrainingExamples, getUniqueEntries, loadState, matchEntries, NAttributes, NEntries, partition, partition, printAttributeDescription, printCommand, printDescription, printDistribution, printEntries, printUsage, removeDuplicates, resolveDuplicates, restoreAttributes, runAttributeExpanders, runAttributeExpansionCommand, runAttributeGeneratorCommand, runAttributeGenerators, saveState, saveTemplate, setAttributeNames, setClassProbabilities, setMeasuredClasses, setOptions, setPredictedClasses, splitForThreading, splitIntoFolds, splitIntoFolds, subtract, transferToWeka

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ElementNames

public java.lang.String[] ElementNames

List of element names

SortingOrder

protected int[] SortingOrder

Order in which elements are sorted (used when printing)

DataDirectory

protected java.lang.String DataDirectory

Location of lookup date files

ElementalProperties

protected java.util.List<java.lang.String> ElementalProperties

List of properties used when generating attributes

ElementPairProperties

protected java.util.List<java.lang.String> ElementPairProperties

List of properties of pairs of elements used when generating attributes

PropertyData

protected java.util.SortedMap<java.lang.String,double[]> PropertyData

Map of elemental property names to values

PairPropertyData

protected java.util.SortedMap<java.lang.String,double[][]> PairPropertyData

Map of properties of pairs of elements

OxidationStates

protected double[][] OxidationStates

Oxidation states of every element

Constructor Detail

CompositionDataset

public CompositionDataset()

Create a dataset using the default set of attribute generators.

CompositionDataset

public CompositionDataset(boolean useDefaultGenerators)

Create a blank dataset. Default attribute generator set:

1. StoichiometricAttributeGenerator: Generate attributes based on fractions of elements. Does not depend on what the elements actually are. Will use p = 2, 3, 5, 7, 10 norms.
2. ValenceShellAttributeGenerator: Attributes based on the valence shell electrons of the constituent elements
3. ElementalPropertyAttributeGenerator: Generate attributes based on properties of constituent elements. Use the list of attributes provided through "attributes properties add" or addElementalProperty(java.lang.String) operations for the commandline and Java interfaces, respectively.
4. IonicityAttributeGenerator: Attributes designed to represent the "ionicity" of a compound.

Parameters:

useDefaultGenerators - [in] Whether to use default generators

Method Detail

emptyClone

public CompositionDataset emptyClone()

Description copied from class: Dataset

Creates a new instance with the same class and attribute names, but without any entries.

Overrides:

emptyClone in class MultiPropertyDataset

Returns:

Dataset with same properties, no entries

createTemplate

public CompositionDataset createTemplate()

Description copied from class: Dataset

Create a template designed to be saved using serialization

Overrides:

createTemplate in class MultiPropertyDataset

Returns:

An empty clone of the dataset, with any additional changes made

getEntry

public CompositionEntry getEntry(int index)

Description copied from class: Dataset

Retrieve a single entry from the dataset

Overrides:

getEntry in class MultiPropertyDataset

Parameters:

index - Index of entry

Returns:

Specified entry

addEntry

public CompositionEntry addEntry(java.lang.String input)
                          throws java.lang.Exception

Description copied from class: Dataset

A new entry by parsing an input string. After using this operation, it may be necessary to recalculate attributes.

Overrides:

addEntry in class Dataset

Parameters:

input - String describing the entry

Returns:

Entry representing the parsed string.

Throws:

java.lang.Exception - If conversion fails

getSortingOrder

public int[] getSortingOrder()

Get the order in which elements are sorted when storing a composition. Sorting makes it faster to detect whether compounds are equal

Returns:

Sorting order

importText

public void importText(java.lang.String filename,
                       java.lang.Object[] options)
                throws java.lang.Exception

Read in an dataset from file. See documentation for format information.

Overrides:

importText in class Dataset

Parameters:

filename - Path of file to be imported

options - Any options used to control import

Throws:

java.lang.Exception

useCompositionAsAttributes

public void useCompositionAsAttributes(boolean decision)

Set whether to use composition (i.e. fraction of each element present) as attributes.

By default: This class does not use fractions as attributes.

Parameters:

decision - Whether to use it or not

getDataDirectory

public java.lang.String getDataDirectory()

Get path to directory containing elemental property lookup-data

Returns:

directory Path to the lookup-data directory

setDataDirectory

public void setDataDirectory(java.lang.String directory)

Define whether to look for elemental property lookup tables.

Elemental property tables should have the properties for each element on a separate line, sorted by Atomic Number. If the property is not known, write "None". You will be alerted if that property was needed generating attributes.

Parameters:

directory - Path to the elemental property lookup directory

addElementalProperty

public void addElementalProperty(java.lang.String Name)

Define a new elemental property to use when generating attributes.

Parameters:

Name - Name of property

addElementalPropertySet

public void addElementalPropertySet(java.lang.String setName)
                             throws java.lang.Exception

Add a set of elemental properties to the list of those used when computing attributes.

Parameters:

setName - Name of set

Throws:

java.lang.Exception

See Also:

PropertyLists.getPropertySet(java.lang.String)

addElementPairProperty

public void addElementPairProperty(java.lang.String propName)

Add a property of a pair of elements that will be used when generating attributes

Parameters:

propName - Name of property

addGeneratedElementPairProperty

public java.lang.String addGeneratedElementPairProperty(java.lang.String basePropName,
                                                        java.lang.String method)
                                                 throws java.lang.Exception

Generate a new lookup table for properties of pairs of elements from properties of single elements

Parameters:

basePropName - Name of property used to generate the new lookup table

method - Method used to generate new attributes. Supported methods are: "difference" and "ratio"

Returns:

Name of new lookup table

Throws:

java.lang.Exception

getElementalProperties

public java.util.List<java.lang.String> getElementalProperties()

Get list of elemental properties currently being used to generate attributes.

Returns:

List of elemental properties

getElementPairProperties

public java.util.List<java.lang.String> getElementPairProperties()

Get list of properties of pairs of elements currently being used to generate attributes.

Returns:

List of elemental properties

removeElementalProperty

public boolean removeElementalProperty(java.lang.String name)

Remove an elemental property from the list used when generating attributes

Parameters:

name - Name of property

Returns:

Whether the property was found and removed

removeElementPairProperty

public boolean removeElementPairProperty(java.lang.String name)

Remove an elemental property from the list used when generating attributes

Parameters:

name - Name of property

Returns:

Whether the property was found and removed

calculateAttributes

protected void calculateAttributes()

Description copied from class: Dataset

Compute attributes that are specific to this class.

Overrides:

calculateAttributes in class Dataset

getPropertyLookupTable

public double[] getPropertyLookupTable(java.lang.String propertyName)
                                throws java.lang.Exception

Reads in a data file that contains properties for each element. MeasuredProperty list should be contained in a file named PropertyName.table

Parameters:

propertyName - Elemental property of interest

Returns:

That property for each element

Throws:

java.lang.Exception

getPairPropertyLookupTable

public double[][] getPairPropertyLookupTable(java.lang.String propertyName)
                                      throws java.lang.Exception

Get a lookup table for the properties of pairs of elements

Parameters:

propertyName - Name of desired lookup table

Returns:

Lookup table

Throws:

java.lang.Exception

See Also:

LookupData.ElementPairProperties

getOxidationStates

public double[][] getOxidationStates()

Get the list of known oxidation states

Returns:

List of oxidation states

compositionCanFormIonic

public boolean compositionCanFormIonic(CompositionEntry entry)

Whether a composition can form a neutral compound assuming each element takes only a single oxidation state.

Parameters:

entry - Composition to be assessed

Returns:

Whether it can form an ionic compound

runCommand

public java.lang.Object runCommand(java.util.List<java.lang.Object> Command)
                            throws java.lang.Exception

Description copied from interface: Commandable

Process some command described by a list of Objects.

Specified by:

runCommand in interface Commandable

Overrides:

runCommand in class MultiPropertyDataset

Parameters:

Command - Command as a list of objects

Returns:

Any output (null if no output generated by command)

Throws:

java.lang.Exception - If something goes wrong

runAttributeCommand

protected java.lang.Object runAttributeCommand(java.util.List<java.lang.Object> Command)
                                        throws java.lang.Exception

Description copied from class: Dataset

Run commands related to attributes of each entry. Starts with the action to perform on the attributes

Overrides:

runAttributeCommand in class Dataset

Parameters:

Command - Operation to be run on/about attributes

Returns:

Any output (null if nothing is created)

Throws:

java.lang.Exception - On any error

runPairPropertyCommand

protected java.lang.Object runPairPropertyCommand(java.util.List<java.lang.Object> command)
                                           throws java.lang.Exception

Run commands that set the element pair properties to be used when generating attributes.

Parameters:

command - Command to be parsed

Returns:

Throws:

java.lang.Exception

runPropertyCommand

protected java.lang.Object runPropertyCommand(java.util.List<java.lang.Object> Command)
                                       throws java.lang.Exception

Run commands that control which elemental properties are used when generating attributes

Parameters:

Command - Command to act on

Returns:

Any output from operation (null if no output)

Throws:

java.lang.Exception

saveCommand

public java.lang.String saveCommand(java.lang.String Basename,
                                    java.lang.String Format)
                             throws java.lang.Exception

Description copied from interface: Savable

Handles complicated saving commands.

Dev Note: Make sure to add save format to Javadoc. See Dataset as an example. Required format:

<save><p><b>format<b> - Description
<br>Optional room to talk more about format </save>

Specified by:

saveCommand in interface Savable

Overrides:

saveCommand in class MultiPropertyDataset

Parameters:

Basename - Name of file without extension

Format - Command specifying format in which to print

Returns:

Filename Path to output file

Throws:

java.lang.Exception - If command not understood

printEntryDescription

public java.lang.String printEntryDescription(boolean htmlFormat)

Description copied from class: Dataset

Print out what the entries to this dataset are.

Overrides:

printEntryDescription in class Dataset

Parameters:

htmlFormat - Whether to print in HTML format

Returns:

Description of each entry (i.e., what kind of data is this).