moseq2-common 1.5.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,49 @@
1
+ # Non-Commercial Research and Academic Use Software License and Terms of Use
2
+
3
+
4
+ MoSeq is a software package that includes original code created by the Harvard researchers listed below (the “Software”), and third-party code that may be obtained by End Users separately. The Software is designed to label behaviors identified from 3D pose dynamics data through the use of computational modeling and fitting approaches. The Software was developed by Alexander Wiltschko, Ph.D., Sandeep Robert Datta, Ph.D., and Matthew J. Johnson, Ph.D. at Harvard University. It is distributed for free academic and non-commercial research use by the President and Fellows of Harvard College (“Harvard”).
5
+
6
+ Using the Software indicates your agreement to be bound by the terms of this Software Use Agreement (“Agreement”). Absent your agreement to the terms below, you (the “End User”) have no rights to hold or use the Software whatsoever.
7
+
8
+ Harvard agrees to grant hereunder a limited non-exclusive license to End User for the use of the Software in the performance of End User’s internal, non-commercial research and academic use at End User’s academic or not-for-profit research institution (“Institution”) on the following terms and conditions:
9
+
10
+ 1. **NO COMMERCIAL USE.** End User shall not use the Software for Commercial use and any such use of the Software is expressly prohibited. “Commercial use” includes, but is not limited to, (i) use of the Software in fee-for-service arrangements, (ii) use of the Software by core facilities or laboratories to provide research services to (or in collaboration with) for-profit third parties for a fee, and (iii) use of the Software in industry-sponsored and/or collaborative research projects in which any commercial rights are granted to the sponsor or collaborator. If End User wishes to use the Software for Commercial use, End User must execute a separate license agreement with Harvard.
11
+
12
+ _Requests for use of the Software for Commercial use, please contact:_
13
+
14
+ Office of Technology Development
15
+ Harvard University
16
+ Smith Campus Center, Suite 727E
17
+ 1350 Massachusetts Avenue Cambridge, MA 02138 USA Telephone: (617) 495-3067
18
+ Facsimile: (617) 495-9568
19
+ E-mail: otd@harvard.edu
20
+
21
+ 2. **OWNERSHIP AND COPYRIGHT NOTICE.** Harvard owns all intellectual property in the Software. End User shall gain no ownership to the Software. End User shall not remove or delete, and shall retain in the Software (including in any modifications to the Software and in any Derivative Works), the copyright, trademark, or other notices pertaining to Software as provided with the Software.
22
+
23
+ 3. **DERIVATIVE WORKS.** End User may create use and distribute Derivative Works, as such term is defined under U.S. copyright laws, provided that any such Derivative Works shall be restricted to non-commercial research and academic use. End User may not distribute Derivative Works to any for-profit third parties for Commercial use.
24
+
25
+ 4. **FEEDBACK.** In order to improve the Software, comments from End Users may be useful. End User agrees to provide Harvard with feedback on the End User’s use of the Software (e.g., any bugs in the Software, the user experience, etc.). Harvard is permitted to use such information provided by End User in making changes and improvements to the Software without compensation or accounting to End User.
26
+
27
+ 5. **NON ASSERT.** End User acknowledges that Harvard may develop modifications to the Software that may be based on the feedback provided by End User under Section 5 above. Harvard shall not be restricted in any way by End User regarding its use of such information. End User acknowledges the right of Harvard to prepare, publish, display, reproduce, transmit and or use modifications to the Software that may be substantially similar or functionally equivalent to End User’s modifications and/or improvements if any. In the event that End User obtains patent protection for any modification or improvement to Software, End User agrees not to allege or enjoin infringement of End User’s patent against Harvard, or any of the researchers, medical or research staff, officers, directors and employees of those institutions.
28
+
29
+ 6. **PUBLICATION & ATTRIBUTION.** End User has the right to publish, present, or share results from the use of the Software. In accordance with customary academic practice, End User will acknowledge Harvard as the provider of the Software and may cite the relevant reference(s) from the following list of publications:
30
+
31
+ Wiltschko AB, Johnson MJ, Iurilli G, Peterson RE, Katon JE, Pashkovski SL, Abraira VE, Adams RP and Datta SR. (2015). Mapping sub-second Structure in Behavior. Neuron, 88:1121.
32
+
33
+ Markowitz JE, Gillis WF, Beron CC, Neufeld SQ, Robertson K, Bhagat ND, Peterson RE, Peterson E, Hyun M, Linderman SW, Sabatini BL and Datta SR. (2018). The striatum organizes 3D behavior via moment-to-moment action selection. Cell, in press.
34
+
35
+ 7.** NO WARRANTIES.** THE SOFTWARE IS PROVIDED "AS IS." TO THE FULLEST EXTENT PERMITTED BY LAW, HARVARD HEREBY DISCLAIMS ALL WARRANTIES OF ANY KIND (EXPRESS, IMPLIED OR OTHERWISE) REGARDING THE SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OWNERSHIP, AND NON-INFRINGEMENT. HARVARD MAKES NO WARRANTY ABOUT THE ACCURACY, RELIABILITY, COMPLETENESS, TIMELINESS, SUFFICIENCY OR QUALITY OF THE SOFTWARE. HARVARD DOES NOT WARRANT THAT THE SOFTWARE WILL OPERATE WITHOUT ERROR OR INTERRUPTION.
36
+
37
+ 8. **LIMITATIONS OF LIABILITY AND REMEDIES.** USE OF THE SOFTWARE IS AT END USER’S OWN RISK. IF END USER IS DISSATISFIED WITH THE SOFTWARE, ITS EXCLUSIVE REMEDY IS TO STOP USING IT. IN NO EVENT SHALL HARVARD BE LIABLE TO END USER OR ITS INSTITUTION, IN CONTRACT, TORT OR OTHERWISE, FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR OTHER DAMAGES OF ANY KIND WHATSOEVER ARISING OUT OF OR IN CONNECTION WITH THE SOFTWARE, EVEN IF HARVARD IS NEGLIGENT OR OTHERWISE AT FAULT, AND REGARDLESS OF WHETHER HARVARD IS ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
38
+
39
+ 9. **INDEMNIFICATION.** To the extent permitted by law, End User shall indemnify, defend and hold harmless Harvard, their corporate affiliates, current or future directors, trustees, officers, faculty, medical and professional staff, employees, students and agents and their respective successors, heirs and assigns (the "Indemnitees"), against any liability, damage, loss or expense (including reasonable attorney's fees and expenses of litigation) incurred by or imposed upon the Indemnitees or any one of them in connection with any claims, suits, actions, demands or judgments arising from End User’s breach of this Agreement or its Institution’s use of the Software except to the extent caused by the gross negligence or willful misconduct of Harvard. This indemnification provision shall survive expiration or termination of this Agreement.
40
+
41
+ 10. **GOVERNING LAW.** This Agreement shall be construed and governed by the laws of the Commonwealth of Massachusetts regardless of otherwise applicable choice of law standards.
42
+
43
+ 11. **NON-USE OF NAME.** Nothing in this License and Terms of Use shall be construed as granting End Users or their Institutions any rights or licenses to use any trademarks, service marks or logos associated with the Software. End User may not use the terms “Harvard” (or a substantially similar term) in any way that is inconsistent with the permitted uses described herein. End Users may not use any name or emblem of Harvard or any of its schools or subdivisions for any purpose, or to falsely suggest any relationship between End User (or its Institution) and Harvard, or in any manner that would infringe or violate any of its rights.
44
+
45
+ 12. End User represents and warrants that it has the legal authority to enter into this License and Terms of Use on behalf of itself and its Institution.
46
+
47
+ ***
48
+
49
+
@@ -0,0 +1,34 @@
1
+ Metadata-Version: 2.4
2
+ Name: moseq2-common
3
+ Version: 1.5.0
4
+ Summary: Code shared by the MoSeq2 packages.
5
+ Author: Datta Lab
6
+ License-Expression: LicenseRef-Harvard-Academic-Non-Commercial
7
+ License-File: LICENSE.md
8
+ Classifier: Development Status :: 5 - Production/Stable
9
+ Classifier: Intended Audience :: Science/Research
10
+ Classifier: Operating System :: OS Independent
11
+ Classifier: Programming Language :: Python :: 3.10
12
+ Classifier: Programming Language :: Python :: 3.11
13
+ Classifier: Programming Language :: Python :: 3.12
14
+ Classifier: Programming Language :: Python :: 3.13
15
+ Classifier: Programming Language :: Python :: 3.14
16
+ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
17
+ Requires-Python: >=3.10
18
+ Requires-Dist: numpy>=2.2.6
19
+ Requires-Dist: ruamel.yaml>=0.19.1
20
+ Description-Content-Type: text/markdown
21
+
22
+ # moseq2-common
23
+
24
+ Code shared by the MoSeq2 packages (`moseq2-app`, `moseq2-extract`,
25
+ `moseq2-pca`, `moseq2-model` and `moseq2-viz`), kept in one place so a fix
26
+ lands once. It is installed with them and has nothing to use on its own.
27
+ Install the pipeline with:
28
+
29
+ ```bash
30
+ python -m pip install moseq2-app
31
+ ```
32
+
33
+ [The installation guide](https://github.com/dattalab/moseq2-app/wiki/MoSeq2-Installation)
34
+ carries the whole procedure.
@@ -0,0 +1,13 @@
1
+ # moseq2-common
2
+
3
+ Code shared by the MoSeq2 packages (`moseq2-app`, `moseq2-extract`,
4
+ `moseq2-pca`, `moseq2-model` and `moseq2-viz`), kept in one place so a fix
5
+ lands once. It is installed with them and has nothing to use on its own.
6
+ Install the pipeline with:
7
+
8
+ ```bash
9
+ python -m pip install moseq2-app
10
+ ```
11
+
12
+ [The installation guide](https://github.com/dattalab/moseq2-app/wiki/MoSeq2-Installation)
13
+ carries the whole procedure.
@@ -0,0 +1 @@
1
+ __version__ = "1.5.0"
@@ -0,0 +1,213 @@
1
+ """YAML reading and writing, in one place.
2
+
3
+ ``ruamel.yaml`` removed the module-level ``safe_load``/``safe_dump`` functions in
4
+ 0.18 in favour of instantiating a parser. Routing every call in the MoSeq2
5
+ packages through here keeps that detail, and the format every file is written
6
+ in, in one file rather than at each of the call sites.
7
+
8
+ The parser stays ``ruamel``, deliberately. ``ruamel``'s safe loader is YAML 1.2;
9
+ PyYAML is YAML 1.1 and reads unquoted ``yes``/``no``/``on``/``off`` as booleans
10
+ and ``06:00:00`` as a sexagesimal integer. moseq2 config and index files contain
11
+ both shapes -- moseq2-model's ``wall_time: 06:00:00`` is interpolated straight
12
+ into an ``sbatch -t`` argument by ``util.get_parameter_strings``, so it must stay
13
+ a string -- and switching parsers would quietly change how existing user files
14
+ are read.
15
+
16
+ Two things the safe writer cannot do on its own are handled here. numpy values
17
+ (a kappa read from a model, a syllable id from ``np.unique``) are written as the
18
+ plain Python value they hold; the safe representer refuses every numpy type.
19
+ And nothing is written until the whole document has serialized, so a value that
20
+ cannot be written leaves the file it was meant to replace as it was.
21
+ """
22
+
23
+ import io
24
+ import reprlib
25
+
26
+ import numpy as np
27
+ from ruamel.yaml import YAML
28
+ from ruamel.yaml.representer import RepresenterError
29
+
30
+ __all__ = ["UnwritableValueError", "dump_yaml", "read_yaml", "write_yaml"]
31
+
32
+ _ADVICE = (
33
+ "If you set this value, change it to text, a number, true/false, a list or a "
34
+ "dictionary and run the step again; if MoSeq2 set it, please report this message "
35
+ "at https://github.com/dattalab/moseq2-app/issues."
36
+ )
37
+
38
+
39
+ class UnwritableValueError(RepresenterError):
40
+ """A value in the data has no YAML form, so nothing was written.
41
+
42
+ A ``RepresenterError``, so code that caught the safe writer's own error
43
+ catches this one too.
44
+
45
+ Attributes:
46
+ key_path: the keys and list indices leading from the top of the data to
47
+ the value (for a key, to the mapping that holds it).
48
+ value: the value (or key) that cannot be written.
49
+ """
50
+
51
+ def __init__(self, message, key_path, value):
52
+ super().__init__(message)
53
+ self.key_path = tuple(key_path)
54
+ self.value = value
55
+
56
+
57
+ def _parser():
58
+ """A YAML parser configured the way ``safe_dump`` was.
59
+
60
+ A new one per call, because a ``YAML`` instance carries a serializer across
61
+ calls: if a value cannot be represented, the failed call leaves that
62
+ serializer open and every later dump writes nothing at all, silently.
63
+ Callers across the packages move their output over a file the user already
64
+ has, so a dumper that quietly produces nothing destroys data.
65
+
66
+ ``pure=True`` selects the Python implementation, matching what the
67
+ module-level functions used.
68
+
69
+ The two assignments restore emitter behaviour that ``YAML()`` does not
70
+ share with ``safe_dump``. ``allow_unicode`` escapes non-ASCII rather than
71
+ writing it literally, which also keeps a write from depending on the
72
+ locale encoding of the file handle. ``width`` is 80 in both, but the two
73
+ versions measure the column at which a flow sequence may break two
74
+ characters apart, so 82 here reproduces where ``safe_dump`` put its line
75
+ breaks -- both for the two-element ``path: [x.h5, x.yaml]`` entries that
76
+ fill an index file and for sequences long enough to wrap.
77
+
78
+ One emitter difference is left, and no configuration reaches it: where a
79
+ flow sequence does wrap, this version writes a space before the break. The
80
+ breaks land in the same places, so the files moseq2 writes -- indexes,
81
+ session results, configs, the PCA parameter yaml, crowd-movie info -- come
82
+ out byte for byte as they did.
83
+ """
84
+ parser = YAML(typ="safe", pure=True)
85
+ parser.allow_unicode = False
86
+ parser.width = 82
87
+ return parser
88
+
89
+
90
+ def _plain(value):
91
+ """``value`` with every numpy scalar and array replaced by its plain value.
92
+
93
+ Follows ``keypoint_moseq.io._plain``, with two differences. Dict keys are
94
+ converted too, since syllable ids from ``np.unique`` end up as keys. And
95
+ only exact ``dict``, ``list`` and ``tuple`` are walked, so a container the
96
+ safe writer refuses (a ``defaultdict``) still raises, and an
97
+ ``OrderedDict`` still writes as ``!!omap``. A tuple becomes a list, which
98
+ is how the safe writer writes one anyway, except as a dict key, where it
99
+ stays a tuple so it can still be a key. The input is never changed.
100
+ """
101
+ kind = type(value)
102
+ if kind is dict:
103
+ return {_plain_key(k): _plain(v) for k, v in value.items()}
104
+ if kind is list or kind is tuple:
105
+ return [_plain(item) for item in value]
106
+ if isinstance(value, (np.generic, np.ndarray)):
107
+ return value.tolist()
108
+ return value
109
+
110
+
111
+ def _plain_key(key):
112
+ if type(key) is tuple:
113
+ return tuple(_plain_key(item) for item in key)
114
+ return _plain(key)
115
+
116
+
117
+ def _writable(value):
118
+ try:
119
+ _parser().dump(value, io.StringIO())
120
+ except RepresenterError:
121
+ return False
122
+ return True
123
+
124
+
125
+ def _find_unwritable(data, key_path=()):
126
+ """``(key_path, value, is_key)`` for the first thing the safe writer refuses.
127
+
128
+ Depth first, in iteration order. Runs only after a dump has failed, so its
129
+ cost does not matter.
130
+ """
131
+ if isinstance(data, dict):
132
+ for key, value in data.items():
133
+ if not _writable(key):
134
+ return key_path, key, True
135
+ found = _find_unwritable(value, key_path + (key,))
136
+ if found:
137
+ return found
138
+ elif isinstance(data, (list, tuple)):
139
+ for index, value in enumerate(data):
140
+ found = _find_unwritable(value, key_path + (index,))
141
+ if found:
142
+ return found
143
+ return None if _writable(data) else (key_path, data, False)
144
+
145
+
146
+ def _type_name(value):
147
+ kind = type(value)
148
+ if kind.__module__ == "builtins":
149
+ return kind.__qualname__
150
+ return f"{kind.__module__}.{kind.__qualname__}"
151
+
152
+
153
+ def _serialize(data, target, kind):
154
+ """The whole YAML document for ``data``, or ``UnwritableValueError``.
155
+
156
+ ``kind`` is ``"file"``, ``"stream"`` or ``"string"``; with ``target``, it
157
+ decides how the error names what was being written.
158
+ """
159
+ plain = _plain(data)
160
+ buffer = io.StringIO()
161
+ try:
162
+ _parser().dump(plain, buffer)
163
+ except RepresenterError as err:
164
+ found = _find_unwritable(plain)
165
+ if found is None:
166
+ raise
167
+ key_path, value, is_key = found
168
+ where = "".join(f"[{k!r}]" for k in key_path) or "the top level"
169
+ location = f"a key in the mapping at {where}" if is_key else f"the value at {where}"
170
+ core = (
171
+ f"{location} is {reprlib.repr(value)}, of type {_type_name(value)}, "
172
+ "which a YAML file cannot hold."
173
+ )
174
+ if kind == "file":
175
+ message = f"Cannot save {target}: {core} {target} was left as it was. {_ADVICE}"
176
+ elif kind == "stream":
177
+ message = f"Cannot write YAML to {target}: {core} Nothing was written to it. {_ADVICE}"
178
+ else:
179
+ message = f"Cannot write this data as YAML: {core} {_ADVICE}"
180
+ raise UnwritableValueError(message, key_path, value) from err
181
+ return buffer.getvalue()
182
+
183
+
184
+ def read_yaml(path_or_stream):
185
+ """Parse a YAML file, given a path or an open stream."""
186
+ if hasattr(path_or_stream, "read"):
187
+ return _parser().load(path_or_stream)
188
+ with open(path_or_stream, "r") as handle:
189
+ return _parser().load(handle)
190
+
191
+
192
+ def write_yaml(data, path_or_stream):
193
+ """Write ``data`` as YAML, given a path or an open stream.
194
+
195
+ The whole document is serialized before anything is written, so a value
196
+ that cannot be written raises ``UnwritableValueError`` with the file (or
197
+ stream) exactly as it was. A path is then opened in text mode, so each
198
+ platform keeps the line endings the packages have always written, and
199
+ written in place rather than replaced, so a symlinked file stays a symlink
200
+ and keeps its permissions.
201
+ """
202
+ if hasattr(path_or_stream, "write"):
203
+ name = getattr(path_or_stream, "name", "the output stream")
204
+ path_or_stream.write(_serialize(data, name, "stream"))
205
+ return
206
+ text = _serialize(data, path_or_stream, "file")
207
+ with open(path_or_stream, "w") as handle:
208
+ handle.write(text)
209
+
210
+
211
+ def dump_yaml(data):
212
+ """Serialize ``data`` to a YAML string."""
213
+ return _serialize(data, None, "string")
@@ -0,0 +1,39 @@
1
+ [tool.pdm.version]
2
+ source = "file"
3
+ path = "moseq2_common/__init__.py"
4
+
5
+ [project]
6
+ name = "moseq2-common"
7
+ dynamic = []
8
+ description = "Code shared by the MoSeq2 packages."
9
+ readme = "README.md"
10
+ authors = [
11
+ { name = "Datta Lab" },
12
+ ]
13
+ license = "LicenseRef-Harvard-Academic-Non-Commercial"
14
+ license-files = [
15
+ "LICENSE.md",
16
+ ]
17
+ classifiers = [
18
+ "Development Status :: 5 - Production/Stable",
19
+ "Intended Audience :: Science/Research",
20
+ "Operating System :: OS Independent",
21
+ "Programming Language :: Python :: 3.10",
22
+ "Programming Language :: Python :: 3.11",
23
+ "Programming Language :: Python :: 3.12",
24
+ "Programming Language :: Python :: 3.13",
25
+ "Programming Language :: Python :: 3.14",
26
+ "Topic :: Scientific/Engineering :: Bio-Informatics",
27
+ ]
28
+ requires-python = ">=3.10"
29
+ dependencies = [
30
+ "numpy>=2.2.6",
31
+ "ruamel.yaml>=0.19.1",
32
+ ]
33
+ version = "1.5.0"
34
+
35
+ [build-system]
36
+ requires = [
37
+ "pdm-backend",
38
+ ]
39
+ build-backend = "pdm.backend"