DataModel

class stdatamodels.DataModel(init=None, schema=None, memmap=False, pass_invalid_values=None, strict_validation=None, validate_on_assignment=None, validate_arrays=False, ignore_missing_extensions=True, **kwargs)

Bases: ObjectNode

Base class of all of the data models.

Parameters:

initstr, tuple, ~astropy.io.fits.HDUList, ndarray, dict, None

• None : Create a default data model with no shape.

• tuple : Shape of the data array. Initialize with empty data array with shape specified by the.

• file path: Initialize from the given file (FITS or ASDF)

• readable file object: Initialize from the given file object

• ~astropy.io.fits.HDUList : Initialize from the given ~astropy.io.fits.HDUList.

• A numpy array: Used to initialize the data array

• dict: The object model tree for the data model

schemadict, str (optional)

Tree of objects representing a JSON schema, or string naming a schema. The schema to use to understand the elements on the model. If not provided, the schema associated with this class will be used.

memmapbool

Turn memmap of FITS/ASDF file on or off. (default: False).

pass_invalid_valuesbool or None

If True, values that do not validate the schema will be added to the metadata. If False, they will be set to None. If None, value will be taken from the environmental PASS_INVALID_VALUES. Otherwise the default value is False.

strict_validationbool or None

If True, schema validation errors will generate an exception. If False, they will generate a warning. If None, value will be taken from the environmental STRICT_VALIDATION. Otherwise, the default value is False.

validate_on_assignmentbool or None

Defaults to ‘None’. If None, value will be taken from the environmental VALIDATE_ON_ASSIGNMENT, defaulting to ‘True’ if no environment variable is set. If ‘True’, attribute assignments are validated at the time of assignment. Validation errors generate warnings and values will be set to None. If ‘False’, schema validation occurs only once at the time of write. Validation errors generate warnings.

validate_arraysbool

If True, arrays will be validated against ndim, max_ndim, and datatype validators in the schemas.

ignore_missing_extensionsbool

When False, raise warnings when a file is read that contains metadata about extensions that are not available. Defaults to True.

kwargsdict

Additional keyword arguments passed to lower level functions. These arguments are generally file format-specific. Arguments of note are:

• FITS

  skip_fits_update - bool or None

  DEPRECATED True to skip updating the ASDF tree from the FITS headers, if possible. If None, value will be taken from the environmental SKIP_FITS_UPDATE. Otherwise, the default value is True.

Attributes Summary

crds_observatory	Get the CRDS observatory code for this model.
history	Get the history as a list of entries
override_handle	override_handle identifies in-memory models where a filepath would normally be used.
schema
schema_url	The schema URI to validate the model against.
shape

Methods Summary

add_schema_entry(position, new_schema)	Extend the model's schema by placing the given new_schema at the given dot-separated position in the tree.
clone(target, source[, deepcopy, memo])
close()
copy([memo])	Returns a deep copy of this model.
extend_schema(new_schema)	Extend the model's schema using the given schema, by combining it in an "allOf" array.
find_fits_keyword(keyword[, return_result])	Utility function to find a reference to a FITS keyword in this model's schema.
from_asdf(init[, schema])	Load a data model from an ASDF file.
from_fits(init[, schema])	Load a model from a FITS file.
get_crds_parameters()	Get the parameters used by CRDS to select references for this model.
get_fileext()
get_fits_wcs([hdu_name, hdu_ver, key])	Get a astropy.wcs.WCS object created from the FITS WCS information in the model.
get_primary_array_name()	Returns the name "primary" array for this model, which controls the size of other arrays that are implicitly created.
getarray_noinit(attribute)	Retrieve array but without initilization
info(*args, **kwargs)	Print a rendering of this file's tree to stdout.
items()	Iterates over all of the schema items in a flat way.
keys()	Iterates over all of the schema keys in a flat way.
on_init(init)	Hook used to customize model attributes at the end of __init__.
on_save([path])	This is a hook that is called just before saving the file.
open_asdf([init, ignore_unrecognized_tag])	Open an asdf object from a filename or create a new asdf object
read([init, schema, memmap, ...])
save(path[, dir_path])	Save to either a FITS or ASDF file, depending on the path.
search(*args, **kwargs)	Search this file's tree.
search_schema(substring)	Utility function to search the metadata schema for a particular phrase.
set_fits_wcs(wcs[, hdu_name])	Sets the FITS WCS information on the model using the given astropy.wcs.WCS object.
to_asdf(init, *args, **kwargs)	Write a data model to an ASDF file.
to_fits(init, *args, **kwargs)	Write a data model to a FITS file.
to_flat_dict([include_arrays])	Returns a dictionary of all of the schema items as a flat dictionary.
update(d[, only, extra_fits])	Updates this model with the metadata elements from another model.
validate()	Re-validate the model instance against its schema
values()	Iterates over all of the schema values in a flat way.
write(path, *args, **kwargs)

Attributes Documentation

crds_observatory

Get the CRDS observatory code for this model.

Returns:

str

history

Get the history as a list of entries

override_handle

override_handle identifies in-memory models where a filepath would normally be used.

schema

schema_url = None

The schema URI to validate the model against. If None, only basic validation of required metadata properties (filename, model_type) will occur.

shape

Methods Documentation

add_schema_entry(position, new_schema)

Extend the model’s schema by placing the given new_schema at the given dot-separated position in the tree.

Parameters:

positionstr

Dot separated string indicating the position, e.g. meta.instrument.name.

new_schemadict

Schema tree.

static clone(target, source, deepcopy=False, memo=None)

close()

copy(memo=None)

Returns a deep copy of this model.

extend_schema(new_schema)

Extend the model’s schema using the given schema, by combining it in an “allOf” array.

Parameters:

new_schemadict

Schema tree.

find_fits_keyword(keyword, return_result=True)

Utility function to find a reference to a FITS keyword in this model’s schema. This is intended for interactive use, and not for use within library code.

Parameters:

keywordstr

A FITS keyword name.

Returns:

locationslist of str

If return_result is True, a list of the locations in the schema where this FITS keyword is used. Each element is a dot-separated path.

classmethod from_asdf(init, schema=None, **kwargs)

Load a data model from an ASDF file.

Parameters:

initstr, file object, ~asdf.AsdfFile

• str : file path: initialize from the given file

• readable file object: Initialize from the given file object

• ~asdf.AsdfFile : Initialize from the given`~asdf.AsdfFile`.

schema

Same as for __init__

kwargsdict

Aadditional arguments passed to lower level functions

Returns:

model~jwst.datamodels.DataModel instance

A data model.

classmethod from_fits(init, schema=None, **kwargs)

Load a model from a FITS file.

Parameters:

initfile path, file object, astropy.io.fits.HDUList

• file path: Initialize from the given file

• readable file object: Initialize from the given file object

• astropy.io.fits.HDUList: Initialize from the given ~astropy.io.fits.HDUList.

schemadict, str

Same as for __init__

kwargsdict

Aadditional arguments passed to lower level functions.

Returns:

model~jwst.datamodels.DataModel

A data model.

get_crds_parameters()

Get the parameters used by CRDS to select references for this model.

Returns:

dict

get_fileext()

get_fits_wcs(hdu_name='SCI', hdu_ver=1, key=' ')

Get a astropy.wcs.WCS object created from the FITS WCS information in the model.

Note that modifying the returned WCS object will not modify the data in this model. To update the model, use set_fits_wcs.

Parameters:

hdu_namestr, optional

The name of the HDU to get the WCS from. This must use named HDU’s, not numerical order HDUs. To get the primary HDU, pass 'PRIMARY'.

keystr, optional

The name of a particular WCS transform to use. This may be either ' ' or 'A'-'Z' and corresponds to the "a" part of the CTYPEia cards. key may only be provided if header is also provided.

hdu_ver: int, optional

The extension version. Used when there is more than one extension with the same name. The default value, 1, is the first.

Returns:

wcsastropy.wcs.WCS or pywcs.WCS object

The type will depend on what libraries are installed on this system.

get_primary_array_name()

Returns the name “primary” array for this model, which controls the size of other arrays that are implicitly created. This is intended to be overridden in the subclasses if the primary array’s name is not “data”.

getarray_noinit(attribute)

Retrieve array but without initilization

Arrays initialize when directly referenced if they had not previously been initialized. This circumvents the initialization and instead raises AttributeError.

Parameters:

attributestr

The attribute to retrieve.

Returns:

valueobject

The value of the attribute.

Raises:

AttributeError

If the attribute does not exist.

info(*args, **kwargs)

Print a rendering of this file’s tree to stdout.

Parameters:

max_rowsint, tuple, or None, optional

Maximum number of lines to print. Nodes that cannot be displayed will be elided with a message. If int, constrain total number of displayed lines. If tuple, constrain lines per node at the depth corresponding to the tuple index. If None, display all lines.

max_colsint or None, optional

Maximum length of line to print. Nodes that cannot be fully displayed will be truncated with a message. If int, constrain length of displayed lines. If None, line length is unconstrained.

show_valuesbool, optional

Set to False to disable display of primitive values in the rendered tree.

items()

Iterates over all of the schema items in a flat way.

Each element is a pair (key, value). Each key is a dot-separated name. For example, the schema element meta.observation.date will end up in the result as:

("meta.observation.date": "2012-04-22T03:22:05.432")

keys()

Iterates over all of the schema keys in a flat way.

Each result of the iterator is a key. Each key is a dot-separated name. For example, the schema element meta.observation.date will end up in the result as the string “meta.observation.date”.

on_init(init)

Hook used to customize model attributes at the end of __init__.

Parameters:

initobject

First argument to __init__.

on_save(path=None)

This is a hook that is called just before saving the file. It can be used, for example, to update values in the metadata that are based on the content of the data.

Override it in the subclass to make it do something, but don’t forget to “chain up” to the base class, since it does things there, too.

Parameters:

pathstr

The path to the file that we’re about to save to.

static open_asdf(init=None, ignore_unrecognized_tag=False, **kwargs)

Open an asdf object from a filename or create a new asdf object

read(init=None, schema=None, memmap=False, pass_invalid_values=None, strict_validation=None, validate_on_assignment=None, validate_arrays=False, ignore_missing_extensions=True, **kwargs)

Parameters:

initstr, tuple, ~astropy.io.fits.HDUList, ndarray, dict, None

• None : Create a default data model with no shape.

• tuple : Shape of the data array. Initialize with empty data array with shape specified by the.

• file path: Initialize from the given file (FITS or ASDF)

• readable file object: Initialize from the given file object

• ~astropy.io.fits.HDUList : Initialize from the given ~astropy.io.fits.HDUList.

• A numpy array: Used to initialize the data array

• dict: The object model tree for the data model

schemadict, str (optional)

Tree of objects representing a JSON schema, or string naming a schema. The schema to use to understand the elements on the model. If not provided, the schema associated with this class will be used.

memmapbool

Turn memmap of FITS/ASDF file on or off. (default: False).

pass_invalid_valuesbool or None

If True, values that do not validate the schema will be added to the metadata. If False, they will be set to None. If None, value will be taken from the environmental PASS_INVALID_VALUES. Otherwise the default value is False.

strict_validationbool or None

If True, schema validation errors will generate an exception. If False, they will generate a warning. If None, value will be taken from the environmental STRICT_VALIDATION. Otherwise, the default value is False.

validate_on_assignmentbool or None

Defaults to ‘None’. If None, value will be taken from the environmental VALIDATE_ON_ASSIGNMENT, defaulting to ‘True’ if no environment variable is set. If ‘True’, attribute assignments are validated at the time of assignment. Validation errors generate warnings and values will be set to None. If ‘False’, schema validation occurs only once at the time of write. Validation errors generate warnings.

validate_arraysbool

If True, arrays will be validated against ndim, max_ndim, and datatype validators in the schemas.

ignore_missing_extensionsbool

When False, raise warnings when a file is read that contains metadata about extensions that are not available. Defaults to True.

kwargsdict

Additional keyword arguments passed to lower level functions. These arguments are generally file format-specific. Arguments of note are:

• FITS

  skip_fits_update - bool or None

  DEPRECATED True to skip updating the ASDF tree from the FITS headers, if possible. If None, value will be taken from the environmental SKIP_FITS_UPDATE. Otherwise, the default value is True.

save(path, dir_path=None, *args, **kwargs)

Save to either a FITS or ASDF file, depending on the path.

Parameters:

pathstring or func

File path to save to. If function, it takes one argument with is model.meta.filename and returns the full path string.

dir_path: string

Directory to save to. If not None, this will override any directory information in the path

Returns:

output_path: str

The file path the model was saved in.

search(*args, **kwargs)

Search this file’s tree.

Parameters:

keyNotSet, str, or any other object

Search query that selects nodes by dict key or list index. If NotSet, the node key is unconstrained. If str, the input is searched among keys/indexes as a regular expression pattern. If any other object, node’s key or index must equal the queried key.

type_NotSet, str, or builtins.type

Search query that selects nodes by type. If NotSet, the node type is unconstrained. If str, the input is searched among (fully qualified) node type names as a regular expression pattern. If builtins.type, the node must be an instance of the input.

valueNotSet, str, or any other object

Search query that selects nodes by value. If NotSet, the node value is unconstrained. If str, the input is searched among values as a regular expression pattern. If any other object, node’s value must equal the queried value.

filter_callable

Callable that filters nodes by arbitrary criteria. The callable accepts one or two arguments:

• the node

• the node’s list index or dict key (optional)

and returns True to retain the node, or False to remove it from the search results.

Returns:

asdf.search.AsdfSearchResult

the result of the search

search_schema(substring)

Utility function to search the metadata schema for a particular phrase.

This is intended for interactive use, and not for use within library code.

The searching is case insensitive.

Parameters:

substringstr

The substring to search for.

Returns:

locationslist of tuples

set_fits_wcs(wcs, hdu_name='SCI')

Sets the FITS WCS information on the model using the given astropy.wcs.WCS object.

Note that the “key” of the WCS is stored in the WCS object itself, so it can not be set as a parameter to this method.

Parameters:

wcsastropy.wcs.WCS or pywcs.WCS object

The object containing FITS WCS information

hdu_namestr, optional

The name of the HDU to set the WCS from. This must use named HDU’s, not numerical order HDUs. To set the primary HDU, pass 'PRIMARY'.

to_asdf(init, *args, **kwargs)

Write a data model to an ASDF file.

Parameters:

initfile path or file object

argstuple, list

Additional positional arguments passed to ~asdf.AsdfFile.write_to.

kwargsdict

Any additional keyword arguments are passed along to ~asdf.AsdfFile.write_to.

to_fits(init, *args, **kwargs)

Write a data model to a FITS file.

Parameters:

initfile path or file object

args, kwargs

Any additional arguments are passed along to astropy.io.fits.writeto.

to_flat_dict(include_arrays=True)

Returns a dictionary of all of the schema items as a flat dictionary.

Each dictionary key is a dot-separated name. For example, the schema element meta.observation.date will end up in the dictionary as:

{ "meta.observation.date": "2012-04-22T03:22:05.432" }

update(d, only=None, extra_fits=False)

Updates this model with the metadata elements from another model.

Note: The update method skips a WCS object, if present.

Parameters:

d~jwst.datamodels.DataModel or dictionary-like object

The model to copy the metadata elements from. Can also be a dictionary or dictionary of dictionaries or lists.

only: str, None

Update only the named hdu, e.g. only='PRIMARY'. Can either be a string or list of hdu names. Default is to update all the hdus.

extra_fitsboolean

Update from extra_fits. Default is False.

validate()

Re-validate the model instance against its schema

values()

Iterates over all of the schema values in a flat way.

write(path, *args, **kwargs)