Schemas (battdat.schemas)#

Schemas for battery data and metadata

pydantic model battdat.schemas.BatteryMetadata#

Bases: BaseModel

Representation for the metadata about a battery

The metadata captures the information about what experiment was run on what battery. A complete set of metadata should be sufficient to reproduce an experiment.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Config:

  • extra: str = allow

Fields:
field associated_ids: List[AnyUrl] | None = None#

Any identifiers associated with this data file. Identifiers can be any URI, such as DOIs of associated paper or HTTP addresses of associated websites

field authors: List[Tuple[str, str]] | None = None#

Name and affiliation of each of the authors of the data. First and last names

field battery: BatteryDescription | None = None#

Description of the battery being tested

field comments: str | None = None#

Long form comments describing the test

field dataset_name: str | None = None#

Name of a larger dataset this data is associated with

field is_measurement: bool = True#

Whether the data was created observationally as opposed to a computer simulation

field modeling: ModelMetadata | None = None#

Description of simulation approach

field name: str | None = None#

Name of the cell. Any format for the name is acceptable, as it is intended to be used by the battery data provider.

field source: str | None = None#

Organization who created this data

field test_protocol: CyclingProtocol | None = None#

Method used to

field version: str = '0.4.1'#

Version of this metadata. Set by the battery-data-toolkit

Battery Description (b.schemas.battery)#

Schemas associated with the components of a battery

pydantic model battdat.schemas.battery.BatteryDescription#

Bases: BaseModel

Description of the entire battery

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Config:

  • extra: str = allow

Fields:
field anode: ElectrodeDescription | None = None#

Name of the anode material

field cathode: ElectrodeDescription | None = None#

Name of the cathode material

field design: str | None = None#

Name of the battery type, such as the battery product ID

field dimensions: List[float] | None = None#

Dimensions of the battery in plain text.

field electrolyte: ElectrolyteDescription | None = None#

Name of the electrolyte material

field form_factor: str | None = None#

The general shape of the battery

field layer_count: int | None = None#

Number of layers within the battery

Constraints:

  • gt = 1

field manufacturer: str | None = None#

Manufacturer of the battery

field mass: float | None = None#

Mass of the entire battery. Units: kg

field nominal_capacity: float | None = None#

Rated capacity of the battery. Units: A-hr

pydantic model battdat.schemas.battery.ElectrodeDescription#

Bases: BaseModel

Description of an electrode

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Config:

  • extra: str = allow

Fields:
field area: float | None = None#

Total area of the electrode (units: cm2)

Constraints:

  • ge = 0

field loading: float | None = None#

Amount of active material per area (units: mg/cm^2)

Constraints:

  • ge = 0

field name: str [Required]#

Short description of the electrolyte type

field porosity: float | None = None#

Relative volume of the electrode occupied by gas (units: %)

Constraints:

  • ge = 0

  • le = 100

field product: str | None = None#

Name of the product. Unique to the supplier

field supplier: str | None = None#

Manufacturer of the material

field thickness: float | None = None#

Thickness of the material (units: um)

Constraints:

  • ge = 0

pydantic model battdat.schemas.battery.ElectrolyteAdditive#

Bases: BaseModel

Additive to the electrolyte

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Config:

  • extra: str = allow

Fields:
field amount: float | None = None#

Amount added to the solution

field name: str [Required]#

Name of the additive

field units: float | None = None#

Units of the amount

pydantic model battdat.schemas.battery.ElectrolyteDescription#

Bases: BaseModel

Description of the electrolyte

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Config:

  • extra: str = allow

Fields:
field additives: List[ElectrolyteAdditive] [Optional]#

Any additives present in the electrolyte

field name: str [Required]#

Short description of the electrolyte types

Metadata: Computation (b.schemas.modeling)#

Metadata which describes how data produced by models were generated

pydantic model battdat.schemas.modeling.ModelMetadata#

Bases: BaseModel

Describe the type and version of a computational tool used to generate battery data

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Config:

  • extra: str = allow

Fields:
field models: List[str] | None = None#

Type of mathematical model(s) being used in physics simulation.Use terms defined in BattINFO, such as “BatteryEquivalentCircuitModel”.

field name: str [Required]#

Name of the software

field references: List[AnyUrl] | None = None#

List of references associated with the software

field simulation_type: str | None = None#

Type of simulation being performed. Use terms defined in BattINFO, such as “TightlyCoupledModelsSimulation”

field type: ModelTypes | None = None#

Type of the computational method it implements.

field version: str | None [Required]#

Version of the software if known

class battdat.schemas.modeling.ModelTypes(value)#

Bases: str, Enum

Type of computational method

data = 'data'#

A computational application that uses existing data to predict the behaviour of a system without providing a identifiable analogy with the original object.

IRI: https://w3id.org/emmo#EMMO_a4b14b83_9392_4a5f_a2e8_b2b58793f59b

empirical = 'empirical'#

A computational application that uses an empiric equation to predict the behaviour of a system without relying on the knowledge of the actual physical phenomena occurring in the object.

IRI: https://w3id.org/emmo#EMMO_67c70dcd_2adf_4e6c_b3f8_f33dd1512487

physics = 'physics'#

A computational application that uses a physical model to predict the behaviour of a system, providing a identifiable analogy with the original object.

IRI: https://w3id.org/emmo#EMMO_8d4962d7_9608_44f7_a2f1_82a4bb173f4a

Metadata: Cycling Protocol (b.schemas.cycling)#

Describing cycling protocol

pydantic model battdat.schemas.cycling.CyclingProtocol#

Bases: BaseModel

Test protocol for cell cycling

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Config:

  • extra: str = allow

Fields:
field cycler: str | None = None#

Name of the cycling machine

field schedule: str | None = None#

Schedule file used for the cycling machine

field set_temperature: float | None = None#

Set temperature for the battery testing equipment. Units: C

field start_date: date | None = None#

Date the initial test on the cell began

Data: Time Series (b.schemas.column)#

Schemas related to describing cycling data

class battdat.schemas.column.ChargingState(value)#

Bases: str, Enum

Potential charging states of the battery

charging = 'charging'#
discharging = 'discharging'#
hold = 'hold'#
unknown = 'unknown'#
pydantic model battdat.schemas.column.ColumnInfo#

Bases: BaseModel

Description of a column for a schema

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Fields:
field description: str [Required]#

Human-readable description of the column

field monotonic: bool = False#

Whether the values should increase or remain constant between subsequent rows

field required: bool = False#

Whether the column is required

field type: DataType = DataType.OTHER#

Python type of the field (e.g., float)

field units: str | None = None#

Units for the value, if applicable

pydantic model battdat.schemas.column.ColumnSchema#

Bases: BaseModel

Base class for schemas that describe the columns of a table

Implement a schema to be re-used across multiple datasets by creating a subclass and adding attributes for each expected column. The type of each attribute must be a ColumnInfo and have a default value.

Save a Schema to disk in JSON format using model_dump_json(). Load it using the model_validate_json() method of the appropriate subclass, if you know the subclass, or from_json(), if you do not.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Config:

  • frozen: bool = True

Fields:
Validators:

  • _check_attributes » all fields

field extra_columns: Dict[str, ColumnInfo] [Optional]#

Descriptions of columns beyond those defined in the schema

Validated by:

  • _check_attributes

add_column(name: str, description: str, data_type: DataType = DataType.OTHER, required: bool = False, units: str | None = None, monotonic: bool = False) → ColumnInfo#

Add a new column to the extra_columns as a ColumnInfo object

Parameters:

  • name – Name of new column

  • description – Human-readable description of the data

  • data_type – Type of data

  • required – Whether the data must be included in a table

  • units – Units used for all rows in column

  • monotonic – Whether values must always remain constant or increase

Returns:

The new column object

classmethod from_json(buf: str) → ColumnSchema#

Read a JSON description of a column schema into an object

The object will not have the same class as the original, but will have the same column information.

Parameters:

buf – JSON version of this class

Returns:

Model as a subclass of ColumnSchema

validate_dataframe(data: DataFrame, allow_extra_columns: bool = True)#

Check whether a dataframe matches this schema

Parameters:

  • data – DataFrame to be assessed

  • allow_extra_columns – Whether to raise an error if the dataframe contains columns which are not defined in this schema.

Raises:

(ValueError) If the dataframe does not adhere –

property column_names: List[str]#

Names of all columns defined in this schema

property columns: Dict[str, ColumnInfo]#

Map of name to description for all columns

class battdat.schemas.column.ControlMethod(value)#

Bases: str, Enum

Method used to control battery during a certain step

constant_current = 'constant_current'#

A step where the current is held constant

constant_power = 'constant_power'#

A step where the power is held constant

constant_voltage = 'constant_voltage'#

A step where the voltage is held constant

other = 'other'#
pulse = 'pulse'#

A short period of a large current

rest = 'rest'#

An extended period of neither charging nor discharging

short_nonrest = 'short_nonrest'#

A very short period of charging or discharging. Defined as a step with 4 or fewer measurements with at least one non-zero current.

short_rest = 'short_rest'#

A very short rest period. Defined as a step with 4 or fewer measurements with near-zero current

pydantic model battdat.schemas.column.CycleLevelData#

Bases: ColumnSchema

Statistics about the performance of a cell over entire cycles

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Config:

  • frozen: bool = True

Fields:
Validators:

field V_maximum: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description='Maximum voltage during cycle', units='V', monotonic=False)#
Validated by:

  • _check_attributes

field V_minimum: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description='Minimum voltage during cycle', units='V', monotonic=False)#
Validated by:

  • _check_attributes

field capacity_charge: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description='Total amount of electrons stored during charge', units='A-hr', monotonic=False)#
Validated by:

  • _check_attributes

field capacity_discharge: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description='Total amount of electrons released during discharge', units='A-hr', monotonic=False)#
Validated by:

  • _check_attributes

field charge_I_average: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description='Average current during charge', units='A', monotonic=False)#
Validated by:

  • _check_attributes

field charge_V_average: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description='Average voltage during charge', units='V', monotonic=False)#
Validated by:

  • _check_attributes

field coulomb_efficiency: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description='Fraction of electric charge that is lost during charge and recharge', units='%', monotonic=False)#
Validated by:

  • _check_attributes

field cycle_duration: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description='Duration of this cycle', units='s', monotonic=False)#
Validated by:

  • _check_attributes

field cycle_number: ColumnInfo = ColumnInfo(required=True, type=<DataType.INTEGER: 'integer'>, description='Index of the cycle', units=None, monotonic=True)#
Validated by:

  • _check_attributes

field cycle_start: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description='Time since the first data point recorded for this battery for the start of this cycle', units='s', monotonic=True)#
Validated by:

  • _check_attributes

field discharge_I_average: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description='Average current during discharge', units='A', monotonic=False)#
Validated by:

  • _check_attributes

field discharge_V_average: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description='Average voltage during discharging', units='V', monotonic=False)#
Validated by:

  • _check_attributes

field energy_charge: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description='Total amount of energy stored during charge', units='W-hr', monotonic=False)#
Validated by:

  • _check_attributes

field energy_discharge: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description='Total amount of energy released during discharge', units='W-hr', monotonic=False)#
Validated by:

  • _check_attributes

field energy_efficiency: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description='Amount of energy lost during charge and discharge', units=None, monotonic=False)#
Validated by:

  • _check_attributes

field temperature_average: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description='Average observed battery temperature during cycle', units='C', monotonic=False)#
Validated by:

  • _check_attributes

field temperature_maximum: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description='Maximum observed battery temperature during cycle', units='C', monotonic=False)#
Validated by:

  • _check_attributes

field temperature_minimum: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description='Minimum observed battery temperature during cycle', units='C', monotonic=False)#
Validated by:

  • _check_attributes

class battdat.schemas.column.DataType(value)#

Bases: str, Enum

Types available for columns

CONTROL = 'control'#
FLOAT = 'float'#
INTEGER = 'integer'#
OTHER = 'other'#
STATE = 'state'#
pydantic model battdat.schemas.column.RawData#

Bases: ColumnSchema

Data describing measurements of a single cell

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Config:

  • frozen: bool = True

Fields:
Validators:

field current: ColumnInfo = ColumnInfo(required=True, type=<DataType.FLOAT: 'float'>, description='Measured current of the system. Positive current represents the battery charging.', units='A', monotonic=False)#
Validated by:

  • _check_attributes

field cycle_capacity: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description='Cumulative change in amount of charge transferred from a battery since the start of a cycle. Positive values indicate the battery has discharged since the start of the cycle.', units='A-hr', monotonic=False)#
Validated by:

  • _check_attributes

field cycle_capacity_charge: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description="Cycle capacity computed only during the 'charging' phase of a cycle", units='A-hr', monotonic=False)#
Validated by:

  • _check_attributes

field cycle_capacity_discharge: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description="Cycle capacity computed only during the 'discharging' phase of a cycle", units='A-hr', monotonic=False)#
Validated by:

  • _check_attributes

field cycle_energy: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description='Cumulative change in amount of energy transferred from a battery since the start of a cycle. Positive values indicate the battery has discharged since the start of the cycle.', units='J', monotonic=False)#
Validated by:

  • _check_attributes

field cycle_number: ColumnInfo = ColumnInfo(required=False, type=<DataType.INTEGER: 'integer'>, description='Index of the testing cycle, starting at 0.', units=None, monotonic=True)#
Validated by:

  • _check_attributes

field cycle_time: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description='Time from the beginning of a cycle', units='s', monotonic=True)#
Validated by:

  • _check_attributes

field file_number: ColumnInfo = ColumnInfo(required=False, type=<DataType.INTEGER: 'integer'>, description='Which file a row came from, if the data was originally split into multiple files', units=None, monotonic=True)#
Validated by:

  • _check_attributes

field internal_resistance: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description='Internal resistance of the battery.', units='ohm', monotonic=False)#
Validated by:

  • _check_attributes

field method: ColumnInfo = ColumnInfo(required=False, type=<DataType.CONTROL: 'control'>, description='Method to control the charge or discharge', units=None, monotonic=False)#
Validated by:

  • _check_attributes

field state: ColumnInfo = ColumnInfo(required=False, type=<DataType.STATE: 'state'>, description='Whether the battery is being charged, discharged or otherwise.', units=None, monotonic=False)#
Validated by:

  • _check_attributes

field step_index: ColumnInfo = ColumnInfo(required=False, type=<DataType.INTEGER: 'integer'>, description='Index of the step number within a testing cycle. A step change is defined by a change states between charging, discharging, or resting.', units=None, monotonic=False)#
Validated by:

  • _check_attributes

field substep_index: ColumnInfo = ColumnInfo(required=False, type=<DataType.INTEGER: 'integer'>, description='Change of the control method within a cycle.', units=None, monotonic=False)#
Validated by:

  • _check_attributes

field temperature: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description='Temperature of the battery', units='C', monotonic=False)#
Validated by:

  • _check_attributes

field test_time: ColumnInfo = ColumnInfo(required=True, type=<DataType.FLOAT: 'float'>, description='Time from the beginning of measurements', units='s', monotonic=True)#
Validated by:

  • _check_attributes

field time: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description='Time as a UNIX timestamp.', units='s', monotonic=True)#
Validated by:

  • _check_attributes

field voltage: ColumnInfo = ColumnInfo(required=True, type=<DataType.FLOAT: 'float'>, description='Measured voltage of the system', units='V', monotonic=False)#
Validated by:

  • _check_attributes

Data: EIS (b.schemas.eis)#

Schemas associated with Electrochemical Impedance Spectroscopy

pydantic model battdat.schemas.eis.EISData#

Bases: ColumnSchema

Measurements for a specific EIS test

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Config:

  • frozen: bool = True

Fields:
Validators:

field frequency: ColumnInfo = ColumnInfo(required=True, type=<DataType.FLOAT: 'float'>, description='Applied frequency', units='Hz', monotonic=False)#
Validated by:

  • _check_attributes

field test_id: ColumnInfo = ColumnInfo(required=True, type=<DataType.INTEGER: 'integer'>, description='Integer used to identify rows belonging to the same experiment.', units=None, monotonic=False)#
Validated by:

  • _check_attributes

field test_time: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description='Time from the beginning of measurements.', units='s', monotonic=True)#
Validated by:

  • _check_attributes

field time: ColumnInfo = ColumnInfo(required=False, type=<DataType.FLOAT: 'float'>, description='Time as a UNIX timestamp. Assumed to be in UTC', units=None, monotonic=False)#
Validated by:

  • _check_attributes

field z_imag: ColumnInfo = ColumnInfo(required=True, type=<DataType.FLOAT: 'float'>, description='Imaginary component of impedance', units='Ohm', monotonic=False)#
Validated by:

  • _check_attributes

field z_mag: ColumnInfo = ColumnInfo(required=True, type=<DataType.FLOAT: 'float'>, description='Magnitude of impedance', units='Ohm', monotonic=False)#
Validated by:

  • _check_attributes

field z_phase: ColumnInfo = ColumnInfo(required=True, type=<DataType.FLOAT: 'float'>, description='Phase angle of the impedance', units='Degree', monotonic=False)#
Validated by:

  • _check_attributes

field z_real: ColumnInfo = ColumnInfo(required=True, type=<DataType.FLOAT: 'float'>, description='Real component of impedance', units='Ohm', monotonic=False)#
Validated by:

  • _check_attributes

validate_dataframe(data: DataFrame, allow_extra_columns: bool = True)#

Check whether a dataframe matches this schema

Parameters:

  • data – DataFrame to be assessed

  • allow_extra_columns – Whether to raise an error if the dataframe contains columns which are not defined in this schema.

Raises:

(ValueError) If the dataframe does not adhere –

Utility: Ontologies (b.schemas.ontology)#

Tools used for linking terms in our data format to the BattINFO ontology

class battdat.schemas.ontology.TermInfo(name: str, iri: str, elucidation: str | None)#

Bases: object

Information about a term as referenced from the BattINFO ontology

elucidation: str | None#

Explanation of the term

classmethod from_thing(thing: Thing)#
iri: str#

IRI of the term

name: str#

Name of the matching term

battdat.schemas.ontology.cross_reference_terms(model: Type[BaseModel]) → dict[str, TermInfo]#

Gather the descriptions of fields from our schema which are cross-referenced to a term within the BattINFO/EMMO ontologies

Parameters:

model – Schema object to be cross-referenced

Returns:

Mapping between metadata fields in elucidation field from the ontology

battdat.schemas.ontology.gather_descendants(term: Type[Thing] | str) → List[TermInfo]#

Get descriptions of the descendants of a certain base type

Parameters:

term – Term for which to gather all descendants. Either the class object itself or its preferred label or IRI

Returns:

List of descriptions of the descendants

battdat.schemas.ontology.load_battinfo()#

Download and store the latest ontology into an in-memory

battdat.schemas.ontology.resolve_term(name_or_iri: str) → Thing#

Resolve the Term object associated with a string

Parameters:

name_or_iri – The preferred label or the IRI of a term in the ontology

Returns:

Thing matching the term

On this page
Show Source