CLASS ndi.document

 NDI.DOCUMENT - NDI_database storage item, general purpose data and parameter storage
  The ndi.document datatype for storing results in the ndi.database

Superclasses

none

Properties

Property	Description
document_properties	a struct with the fields for the document

Methods

Method	Description
add_dependency_value_n	add a dependency to a named list
add_file	add a file to a ndi.document
current_file_list	return the list of files that have been associated with an ndi.document
dependency	return names and a structure with all dependencies for an ndi.object
dependency_value	return dependency value given dependency name
dependency_value_n	return dependency values from list given dependency name
doc_class	DOC_CLASS what is the document class type of an ndi.document object?
doc_isa	is an ndi.document a member of a particular document_class?
doc_superclass	return the document superclasses of an ndi.document object
doc_unique_id	return the document unique identifier for an ndi.document
document	create a new ndi.database object
eq	are two ndi.document objects equal?
find_doc_by_id	find a doc in an array by ID
find_newest	find the newest document out an array
has_files	ndi.document/has_files is a function.
id	return the document unique identifier for an ndi.document
is_in_file_list	is a file name in a ndi.document's file list?
plus	merge two ndi.document objects
readblankdefinition	read a blank JSON class definitions from a file location string
remove_dependency_value_n	remove a dependency from a named list
remove_file	remove file information from a did.document
reset_file_info	reset the file information parameters for a new did.document
session_id	return the document session unique identifier for an ndi.document
set_dependency_value	set the value of a dependency field
set_session_id	set the session id for an ndi.document object
setproperties	Set property values of an ndi.document object
to_table	convert an ndi.document to a table
validate	0/1 evaluate whether ndi.document object is valid by its schema

Methods help

add_dependency_value_n - add a dependency to a named list

NDI_DOCUMENT_OBJ = ADD_DEPENDENCY_VALUE_N(NDI_DOCUMENT_OBJ, DEPENDENCY_NAME, VALUE, ...)

  Examines the 'depends_on' field (if it is present) for a given NDI_DOCUMENT_OBJ
  and adds a dependency name 'dependency_name_(n+1)', where n is the number of entries with
  the form 'depenency_name_i' that exist presently. If there is no dependency field with that, then
  an entry is added and i is 1.

  This function accepts name/value pairs that alter its default behavior:
  Parameter (default)      | Description
  -----------------------------------------------------------------
  ErrorIfNotFound (1)      | If 1, generate an error if the entry is
                           |   not found. Otherwise, generate no error but take no action.

---

add_file - add a file to a ndi.document

DID_DOCUMENT_OBJ = ADD_FILE(NDI_DOCUMENT_OBJ, NAME, LOCATION, ...)

  Adds a file's information to a ndi.document, for later ingestion into
  the database. NAME is the name of the file record for the document.
  LOCATION is a string that identifies the file or URL location on the
  internet.

  Note: NAME must not include any file separator characters on any
  platform (':','\','/') and may not have leading or trailing spaces.
  Leading or trailing spaces will be trimmed.

  This function accepts name/value pairs that alter its default behavior:
  Parameter (default)      | Description
  -----------------------------------------------------------------
  ingest (1 or 0)          | 0/1 Should the file be copied into the local
                           |   database by ndi.database.add_doc() ?
                           |   If LOCATION does not begin with 'http://' or
                           |   'https://', then ingest is 1 by default.
                           |   If LOCATION begins with 'http(s)://', then
                           |   ingest is 0 by default. Note that the file
                           |   is only copied upon the later call to
                           |   ndi.database.add_doc(), not at the call to
                           |   ndi.document.add_file().
  delete_original (1 or 0) | 0/1 Should we delete the file after ingestion?
                           |   If LOCATION does not begin with 'http://' or
                           |   'https://', then delete_original is 1 by default.
                           |   If LOCATION begins with 'http(s)://', then
                           |   delete_original is 0 by default. Note that the
                           |   file is only deleted upon the later call to
                           |   ndi.database.add_doc(), not at the call to
                           |   ndi.document.add_file().
  location_type ('file',   | Can be 'file', 'url' or 'ndicloud'. By default, it 
    'url' or 'ndicloud')   |   is set to 'file' if LOCATION does not begin with
                           |   'http://', 'https://' or 'ndic://', and 'url' or 
                           |   'ndicloud' otherwise.

---

current_file_list - return the list of files that have been associated with an ndi.document

FL = CURRENT_FILE_LIST(NDI_DOCUMENT_OBJ)

  Return a cell array of file names that are associated with an ndi.document object.

  This list will be a subset of all files possible to add to the document in
  ndi_document_obj.document_properties.file.file_list, and only includes files that have actually
  been added in {ndi_document_obj.document_properties.file.file_info.name}.

---

dependency - return names and a structure with all dependencies for an ndi.object

[NAMES, DEPEND_STRUCT] = DEPENDENCY(NDI_DOCUMENT_OBJ)

  Returns in the cell array NAMES the 'name' of all 'depends_on' entries in the ndi.document NDI_DOCUMENT_OBJ.
  Further, this function returns a structure with all 'name' and 'value' entries in DEPEND_STRUCT.

---

dependency_value - return dependency value given dependency name

D = DEPENDENCY_VALUE(NDI_DOCUMENT_OBJ, DEPENDENCY_NAME, ...)

  Examines the 'depends_on' field (if it is present) for a given NDI_DOCUMENT_OBJ
  and returns the 'value' associated with the given 'name'. If there is no such
  field (either 'depends_on' or 'name'), then D is empty and an error is generated.

  This function accepts name/value pairs that alter its default behavior:
  Parameter (default)      | Description
  -----------------------------------------------------------------
  ErrorIfNotFound (1)      | If 1, generate an error if the entry is
                           |   not found. Otherwise, return empty.

---

dependency_value_n - return dependency values from list given dependency name

D = DEPENDENCY_VALUE_N(NDI_DOCUMENT_OBJ, DEPENDENCY_NAME, ...)

  Examines the 'depends_on' field (if it is present) for a given NDI_DOCUMENT_OBJ
  and returns the 'values' associated with the given 'name_i', where i varies from 1 to the
  maximum number of entries titled 'name_i'. If there is no such field (either
  'depends_on' or 'name_i'), then D is empty and an error is generated.

  This function accepts name/value pairs that alter its default behavior:
  Parameter (default)      | Description
  -----------------------------------------------------------------
  ErrorIfNotFound (1)      | If 1, generate an error if the entry is
                           |   not found. Otherwise, return empty.

---

doc_class - DOC_CLASS what is the document class type of an ndi.document object?

C = DOC_CLASS(NDI_DOCUMENT_OBJ)

  Returns the document class of an ndi.document.
  (Found at ndi_document_obj.document_properties.document_class.class_name)

---

doc_isa - is an ndi.document a member of a particular document_class?

B = DOC_ISA(NDI_DOCUMENT_OBJ, DOCUMENT_CLASS)

  Returns 1 if NDI_DOCUMENT_OBJ or one of its superclasses is a match
  for DOCUMENT_CLASS. Otherwise returns 0.

---

doc_superclass - return the document superclasses of an ndi.document object

SC = DOC_SUPERCLASS(NDI_DOCUMENT_OBJ)

  Returns the document superclasses of an ndi.document object. SC is a cell
  array of strings.

---

doc_unique_id - return the document unique identifier for an ndi.document

UID = DOC_UNIQUE_ID(NDI_DOCUMENT_OBJ)

  Returns the unique id of an ndi.document
  (Found at NDI_DOCUMENT_OBJ.documentproperties.base.id)

---

document - create a new ndi.database object

NDI_DOCUMENT_OBJ = ndi.document(DOCUMENT_TYPE, 'PARAM1', VALUE1, ...)
    or
  NDI_DOCUMENT_OBJ = ndi.document(MATLAB_STRUCT)

    Documentation for ndi.document/document
       doc ndi.document

---

eq - are two ndi.document objects equal?

B = EQ(NDI_DOCUMENT_OBJ1, NDI_DOCUMENT_OBJ2)

  Returns 1 if and only if the objects have identical document_properties.base.id
  fields.

---

find_doc_by_id - find a doc in an array by ID

[D,I] = FIND_DOC_BY_ID(DOCARRAY, ID)

  Given a cell array of ndi.document objects and an
  ID, return the document D that matches and its
  index I in DOCARRAY.

  If no document matches, empty is returned for D, I.

---

find_newest - find the newest document out an array

[D,I,T] = FIND_NEWEST(DOCARRAY)

  Find the newest document among an array of ndi.document objects.

  The newest document is returned in D, along with the index I.
  T is the datestamp of each document as a datetime object.

---

has_files - ndi.document/has_files is a function.

tf = has_files(ndi_document_obj)

---

id - return the document unique identifier for an ndi.document

UID = ID (NDI_DOCUMENT_OBJ)

  Returns the unique id of an ndi.document
  (Found at NDI_DOCUMENT_OBJ.documentproperties.base.id)

---

is_in_file_list - is a file name in a ndi.document's file list?

[B, MSG, FI_INDEX] = IS_IN_FILE_LIST(NDI_DOCUMENT_OBJ, NAME)

  Is the file NAME a valid named binary file for the ndi.document
  NDI_DOCUMENT_OBJ? If so, B is 1; else, B is 0.

  A name is a valid name if it appears in NDI_DOCUMENT_OBJ....
  document_properties.files.file_list or if it is a numbered
  file with an entry in document_properties.files.file_list
  as 'filename.ext_#'. (For example, 'filename.ext_1' would
  be valid if 'filename.ext_# is in the file_list.)

  If the file NAME is not valid, a reason is returned in MSG.

  If it is a valid file NAME, then the index value of NAME
  in NDI_DOCUMENT_OBJ.DOCUMENT_PROPERTIES.FILES.FILE_INFO is also
  returned.

---

plus - merge two ndi.document objects

NDI_DOCUMENT_OBJ_OUT = PLUS(NDI_DOCUMENT_OBJ_A, NDI_DOCUMENT_OBJ_B)

  Merges the ndi.document objects A and B. First, the 'document_class'
  superclasses are merged. Then, the fields that are in B but are not in A
  are added to A. The result is returned in NDI_DOCUMENT_OBJ_OUT.
  Note that any fields that A has that are also in B will be preserved; no elements of
  those fields of B will be combined with A.

---

readblankdefinition - read a blank JSON class definitions from a file location string

S = READBLANKDEFINITION(JSONFILELOCATIONSTRING)

  Given a JSONFILELOCATIONSTRING, this function creates a blank document using the JSON definitions.

  A JSONFILELOCATIONSTRING can be:
     a) a url
     b) a filename (full path)
        c) a filename referenced with respect to $NDIDOCUMENTPATH

  See also: DID.DOCUMENT.READJSONFILELOCATION

---

remove_dependency_value_n - remove a dependency from a named list

NDI_DOCUMENT_OBJ = REMOVE_DEPENDENCY_VALUE_N(NDI_DOCUMENT_OBJ, DEPENDENCY_NAME, VALUE, N, ...)

  Examines the 'depends_on' field (if it is present) for a given NDI_DOCUMENT_OBJ
  and removes the dependency name 'dependency_name_(n)'.

  This function accepts name/value pairs that alter its default behavior:
  Parameter (default)      | Description
  -----------------------------------------------------------------
  ErrorIfNotFound (1)      | If 1, generate an error if the entry is
                           |   not found. Otherwise, generate no error but take no action.

---

remove_file - remove file information from a did.document

DID_DOCUMENT_OBJ = REMOVE_FILE(NDI_DOCUMENT_OBJ, NAME, [LOCATION], ...)

  Removes the file information for a name or a name and location
  combination from a did.document() object.

  If LOCATION is not specified or is empty, then all locations are removed.

  If NDI_DOCUMENT_OBJ does not have a file NAME in its file_list, then an error is
  generated.

  This function accepts name/value pairs that alter its default behavior:
  Parameter (default)      | Description
  -----------------------------------------------------------------
  ErrorIfNoFileInfo (0)    | 0/1 If a name is specified and the
                           |   file info is already empty, should we
                           |   produce an error?

---

reset_file_info - reset the file information parameters for a new did.document

NDI_DOCUMENT_OBJ = RESET_FILE_INFO(NDI_DOCUMENT_OBJ)

  Reset (make empty) all file info structures for a new did.document object.

  Sets document_properties.files.file_info to an empty structure

---

session_id - return the document session unique identifier for an ndi.document

UID = SESSION_ID (NDI_DOCUMENT_OBJ)

  Returns the unique session id of an ndi.document
  (Found at NDI_DOCUMENT_OBJ.documentproperties.base.session_id)

---

set_dependency_value - set the value of a dependency field

NDI_DOCUMENT_OBJ = SET_DEPENDENCY_VALUE(NDI_DOCUMENT_OBJ, DEPENDENCY_NAME, VALUE, ...)

  Examines the 'depends_on' field (if it is present) for a given NDI_DOCUMENT_OBJ
  and, if there is a dependency with a given 'dependency_name', then the value of the
  dependency is set to DEPENDENCY_VALUE.

  This function accepts name/value pairs that alter its default behavior:
  Parameter (default)      | Description
  -----------------------------------------------------------------
  ErrorIfNotFound (1)      | If 1, generate an error if the entry is
                           |   not found. Otherwise, add it.

---

set_session_id - set the session id for an ndi.document object

NDI_DOCUMENT_OBJ = SET_SESSION_ID(NDI_DOCUMENT_OBJ, SESSION_ID)

  Sets the document_properties.base.session_id field to the value indicated.

---

setproperties - Set property values of an ndi.document object

NDI_DOCUMENT_OBJ = SETPROPERTIES(NDI_DOCUMENT_OBJ, 'PROPERTY1', VALUE1, ...)

  Sets the property values of NDI_DOCUMENT_OBJ.    PROPERTY values should be expressed
  relative to NDI_DOCUMENT_OBJ.document_properties (see example).

  See also: ndi.document, ndi.document/ndi.document

  Example:
    mydoc = mydoc.setproperties('base.name','mydoc name');

---

to_table - convert an ndi.document to a table

T = TO_TABLE(NDI_DOCUMENT_OBJ)

  Convert an ndi.document to a Matlab table.

  Field names are converted to table variable names. If
  there are substructures, then the variable names
  have a 'dot' indicating the substructure.

  'depends_on' elements are given their own names.
  Each dependency has a 'depends_on_NAME' variable name
  and the value is the dependency value.

---

validate - 0/1 evaluate whether ndi.document object is valid by its schema

B = VALIDATE(NDI_DOCUMENT_OBJ)

  Checks the fields of the ndi.document object against the schema in
  NDI_DOCUMENT_OBJ.ndi_core_properties.validation_schema and returns 1
  if the object is valid and 0 otherwise.

---