text:
# Specifying the Maximum Amplifier Noise When Driving an ADC

I recently learned an interesting rule of thumb regarding the use of an amplifier to drive the input of an analog to digital converter (ADC). The rule of thumb describes how to specify the maximum allowable noise power of the amplifier [1].

The Problem
Here's the situation for an ADC whose maximum analog input voltage range is –VRef to +VRef. If we drive an ADC's analog input with an sine wave whose peak amplitude is VP = VRef, the ADC's output signal to noise ratio is maximized. We'll call that maximum signal to noise ratio SNRMax. That scenario is shown in Figure 1(a).

To overcome that loss of output signal to noise ratio in Figure 1(b) we can use an amplifier, with a voltage gain of α, to drive the ADC's input to fullscale as shown in Figure 1(c). We'll use the variable SNRWith Amp to represent the ADC output signal to noise ratio in this case. However, we must be cautious! Because we cannot buy an ideal noise-free amplifier at Radio Shack, we're forced to use an amplifier that has some non-zero output noise. In that case, the question becomes, "What is the maximum inherent amplifier noise we can tolerate and still ensure that SNRWith Amp > SNRNo Amp?" And the answer to that question is the point I'm attempting to make in this blog. Please read on.

Just to remind you, the quantization noise power of an b-bit ADC, whose maximum analog input voltage range is –VRef to +VRef, is:

where q is the least significant bit (LSB) voltage range equal to

Equation (1) is based on the assumption that the ADC's input voltage crosses 4 or 5 LSB voltage boundaries, and is not synchronous with the ADC's sample frequency. The derivation of Eq. (1) is readily available on the Internet and in just about every DSP textbook.

ADC Output Signal to Noise Ratio
In the Figure 1(a) case, the ADC's output signal to noise ratio, in decibels, is:

In the Figure 1(b) case, the ADC's output signal to noise ratio is:

In the Figure 1(c) case, the ADC's output signal to noise ratio is:

Because in Figure 1(c) we're driving the ADC to full-scale the numerator of the ratio in SNRWith Amp in Eq. (5) is equal to the numerator of the ratio in SNRMax in Eq. (3). The denominator of the ratio in Eq. (5) is ADC quantization noise power plus the amplifier's output noise power. The term VAmp Noise in Eq. (5) is the RMS of the amplifier's inherent internally-generated noise referred to the input of the amplifier. Thus the term α2 (VAmp Noise)2 is the amplifier's output noise power.

For a given ADC with an input signal that requires amplification by a gain of α, we want to know what is the maximum value of (VAmp Noise)2 so that SNRWith Amp is greater than SNRNo Amp? To answer that question we must compare Eqs. (4) and (5). We can make that comparison by first multiplying Eq. (4)'s numerator and denominator ratios by α2 giving us:

Now we can easily compare Eqs. (5) and (6) because they have identical numerator ratios. So all we have to do to make sure that SNRWith Amp is greater than SNRNo Amp is ensure that the denominator of Eq. (5) is less than the denominator of Eq. (6). That is, we want the following inequality to be satisfied:

Rearranging Eq. (7), we want to ensure that the following inequality is satisfied:

So there we have it. We want the amplifier's internally-generated noise power, referred to the input of the amplifier, to be a factor of (1-1/α2) less than the ADC's q2/12 quantization noise power.

It's instructive to plot the maximum (VAmp Noise)2 in percentage terms of the ADC's q2/12 quantization noise power, as a function of amplifier gain α. We do that in Figure 2.

We interpret Figure 2 as follows: let's say our original analog input signal requires a voltage gain of α = 2 to drive an ADC to full-scale. For a value of α = 2, Figure 2 and Eq. (8) tell us that (VAmp Noise)2 must be no greater than 75% of the ADC's q2/12 quantization noise power.

When I first looked at Figure 2 I noticed that it implied: for larger values of amplifier gain a larger values of (VAmp Noise)2 are acceptable. That means for larger values of a larger values of α2 (VAmp Noise)2 amplifier output noise power are tolerable. This didn't make sense to me until I realized: for larger values of gain a the value of SNRNo Amp will be smaller permitting larger acceptable maximum values for (VAmp Noise)2 as shown in Figure 3.

Conclusion
Given the specifications of an ADC and the necessary gain of an amplifier, Eq. (8) and Figure 2 tell us what must be the maximum amplifier output noise so that using an amplifier improves an ADC's output SNR relative to not using an amplifier. By the way, Reference [2] presents a useful tutorial on amplifier noise.

References
[1] This amplifier noise rule of thumb was taught to me by Prof. Ayman Fayed, ADC guru at Iowa State University.

[2] "Op Amp Noise", MT-047 Tutorial, http://www.analog.com/media/en/training-seminars/tutorials/MT-047.pdf

Previous post by Rick Lyons:
A Remarkable Bit of DFT Trivia
Next post by Rick Lyons:
The DFT Magnitude of a Real-valued Cosine Sequence

[ - ]
Comment by June 9, 2014
"If, on the other hand, we drove an ADC's analog input with an sine wave whose peak amplitude is VP = VRef/?, where ? < 1..."

alpha > 1
[ - ]
Comment by June 14, 2014
Hi abara,
It seems that the second half of you post failed to show up in your comment. I'm not sure what is the point you're trying to make. In any case, if alpha a <1 then we'd need an attenuator preceding the ADC, rather than an amplifier, to avoid overdriving the ADC.
[-Rick-]
[ - ]
Comment by November 1, 2015
Hi Rick,
i think abara meant that there is an error in you text: in your text ther is the sentence as abara has mentioned.It shall be "alpha>1"
[ - ]
Comment by January 17, 2016
Hi r.hemmet. You're right. I have corrected the "typo". Thanks.
[ - ]
Comment by January 17, 2016
A valid analysis. Over the years I have had to think about this in several other ways to satisfy system constraints. 1) Sometimes dither is needed to minimize ADC spurs by randomizing them. This can be just broadband noise or shaped noise as the system requires. 2) Some demodulation schemes work better if the noise floor of the ADC stream has some random noise to it instead of just the harsh quantization noise (esp. Audio demodulation's). So we Analog guys work hard to get the noise to the quantization level, then we are sometimes told to add it right back in to randomize the ADC noise floor! ;)"
[ - ]
Comment by June 14, 2018

Hello Rick,

Thanks!

Ibrahim

[ - ]
Comment by June 14, 2018

Hello Ibrahim. I believe that reference [2] is:

[2] "Op Amp Noise", MT-047 Tutorial, http://www.analog.com/media/en/training-seminars/tutorials/MT-047.pdf

[ - ]
Comment by June 14, 2018
Thank you Rick!

To post reply to a comment, click on the 'reply' button attached to each comment. To post a new comment (not a reply to a comment) check out the 'Write a Comment' tab at the top of the comments.


text:
fiftyone.core.odm.dataset¶

Documents that track datasets and their sample schemas in the database.

Classes:

 DatasetAppConfig(*args, **kwargs) Dataset-specific settings that customize how a dataset is visualized in the App. DatasetDocument(*args, **values) Backing document for datasets. KeypointSkeleton(*args, **kwargs) Description of a keypoint skeleton. SampleFieldDocument(*args, **kwargs) Description of a sample field. SidebarGroupDocument(*args, **kwargs) Description of a sidebar group in the App.

Functions:

 create_field(name, ftype[, …]) Creates the field defined by the given specification.
fiftyone.core.odm.dataset.create_field(name, ftype, embedded_doc_type=None, subfield=None, fields=None, db_field=None, description=None, info=None, **kwargs)

Creates the field defined by the given specification.

Note

This method is used exclusively to create user-defined (non-default) fields. Any parameters accepted here must be stored on SampleFieldDocument or else datasets will “lose” any additional decorations when they are loaded from the database.

Parameters
Returns
class fiftyone.core.odm.dataset.SampleFieldDocument(*args, **kwargs)

Description of a sample field.

Attributes:

 STRICT db_field A unicode string field. description A unicode string field. embedded_doc_type A unicode string field. field_names An ordered tuple of the public fields of this document. fields A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database. ftype A unicode string field. info A dictionary field that wraps a standard Python dictionary. name A unicode string field. subfield A unicode string field.

Methods:

 Hook for doing document level data cleaning (usually validation or assignment) before validation is run. clear_field(field_name) Clears the field from the document. Returns a deep copy of the document. fancy_repr([class_name, select_fields, …]) Generates a customizable string representation of the document. field_to_mongo(field_name) field_to_python(field_name, value) from_dict(d[, extended]) Loads the document from a BSON/JSON dictionary. from_field(field) Creates a SampleFieldDocument for a field. Loads the document from a JSON string. get_field(field_name) Gets the field of the document. Get text score from text query has_field(field_name) Determines whether the document has a field of the given name. Returns an iterator over the (name, value) pairs of the public fields of the document. merge(doc[, merge_lists, merge_dicts, overwrite]) Merges the contents of the given document into this document. set_field(field_name, value[, create, …]) Sets the value of a field of the document. to_dict([extended]) Serializes this document to a BSON/JSON dictionary. Creates the fiftyone.core.fields.Field specified by this document. to_json([pretty_print]) Serializes the document to a JSON string. to_mongo(*args, **kwargs) Return as SON data ready for use with MongoDB. validate([clean]) Ensure that all fields’ values are valid and that required fields are present.

Classes:

 my_metaclass alias of mongoengine.base.metaclasses.DocumentMetaclass
name

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

ftype

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

embedded_doc_type

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

subfield

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

fields

A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

If this field is not set, its default value is [].

Parameters
• field (None) – an optional Field instance describing the type of the list elements

• description (None) – an optional description

• info (None) – an optional info dict

db_field

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

description

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

info

A dictionary field that wraps a standard Python dictionary.

If this field is not set, its default value is {}.

Parameters
• field (None) – an optional Field instance describing the type of the values in the dict

• description (None) – an optional description

• info (None) – an optional info dict

to_field()

Creates the fiftyone.core.fields.Field specified by this document.

Returns
classmethod from_field(field)

Creates a SampleFieldDocument for a field.

Parameters

field – a fiftyone.core.fields.Field instance

Returns
STRICT = False
clean()

Hook for doing document level data cleaning (usually validation or assignment) before validation is run.

Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.

clear_field(field_name)

Clears the field from the document.

Parameters

field_name – the field name

Raises

ValueError – if the field does not exist

copy()

Returns a deep copy of the document.

Returns

a SerializableDocument

fancy_repr(class_name=None, select_fields=None, exclude_fields=None, **kwargs)

Generates a customizable string representation of the document.

Parameters
• class_name (None) – optional class name to use

• select_fields (None) – iterable of field names to restrict to

• exclude_fields (None) – iterable of field names to exclude

• **kwargs – additional key-value pairs to include in the string representation

Returns

a string representation of the document

property field_names

An ordered tuple of the public fields of this document.

field_to_mongo(field_name)
field_to_python(field_name, value)
classmethod from_dict(d, extended=False)

Loads the document from a BSON/JSON dictionary.

Parameters
• d – a dictionary

• extended (False) – whether the input dictionary may contain serialized extended JSON constructs

Returns

a SerializableDocument

classmethod from_json(s)

Loads the document from a JSON string.

Returns

a SerializableDocument

get_field(field_name)

Gets the field of the document.

Parameters

field_name – the field name

Returns

the field value

Raises

AttributeError – if the field does not exist

get_text_score()

Get text score from text query

has_field(field_name)

Determines whether the document has a field of the given name.

Parameters

field_name – the field name

Returns

True/False

iter_fields()

Returns an iterator over the (name, value) pairs of the public fields of the document.

Returns

an iterator that emits (name, value) tuples

merge(doc, merge_lists=True, merge_dicts=True, overwrite=True)

Merges the contents of the given document into this document.

Parameters
• doc – a SerializableDocument of same type as this document

• merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value

• merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value

• overwrite (True) – whether to overwrite (True) or skip (False) existing fields

my_metaclass

alias of mongoengine.base.metaclasses.DocumentMetaclass Methods:

 mro Return a type’s method resolution order.
set_field(field_name, value, create=True, validate=True, dynamic=False)

Sets the value of a field of the document.

Parameters
• field_name – the field name

• value – the field value

• create (True) – whether to create the field if it does not exist

Raises

ValueError – if field_name is not an allowed field name or does not exist and create == False

to_dict(extended=False)

Serializes this document to a BSON/JSON dictionary.

Parameters

extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format

Returns

a dict

to_json(pretty_print=False)

Serializes the document to a JSON string.

Parameters

pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations

Returns

a JSON string

to_mongo(*args, **kwargs)

Return as SON data ready for use with MongoDB.

validate(clean=True)

Ensure that all fields’ values are valid and that required fields are present.

Raises ValidationError if any of the fields’ values are found to be invalid.

class fiftyone.core.odm.dataset.SidebarGroupDocument(*args, **kwargs)

Description of a sidebar group in the App.

Parameters
• name – the name of the sidebar group

• paths ([]) – the list of field or embedded.field.name paths in the group

• expanded (None) – whether this group should be expanded by default

Attributes:

 STRICT expanded A boolean field. field_names An ordered tuple of the public fields of this document. name A unicode string field. paths A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

Methods:

 Hook for doing document level data cleaning (usually validation or assignment) before validation is run. clear_field(field_name) Clears the field from the document. Returns a deep copy of the document. fancy_repr([class_name, select_fields, …]) Generates a customizable string representation of the document. field_to_mongo(field_name) field_to_python(field_name, value) from_dict(d[, extended]) Loads the document from a BSON/JSON dictionary. Loads the document from a JSON string. get_field(field_name) Gets the field of the document. Get text score from text query has_field(field_name) Determines whether the document has a field of the given name. Returns an iterator over the (name, value) pairs of the public fields of the document. merge(doc[, merge_lists, merge_dicts, overwrite]) Merges the contents of the given document into this document. set_field(field_name, value[, create, …]) Sets the value of a field of the document. to_dict([extended]) Serializes this document to a BSON/JSON dictionary. to_json([pretty_print]) Serializes the document to a JSON string. to_mongo(*args, **kwargs) Return as SON data ready for use with MongoDB. validate([clean]) Ensure that all fields’ values are valid and that required fields are present.

Classes:

 my_metaclass alias of mongoengine.base.metaclasses.DocumentMetaclass
name

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

paths

A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

If this field is not set, its default value is [].

Parameters
• field (None) – an optional Field instance describing the type of the list elements

• description (None) – an optional description

• info (None) – an optional info dict

expanded

A boolean field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

STRICT = False
clean()

Hook for doing document level data cleaning (usually validation or assignment) before validation is run.

Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.

clear_field(field_name)

Clears the field from the document.

Parameters

field_name – the field name

Raises

ValueError – if the field does not exist

copy()

Returns a deep copy of the document.

Returns

a SerializableDocument

fancy_repr(class_name=None, select_fields=None, exclude_fields=None, **kwargs)

Generates a customizable string representation of the document.

Parameters
• class_name (None) – optional class name to use

• select_fields (None) – iterable of field names to restrict to

• exclude_fields (None) – iterable of field names to exclude

• **kwargs – additional key-value pairs to include in the string representation

Returns

a string representation of the document

property field_names

An ordered tuple of the public fields of this document.

field_to_mongo(field_name)
field_to_python(field_name, value)
classmethod from_dict(d, extended=False)

Loads the document from a BSON/JSON dictionary.

Parameters
• d – a dictionary

• extended (False) – whether the input dictionary may contain serialized extended JSON constructs

Returns

a SerializableDocument

classmethod from_json(s)

Loads the document from a JSON string.

Returns

a SerializableDocument

get_field(field_name)

Gets the field of the document.

Parameters

field_name – the field name

Returns

the field value

Raises

AttributeError – if the field does not exist

get_text_score()

Get text score from text query

has_field(field_name)

Determines whether the document has a field of the given name.

Parameters

field_name – the field name

Returns

True/False

iter_fields()

Returns an iterator over the (name, value) pairs of the public fields of the document.

Returns

an iterator that emits (name, value) tuples

merge(doc, merge_lists=True, merge_dicts=True, overwrite=True)

Merges the contents of the given document into this document.

Parameters
• doc – a SerializableDocument of same type as this document

• merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value

• merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value

• overwrite (True) – whether to overwrite (True) or skip (False) existing fields

my_metaclass

alias of mongoengine.base.metaclasses.DocumentMetaclass Methods:

 mro Return a type’s method resolution order.
set_field(field_name, value, create=True, validate=True, dynamic=False)

Sets the value of a field of the document.

Parameters
• field_name – the field name

• value – the field value

• create (True) – whether to create the field if it does not exist

Raises

ValueError – if field_name is not an allowed field name or does not exist and create == False

to_dict(extended=False)

Serializes this document to a BSON/JSON dictionary.

Parameters

extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format

Returns

a dict

to_json(pretty_print=False)

Serializes the document to a JSON string.

Parameters

pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations

Returns

a JSON string

to_mongo(*args, **kwargs)

Return as SON data ready for use with MongoDB.

validate(clean=True)

Ensure that all fields’ values are valid and that required fields are present.

Raises ValidationError if any of the fields’ values are found to be invalid.

class fiftyone.core.odm.dataset.KeypointSkeleton(*args, **kwargs)

Description of a keypoint skeleton.

Keypoint skeletons can be associated with fiftyone.core.labels.Keypoint or fiftyone.core.labels.Keypoints fields whose points attributes all contain a fixed number of semantically ordered points.

The edges argument contains lists of integer indexes that define the connectivity of the points in the skeleton, and the optional labels argument defines the label strings for each node in the skeleton.

For example, the skeleton below is defined by edges between the following nodes:

left hand <-> left shoulder <-> right shoulder <-> right hand
left eye <-> right eye <-> mouth

Example:

import fiftyone as fo

# A skeleton for an object made of 7 points
skeleton = fo.KeypointSkeleton(
labels=[
"left hand" "left shoulder", "right shoulder", "right hand",
"left eye", "right eye", "mouth",
],
edges=[[0, 1, 2, 3], [4, 5, 6]],
)

Parameters
• labels (None) – an optional list of label strings for each node

• edges – a list of lists of integer indexes defining the connectivity between nodes

Attributes:

 STRICT edges A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database. field_names An ordered tuple of the public fields of this document. labels A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

Methods:

 Hook for doing document level data cleaning (usually validation or assignment) before validation is run. clear_field(field_name) Clears the field from the document. Returns a deep copy of the document. fancy_repr([class_name, select_fields, …]) Generates a customizable string representation of the document. field_to_mongo(field_name) field_to_python(field_name, value) from_dict(d[, extended]) Loads the document from a BSON/JSON dictionary. Loads the document from a JSON string. get_field(field_name) Gets the field of the document. Get text score from text query has_field(field_name) Determines whether the document has a field of the given name. Returns an iterator over the (name, value) pairs of the public fields of the document. merge(doc[, merge_lists, merge_dicts, overwrite]) Merges the contents of the given document into this document. set_field(field_name, value[, create, …]) Sets the value of a field of the document. to_dict([extended]) Serializes this document to a BSON/JSON dictionary. to_json([pretty_print]) Serializes the document to a JSON string. to_mongo(*args, **kwargs) Return as SON data ready for use with MongoDB. validate([clean]) Ensure that all fields’ values are valid and that required fields are present.

Classes:

 my_metaclass alias of mongoengine.base.metaclasses.DocumentMetaclass
labels

A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

If this field is not set, its default value is [].

Parameters
• field (None) – an optional Field instance describing the type of the list elements

• description (None) – an optional description

• info (None) – an optional info dict

edges

A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

If this field is not set, its default value is [].

Parameters
• field (None) – an optional Field instance describing the type of the list elements

• description (None) – an optional description

• info (None) – an optional info dict

STRICT = False
clean()

Hook for doing document level data cleaning (usually validation or assignment) before validation is run.

Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.

clear_field(field_name)

Clears the field from the document.

Parameters

field_name – the field name

Raises

ValueError – if the field does not exist

copy()

Returns a deep copy of the document.

Returns

a SerializableDocument

fancy_repr(class_name=None, select_fields=None, exclude_fields=None, **kwargs)

Generates a customizable string representation of the document.

Parameters
• class_name (None) – optional class name to use

• select_fields (None) – iterable of field names to restrict to

• exclude_fields (None) – iterable of field names to exclude

• **kwargs – additional key-value pairs to include in the string representation

Returns

a string representation of the document

property field_names

An ordered tuple of the public fields of this document.

field_to_mongo(field_name)
field_to_python(field_name, value)
classmethod from_dict(d, extended=False)

Loads the document from a BSON/JSON dictionary.

Parameters
• d – a dictionary

• extended (False) – whether the input dictionary may contain serialized extended JSON constructs

Returns

a SerializableDocument

classmethod from_json(s)

Loads the document from a JSON string.

Returns

a SerializableDocument

get_field(field_name)

Gets the field of the document.

Parameters

field_name – the field name

Returns

the field value

Raises

AttributeError – if the field does not exist

get_text_score()

Get text score from text query

has_field(field_name)

Determines whether the document has a field of the given name.

Parameters

field_name – the field name

Returns

True/False

iter_fields()

Returns an iterator over the (name, value) pairs of the public fields of the document.

Returns

an iterator that emits (name, value) tuples

merge(doc, merge_lists=True, merge_dicts=True, overwrite=True)

Merges the contents of the given document into this document.

Parameters
• doc – a SerializableDocument of same type as this document

• merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value

• merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value

• overwrite (True) – whether to overwrite (True) or skip (False) existing fields

my_metaclass

alias of mongoengine.base.metaclasses.DocumentMetaclass Methods:

 mro Return a type’s method resolution order.
set_field(field_name, value, create=True, validate=True, dynamic=False)

Sets the value of a field of the document.

Parameters
• field_name – the field name

• value – the field value

• create (True) – whether to create the field if it does not exist

Raises

ValueError – if field_name is not an allowed field name or does not exist and create == False

to_dict(extended=False)

Serializes this document to a BSON/JSON dictionary.

Parameters

extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format

Returns

a dict

to_json(pretty_print=False)

Serializes the document to a JSON string.

Parameters

pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations

Returns

a JSON string

to_mongo(*args, **kwargs)

Return as SON data ready for use with MongoDB.

validate(clean=True)

Ensure that all fields’ values are valid and that required fields are present.

Raises ValidationError if any of the fields’ values are found to be invalid.

class fiftyone.core.odm.dataset.DatasetAppConfig(*args, **kwargs)

Dataset-specific settings that customize how a dataset is visualized in the App.

Parameters
• media_fields (["filepath"]) – the list of sample fields that contain media and should be available to choose from the App’s settings menus

• grid_media_field ("filepath") – the default sample field from which to serve media in the App’s grid view

• modal_media_field ("filepath") – the default sample field from which to serve media in the App’s modal view

• sidebar_mode (None) – an optional default mode for the App sidebar. Supported values are ("all", "best", "fast")

• sidebar_groups (None) – an optional list of SidebarGroupDocument describing sidebar groups to use in the App

• plugins ({}) –

an optional dict mapping plugin names to plugin configuration dicts. Builtin plugins include:

Attributes:

 STRICT field_names An ordered tuple of the public fields of this document. grid_media_field A unicode string field. media_fields A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database. modal_media_field A unicode string field. plugins A dictionary field that wraps a standard Python dictionary. sidebar_groups A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database. sidebar_mode A unicode string field.

Methods:

 Hook for doing document level data cleaning (usually validation or assignment) before validation is run. clear_field(field_name) Clears the field from the document. Returns a deep copy of the document. default_sidebar_groups(sample_collection) Generates the default sidebar_groups for the given collection. fancy_repr([class_name, select_fields, …]) Generates a customizable string representation of the document. field_to_mongo(field_name) field_to_python(field_name, value) from_dict(d[, extended]) Loads the document from a BSON/JSON dictionary. Loads the document from a JSON string. get_field(field_name) Gets the field of the document. Get text score from text query has_field(field_name) Determines whether the document has a field of the given name. Determines whether this app config differs from the default one. Returns an iterator over the (name, value) pairs of the public fields of the document. merge(doc[, merge_lists, merge_dicts, overwrite]) Merges the contents of the given document into this document. set_field(field_name, value[, create, …]) Sets the value of a field of the document. to_dict([extended]) Serializes this document to a BSON/JSON dictionary. to_json([pretty_print]) Serializes the document to a JSON string. to_mongo(*args, **kwargs) Return as SON data ready for use with MongoDB. validate([clean]) Ensure that all fields’ values are valid and that required fields are present.

Classes:

 my_metaclass alias of mongoengine.base.metaclasses.DocumentMetaclass
media_fields

A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

If this field is not set, its default value is [].

Parameters
• field (None) – an optional Field instance describing the type of the list elements

• description (None) – an optional description

• info (None) – an optional info dict

grid_media_field

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

modal_media_field

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

sidebar_mode

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

sidebar_groups

A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

If this field is not set, its default value is [].

Parameters
• field (None) – an optional Field instance describing the type of the list elements

• description (None) – an optional description

• info (None) – an optional info dict

plugins

A dictionary field that wraps a standard Python dictionary.

If this field is not set, its default value is {}.

Parameters
• field (None) – an optional Field instance describing the type of the values in the dict

• description (None) – an optional description

• info (None) – an optional info dict

static default_sidebar_groups(sample_collection)

Generates the default sidebar_groups for the given collection.

Examples:

import fiftyone as fo
import fiftyone.zoo as foz

sidebar_groups = fo.DatasetAppConfig.default_sidebar_groups(dataset)
dataset.app_config.sidebar_groups = sidebar_groups
print(dataset.app_config)

Parameters

sample_collection – a fiftyone.core.collections.SampleCollection

Returns

a list of SidebarGroupDocument instances

is_custom()

Determines whether this app config differs from the default one.

Returns

True/False

STRICT = False
clean()

Hook for doing document level data cleaning (usually validation or assignment) before validation is run.

Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.

clear_field(field_name)

Clears the field from the document.

Parameters

field_name – the field name

Raises

ValueError – if the field does not exist

copy()

Returns a deep copy of the document.

Returns

a SerializableDocument

fancy_repr(class_name=None, select_fields=None, exclude_fields=None, **kwargs)

Generates a customizable string representation of the document.

Parameters
• class_name (None) – optional class name to use

• select_fields (None) – iterable of field names to restrict to

• exclude_fields (None) – iterable of field names to exclude

• **kwargs – additional key-value pairs to include in the string representation

Returns

a string representation of the document

property field_names

An ordered tuple of the public fields of this document.

field_to_mongo(field_name)
field_to_python(field_name, value)
classmethod from_dict(d, extended=False)

Loads the document from a BSON/JSON dictionary.

Parameters
• d – a dictionary

• extended (False) – whether the input dictionary may contain serialized extended JSON constructs

Returns

a SerializableDocument

classmethod from_json(s)

Loads the document from a JSON string.

Returns

a SerializableDocument

get_field(field_name)

Gets the field of the document.

Parameters

field_name – the field name

Returns

the field value

Raises

AttributeError – if the field does not exist

get_text_score()

Get text score from text query

has_field(field_name)

Determines whether the document has a field of the given name.

Parameters

field_name – the field name

Returns

True/False

iter_fields()

Returns an iterator over the (name, value) pairs of the public fields of the document.

Returns

an iterator that emits (name, value) tuples

merge(doc, merge_lists=True, merge_dicts=True, overwrite=True)

Merges the contents of the given document into this document.

Parameters
• doc – a SerializableDocument of same type as this document

• merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value

• merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value

• overwrite (True) – whether to overwrite (True) or skip (False) existing fields

my_metaclass

alias of mongoengine.base.metaclasses.DocumentMetaclass Methods:

 mro Return a type’s method resolution order.
set_field(field_name, value, create=True, validate=True, dynamic=False)

Sets the value of a field of the document.

Parameters
• field_name – the field name

• value – the field value

• create (True) – whether to create the field if it does not exist

Raises

ValueError – if field_name is not an allowed field name or does not exist and create == False

to_dict(extended=False)

Serializes this document to a BSON/JSON dictionary.

Parameters

extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format

Returns

a dict

to_json(pretty_print=False)

Serializes the document to a JSON string.

Parameters

pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations

Returns

a JSON string

to_mongo(*args, **kwargs)

Return as SON data ready for use with MongoDB.

validate(clean=True)

Ensure that all fields’ values are valid and that required fields are present.

Raises ValidationError if any of the fields’ values are found to be invalid.

class fiftyone.core.odm.dataset.DatasetDocument(*args, **values)

Backing document for datasets.

Miscellaneous:

Attributes:

 STRICT annotation_runs A dictionary field that wraps a standard Python dictionary. app_config A field that stores instances of a given type of fiftyone.core.odm.BaseEmbeddedDocument object. brain_methods A dictionary field that wraps a standard Python dictionary. classes A dictionary field that wraps a standard Python dictionary. created_at A datetime field. default_classes A ListField that stores class label strings. default_group_slice A unicode string field. default_mask_targets A DictField that stores mapping between integer keys and string targets. default_skeleton A field that stores instances of a given type of fiftyone.core.odm.BaseEmbeddedDocument object. evaluations A dictionary field that wraps a standard Python dictionary. field_names An ordered tuple of the public fields of this document. frame_collection_name A unicode string field. frame_fields A field that stores a list of a given type of fiftyone.core.odm.BaseEmbeddedDocument objects. group_field A unicode string field. group_media_types A dictionary field that wraps a standard Python dictionary. id A field wrapper around MongoDB’s ObjectIds. in_db Whether the document has been inserted into the database. info A dictionary field that wraps a standard Python dictionary. last_loaded_at A datetime field. mask_targets A dictionary field that wraps a standard Python dictionary. media_type A unicode string field. name A unicode string field. objects([q_obj]) persistent A boolean field. pk Get the primary key. sample_collection_name A unicode string field. sample_fields A field that stores a list of a given type of fiftyone.core.odm.BaseEmbeddedDocument objects. skeletons A dictionary field that wraps a standard Python dictionary. tags A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database. version A unicode string field.

Methods:

 cascade_save(**kwargs) Recursively save any references and generic references on the document. Hook for doing document level data cleaning (usually validation or assignment) before validation is run. clear_field(field_name) Clears the field from the document. Compares the indexes defined in MongoEngine with the ones existing in the database. Returns a deep copy of the document. create_index(keys[, background]) Creates the given indexes if required. delete([signal_kwargs]) Delete the Document from the database. Drops the entire collection associated with this Document type from the database. ensure_index(key_or_list[, background]) Ensure that the given indexes are in place. Checks the document meta data and ensures all the indexes exist. fancy_repr([class_name, select_fields, …]) Generates a customizable string representation of the document. field_to_mongo(field_name) field_to_python(field_name, value) from_dict(d[, extended]) Loads the document from a BSON/JSON dictionary. Loads the document from a JSON string. get_field(field_name) Gets the field of the document. Get text score from text query has_field(field_name) Determines whether the document has a field of the given name. Returns an iterator over the (name, value) pairs of the public fields of the document. Lists all indexes that should be created for the Document collection. merge(doc[, merge_lists, merge_dicts, overwrite]) Merges the contents of the given document into this document. modify([query]) Perform an atomic update of the document in the database and reload the document object using updated version. register_delete_rule(document_cls, …) This method registers the delete rules to apply when removing this object. reload(*fields, **kwargs) Reloads all attributes from the database. save([validate, clean, safe]) Saves the document to the database. select_related([max_depth]) Handles dereferencing of DBRef objects to a maximum depth in order to cut down the number queries to mongodb. set_field(field_name, value[, create, …]) Sets the value of a field of the document. switch_collection(collection_name[, …]) Temporarily switch the collection for a document instance. switch_db(db_alias[, keep_created]) Temporarily switch the database for a document instance. Returns an instance of DBRef useful in __raw__ queries. to_dict([extended]) Serializes this document to a BSON/JSON dictionary. to_json([pretty_print]) Serializes the document to a JSON string. to_mongo(*args, **kwargs) Return as SON data ready for use with MongoDB. update(**kwargs) Performs an update on the Document A convenience wrapper to update(). validate([clean]) Ensure that all fields’ values are valid and that required fields are present.

Classes:

 my_metaclass alias of mongoengine.base.metaclasses.TopLevelDocumentMetaclass
name

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

version

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

created_at

A datetime field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

last_loaded_at

A datetime field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

sample_collection_name

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

frame_collection_name

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

persistent

A boolean field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

media_type

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

group_field

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

group_media_types

A dictionary field that wraps a standard Python dictionary.

If this field is not set, its default value is {}.

Parameters
• field (None) – an optional Field instance describing the type of the values in the dict

• description (None) – an optional description

• info (None) – an optional info dict

default_group_slice

A unicode string field.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

tags

A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

If this field is not set, its default value is [].

Parameters
• field (None) – an optional Field instance describing the type of the list elements

• description (None) – an optional description

• info (None) – an optional info dict

info

A dictionary field that wraps a standard Python dictionary.

If this field is not set, its default value is {}.

Parameters
• field (None) – an optional Field instance describing the type of the values in the dict

• description (None) – an optional description

• info (None) – an optional info dict

app_config

A field that stores instances of a given type of fiftyone.core.odm.BaseEmbeddedDocument object.

Parameters
• document_type – the fiftyone.core.odm.BaseEmbeddedDocument type stored in this field

• description (None) – an optional description

• info (None) – an optional info dict

classes

A dictionary field that wraps a standard Python dictionary.

If this field is not set, its default value is {}.

Parameters
• field (None) – an optional Field instance describing the type of the values in the dict

• description (None) – an optional description

• info (None) – an optional info dict

default_classes

A ListField that stores class label strings.

If this field is not set, its default value is [].

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

mask_targets

A dictionary field that wraps a standard Python dictionary.

If this field is not set, its default value is {}.

Parameters
• field (None) – an optional Field instance describing the type of the values in the dict

• description (None) – an optional description

• info (None) – an optional info dict

default_mask_targets

A DictField that stores mapping between integer keys and string targets.

If this field is not set, its default value is {}.

Parameters
• description (None) – an optional description

• info (None) – an optional info dict

skeletons

A dictionary field that wraps a standard Python dictionary.

If this field is not set, its default value is {}.

Parameters
• field (None) – an optional Field instance describing the type of the values in the dict

• description (None) – an optional description

• info (None) – an optional info dict

default_skeleton

A field that stores instances of a given type of fiftyone.core.odm.BaseEmbeddedDocument object.

Parameters
• document_type – the fiftyone.core.odm.BaseEmbeddedDocument type stored in this field

• description (None) – an optional description

• info (None) – an optional info dict

sample_fields

A field that stores a list of a given type of fiftyone.core.odm.BaseEmbeddedDocument objects.

Parameters
• document_type – the fiftyone.core.odm.BaseEmbeddedDocument type stored in this field

• description (None) – an optional description

• info (None) – an optional info dict

frame_fields

A field that stores a list of a given type of fiftyone.core.odm.BaseEmbeddedDocument objects.

Parameters
• document_type – the fiftyone.core.odm.BaseEmbeddedDocument type stored in this field

• description (None) – an optional description

• info (None) – an optional info dict

annotation_runs

A dictionary field that wraps a standard Python dictionary.

If this field is not set, its default value is {}.

Parameters
• field (None) – an optional Field instance describing the type of the values in the dict

• description (None) – an optional description

• info (None) – an optional info dict

brain_methods

A dictionary field that wraps a standard Python dictionary.

If this field is not set, its default value is {}.

Parameters
• field (None) – an optional Field instance describing the type of the values in the dict

• description (None) – an optional description

• info (None) – an optional info dict

evaluations

A dictionary field that wraps a standard Python dictionary.

If this field is not set, its default value is {}.

Parameters
• field (None) – an optional Field instance describing the type of the values in the dict

• description (None) – an optional description

• info (None) – an optional info dict

exception DoesNotExist

Bases: mongoengine.errors.DoesNotExist

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception MultipleObjectsReturned

Bases: mongoengine.errors.MultipleObjectsReturned

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

STRICT = False
cascade_save(**kwargs)

Recursively save any references and generic references on the document.

clean()

Hook for doing document level data cleaning (usually validation or assignment) before validation is run.

Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.

clear_field(field_name)

Clears the field from the document.

Parameters

field_name – the field name

Raises

ValueError – if the field does not exist

classmethod compare_indexes()

Compares the indexes defined in MongoEngine with the ones existing in the database. Returns any missing/extra indexes.

copy()

Returns a deep copy of the document.

Returns

a SerializableDocument

classmethod create_index(keys, background=False, **kwargs)

Creates the given indexes if required.

Parameters
• keys – a single index key or a list of index keys (to construct a multi-field index); keys may be prefixed with a + or a - to determine the index ordering

• background – Allows index creation in the background

delete(signal_kwargs=None, **write_concern)

Delete the Document from the database. This will only take effect if the document has been previously saved.

Parameters
• signal_kwargs – (optional) kwargs dictionary to be passed to the signal calls.

• write_concern – Extra keyword arguments are passed down which will be used as options for the resultant getLastError command. For example, save(..., w: 2, fsync: True) will wait until at least two servers have recorded the write and will force an fsync on the primary server.

classmethod drop_collection()

Drops the entire collection associated with this Document type from the database.

Raises OperationError if the document has no collection set (i.g. if it is abstract)

classmethod ensure_index(key_or_list, background=False, **kwargs)

Ensure that the given indexes are in place. Deprecated in favour of create_index.

Parameters
• key_or_list – a single index key or a list of index keys (to construct a multi-field index); keys may be prefixed with a + or a - to determine the index ordering

• background – Allows index creation in the background

classmethod ensure_indexes()

Checks the document meta data and ensures all the indexes exist.

Global defaults can be set in the meta - see Defining documents

By default, this will get called automatically upon first interaction with the Document collection (query, save, etc) so unless you disabled auto_create_index, you shouldn’t have to call this manually.

Note

You can disable automatic index creation by setting auto_create_index to False in the documents meta data

fancy_repr(class_name=None, select_fields=None, exclude_fields=None, **kwargs)

Generates a customizable string representation of the document.

Parameters
• class_name (None) – optional class name to use

• select_fields (None) – iterable of field names to restrict to

• exclude_fields (None) – iterable of field names to exclude

• **kwargs – additional key-value pairs to include in the string representation

Returns

a string representation of the document

property field_names

An ordered tuple of the public fields of this document.

field_to_mongo(field_name)
field_to_python(field_name, value)
classmethod from_dict(d, extended=False)

Loads the document from a BSON/JSON dictionary.

Parameters
• d – a dictionary

• extended (False) – whether the input dictionary may contain serialized extended JSON constructs

Returns

a SerializableDocument

classmethod from_json(s)

Loads the document from a JSON string.

Returns

a SerializableDocument

get_field(field_name)

Gets the field of the document.

Parameters

field_name – the field name

Returns

the field value

Raises

AttributeError – if the field does not exist

get_text_score()

Get text score from text query

has_field(field_name)

Determines whether the document has a field of the given name.

Parameters

field_name – the field name

Returns

True/False

id

A field wrapper around MongoDB’s ObjectIds.

property in_db

Whether the document has been inserted into the database.

iter_fields()

Returns an iterator over the (name, value) pairs of the public fields of the document.

Returns

an iterator that emits (name, value) tuples

classmethod list_indexes()

Lists all indexes that should be created for the Document collection. It includes all the indexes from super- and sub-classes.

Note that it will only return the indexes’ fields, not the indexes’ options

merge(doc, merge_lists=True, merge_dicts=True, overwrite=True)

Merges the contents of the given document into this document.

Parameters
• doc – a SerializableDocument of same type as this document

• merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value

• merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value

• overwrite (True) – whether to overwrite (True) or skip (False) existing fields

modify(query=None, **update)

Perform an atomic update of the document in the database and reload the document object using updated version.

Returns True if the document has been updated or False if the document in the database doesn’t match the query.

Note

All unsaved changes that have been made to the document are rejected if the method returns True.

Parameters
• query – the update will be performed only if the document in the database matches the query

• update – Django-style update keyword arguments

my_metaclass

alias of mongoengine.base.metaclasses.TopLevelDocumentMetaclass Methods:

 get_auto_id_names(new_class) Find a name for the automatic ID field for the given new class. mro Return a type’s method resolution order.
objects(q_obj=None, **query) = []
property pk

Get the primary key.

classmethod register_delete_rule(document_cls, field_name, rule)

This method registers the delete rules to apply when removing this object.

reload(*fields, **kwargs)

Reloads all attributes from the database.

Parameters
• fields – (optional) args list of fields to reload

• max_depth – (optional) depth of dereferencing to follow

save(validate=True, clean=True, safe=False, **kwargs)

Saves the document to the database.

If the document already exists, it will be updated, otherwise it will be created.

Parameters
• validate (True) – whether to validate the document

• clean (True) – whether to call the document’s clean() method. Only applicable when validate is True

• safe (False) – whether to reload() the document before raising any validation errors

Returns

self

Handles dereferencing of DBRef objects to a maximum depth in order to cut down the number queries to mongodb.

set_field(field_name, value, create=True, validate=True, dynamic=False)

Sets the value of a field of the document.

Parameters
• field_name – the field name

• value – the field value

• create (True) – whether to create the field if it does not exist

Raises

ValueError – if field_name is not an allowed field name or does not exist and create == False

switch_collection(collection_name, keep_created=True)

Temporarily switch the collection for a document instance.

Only really useful for archiving off data and calling save():

user = User.objects.get(id=user_id)
user.switch_collection('old-users')
user.save()

Parameters
• collection_name (str) – The database alias to use for saving the document

• keep_created (bool) – keep self._created value after switching collection, else is reset to True

Use switch_db if you need to read from another database

switch_db(db_alias, keep_created=True)

Temporarily switch the database for a document instance.

Only really useful for archiving off data and calling save():

user = User.objects.get(id=user_id)
user.switch_db('archive-db')
user.save()

Parameters
• db_alias (str) – The database alias to use for saving the document

• keep_created (bool) – keep self._created value after switching db, else is reset to True

Use switch_collection if you need to read from another collection

to_dbref()

Returns an instance of DBRef useful in __raw__ queries.

to_dict(extended=False)

Serializes this document to a BSON/JSON dictionary.

Parameters

extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format

Returns

a dict

to_json(pretty_print=False)

Serializes the document to a JSON string.

Parameters

pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations

Returns

a JSON string

to_mongo(*args, **kwargs)

Return as SON data ready for use with MongoDB.

update(**kwargs)

Performs an update on the Document A convenience wrapper to update().

Raises OperationError if called on an object that has not yet been saved.

validate(clean=True)

Ensure that all fields’ values are valid and that required fields are present.

Raises ValidationError if any of the fields’ values are found to be invalid.

format: plain


text:
Archives

Convergence Rate of the Glimm Scheme
by Stefano Modena   Stefano Bianchini

Vol. 11 No. 1 (2016) P.235~P.300

ABSTRACT

In this paper we prove that there exists a random sequence $\theta_i$ for the Glimm scheme such that the approximate solution $u^\epsilon(t)$ converges to the exact semigroup solution $S_t \bar u$ of the strictly hyperbolic system of conservation laws \begin{equation*} u_t + f(u)_x = 0, \qquad u(t=0) = \bar u \end{equation*} as follows: for all $T \geq 0$ it holds \begin{equation*} \lim_{\varepsilon \to 0} \frac{\|u^\varepsilon (T) - S_T \bar u\|_1}{\sqrt{\varepsilon } |\log \varepsilon |} = 0. \end{equation*} This result is the extension of the analysis of [8] to the general case, when no assumptions on the flux $f$ are made besides strict hyperbolicity. As a corollary, we obtain a deterministic version of the Glimm scheme for the general system case, extending the analysis of [14].

The analysis requires an extension of the quadratic interaction estimates obtained in [3] in order to analyze interaction occurring during an interval of time.

KEYWORDS
Conservation laws, interaction functionals, Glimm scheme.

MATHEMATICAL SUBJECT CLASSIFICATION 2010
Primary: 35L65.

MILESTONES