Skip to content

minor adjustments to metadata docs #3473

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
petrelharp wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

minor adjustments to metadata docs #3473

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 22 additions & 3 deletions docs/metadata.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,18 @@ For example, setting the generation time to a string will now raise an error:
tables.metadata = {"generation_time": "two of your earth years"}
```

:::{note}
You *cannot directly edit* metadata in an existing `TableCollection`
(or `TreeSequence`): for instance,
`tables.metadata["taxonomy"]["subspecies"] = "lyrata"`
will *silently do nothing*.
(This is because `tables.metadata` returns a copy of the decoded metadata,
rather than a view of the metadata itself.)
Instead, first copy out the metadata (e.g., `md = tables.metadata`);
edit it (e.g., `md["taxonomy"]["species"] = "lyrata"`),
and put it back (`tables.metadata = md`).
:::

:::{note}
Although we have stored the generation time in metadata, the
time *units* of a tree sequence should be stored in the
Expand Down Expand Up @@ -284,8 +296,9 @@ must be encoded and decoded. The C API does not do this, but the Python API will
use the schema to decode the metadata to Python objects.
The encoding for doing this is specified in the top-level schema property `codec`.
Currently the Python API supports the `json` codec which encodes metadata as
[JSON](https://www.json.org/json-en.html), and the `struct` codec which encodes
metadata in an efficient schema-defined binary format using {func}`python:struct.pack` .
[JSON](https://www.json.org/json-en.html), the `struct` codec which encodes
metadata in an efficient schema-defined binary format using {func}`python:struct.pack`,
and the `json+struct` codec which is a combination of the two.

(sec_metadata_codecs_json)=

Expand Down Expand Up @@ -436,6 +449,12 @@ The supported numeric and boolean types are:
- 8
```

In addition to the `binaryFormat` encoding given in the table above,
the `type` key must also be set to the appropriate value.
For boolean values the `type` should be `boolean` (not bool);
for integer binary formats it should be `integer` (not number),
and for floating-point binary formats it should be `number`.

When attempting to pack a non-integer using any of the integer conversion
codes, if the non-integer has a `__index__` method then that method is
called to convert the argument to an integer before packing.
Expand Down Expand Up @@ -602,7 +621,7 @@ into 8-byte alignment; and
(7) the binary data.
The JSON data is encoded as ASCII, without a null terminating byte,
and the format of the binary data is specified using the "struct" portion
of the metadata schema, described :ref:`above <sec_metadata_codecs_struct>`.
of the metadata schema, described {ref}`above <sec_metadata_codecs_struct>`.

(sec_metadata_schema_examples)=

Expand Down
Loading