aniread (development version)
- Works with anicore’s
anipointclass and rebuilt accessor API (animovement/anicore#154). Readers return ananipoint,read_aniframe()restores ananieventas well as ananipoint, andread_boris()no longer sets spatial metadata on itsanievent.
Breaking changes
-
get_supported_sources()lists what can be written as well as read (#135). It now returns one row per source and direction, with the columnssource,direction("read"or"write"),funandsuffix; thereadercolumn is nowfun. To list readers as before, filter ondirection == "read".
Removed
-
The unused output validators,
ensure_output_header_names(),ensure_output_header_class()andensure_output_no_nan()(#123). No reader called them — their only callers were their own tests — so nothing they promised was ever enforced, and the tests passing gave the impression that it was.They could not be wired in as they stood: they require exactly
time,individual,keypoint,x,yandconfidence, which is a narrower contract than the aniframe has had for some time. Five of the seven sample sources fail it —read_deeplabcut()returns noindividual,read_anipose()andread_c3d()returnz,read_freemocap()returnsmodel, andread_fictrac()andread_c3d()return noconfidence.anicore::validate_aniframe()is the metadata-aware successor: it checks the frame against what it declares rather than against a fixed column list. The deprecated
read_animalta(detailed = ),read_idtracker(version = )andget_sample_data()source names"idtracker"and"trackball"are removed; useread_animalta(format = ),read_idtracker(format = ),"idtrackerai"and"trackball_bonsai"(#223).
Added
write_dataset()writes to any supported format, inferring it from the file suffix, as the counterpart ofread_dataset()(#135). A.csvis written as a plain table; inTRACKtive’s CSV needsformat = "intracktive".write_dataset()writes one file per group withby(#79):by = "individual"writesmice_individual-mouse1.csv,mice_individual-mouse2.csv, … from"mice.csv".bytakes several keys, and the role names"what"and"when"stand for all identity or all temporal keys, soby = c("what", "when")writes one file per track. Keys in braces in the path name the files instead, and setby:"{session}/mice_{individual}.csv". Each file holds an aniframe with the class and metadata of the whole. This is for tools that cannot hold several individuals with differing keypoints in one file, such as movement.A Parquet file written by
write_aniframe()orwrite_dataset()keeps its metadata where any language can read it (#203). The metadata, with the class, is JSON under the file’sanimovementkey,{"class": ["anipoint"], "metadata": {...}}, in the layoutanicore::get_metadata_json()documents. It was in arrow’srkey, as R code that Python, DuckDB and other readers cannot use, and is no longer kept there.read_aniframe()restores the metadata from the key, and still reads files written before. Needs anicore withget_metadata_json().A Parquet file keeps the class it was written with (#135).
read_aniframe()gave back ananisegmentoranijointas ananipoint, because arrow strips the class from a grouped frame and the reader could only tell ananipointfrom ananievent.write_aniframe()now records the class in the file’s metadata, as JSON under the keyanimovement({"class":["anijoint"]}), which any language can read, soread_dataset()afterwrite_dataset()returns the same class, grouping and metadata. Files written before this are read as they were.write_intracktive()writes the lineage of dividing tracks. A frame with aparentcolumn, asread_trackmate()gives one for a file with dividing tracks (#182), gets inTRACKtive’sparent_track_idcolumn: thetrack_idof the track each track divided from, and-1, inTRACKtive’s value for no parent, for the tracks that start a lineage. A parent that is not in the frame is also written as-1, with a warning. A frame withoutparentis written as before.read_freemocap()reads FreeMoCap v2’s output (#171). The tidyfreemocap_data_by_frame.csv, and the.parquetbeside it (with arrow installed), are read assource_format"v2_by_frame", and the per-trajectory files such asoutput_data/mediapipe_body_3d_xyz.csvas"v2_trajectory". Those per-trajectory files keep the names of v1’s wide per-model files but are long, so they are told apart by their columns. Models are named<tracker>_<aspect>as in v1 (rtmpose.left_handbecomesrtmpose_left_hand). Each keypoint appears once per trajectory in the tidy export: the newtrajectoryargument chooses"3d_xyz"(default) or"rigid_3d_xyz"for the positions, and the centres of mass become keypoints of a<tracker>_commodel, as v1’smediapipe_com. v2 writes no timestamps, sotimeis in frames.detect_source()andread_dataset()recognise the tidy CSV. The 9-column v1.8by_frame.csvalready read; it now has a test fixture written by FreeMoCap v1.8.2’s own saver, andmodelandkeypointare now always read as text, so a face keypoint such as0000can no longer be guessed to be the number 0.read_idtracker(), and soread_dataset(), reads idtracker.ai’s tidy CSV export,trajectories_tidy.csv(idtracker.ai 6.0.14), and its Parquet export,trajectories.parquet(6.0.13), which idtracker.ai recommends for R and for large datasets (#165). Both hold one row per frame and individual. The Parquet file records the version, frame rate, frame size and identity labels in its own metadata, and the tidy CSV inattributes_tidy.jsonbeside it, which the reader reads when it is there; both are then used as for the.h5.timeis in seconds when the frame rate is known; when it is not, idtracker.ai writes the frame as the time, sotimeis the frame counted from 0, withunit_time"frame", as for the other exports. A newformatargument names the export when the suffix and header do not, and which one was read is recorded insource_formatfor every idtracker.ai file.detect_source()recognises both: an idtracker.ai Parquet file was detected as an"aniframe", since every Parquet file opens with the same bytes, and is now told apart by the attributes in its metadata (with arrow installed).read_trackmate(), and soread_dataset(), keeps what a TrackMate XML records about the recording (#149). The frame interval inSettings/ImageDatabecomessampling_rate, converted to Hz, and the TrackMate version on the root element becomessource_version.sampling_ratestaysNAwhen the time unit is frames or not recognised. TrackMate writes an image with no time calibration as one second per frame, so a 1 Hz rate from a file in seconds may really be frames.-
Readers keep orientation where the source records it rather than deriving it from positions (animovement/anicore#46):
-
read_fictrac()keeps FicTrac’s “integrated animal heading” asyawand declares it as the frame’s orientation. Its movement direction, which follows from the path, is still not kept. -
read_trex()keeps TRex’sANGLE, the direction an individual faces from its posture, as a declaredyaw, reflected withylike the positions. It is read from either export when the run included it. -
read_bonsai()keeps the blob’sOrientationasorientation_axis: the angle of its long axis, axial rather than a heading, so it is not declared as orientation. It is turned withywhen y is reflected. -
read_octron()documents that itsorientationis scikit-image’s axial angle in image coordinates.
-
read_structure()reads a pose-estimation project’s skeleton as ananicore::anistructure(), detecting the tool from the file, alongsideread_structure_deeplabcut()(a project’sconfig.yaml, including multi-animal projects) andread_structure_sleap()(a.slpfile or an analysis.h5; body edges only, since symmetry edges are not segments). Attach it withanicore::set_structure(). A frame reader attaches a skeleton itself only when its data file carries one, as a SLEAP analysis.h5does; DeepLabCut keeps its skeleton in the project config, so a DeepLabCut frame still needsread_structure().read_sleap(), and soread_dataset(), keeps what a SLEAP analysis.h5records besides the tracks (#143). The skeleton is attached as the frame’skeypointstructure, parsed asread_structure_sleap()parses it, and the SLEAP version from the file’sprovenancerecord becomessource_version. The CSV export carries neither, so a frame read from it is unchanged.read_animalta()reads AnimalTA’s detailed data files,Results/Detailed_data/<video>/Arena_<a><target>.csv, which “Run analyses” writes one per target. A file keeps its time and positions (XandY, orX_SmoothedandY_Smoothed) and drops the measures derived from them; itsarenaandindividualare read from the file name, and several files can be read together as one recording. Its positions are in the unit of the scale set in AnimalTA, which the file does not record, sounit_spaceshould be declared when a scale was set.detect_source()andread_dataset()recognise these files too.read_animalta()reads coordinates files tracked with AnimalTA’s “Separate head from tail” option. A target alone in its arena then hasX_Arena<a>_Ind<i>_Headand_Tailcolumns instead of a single pair, which broke the reader’s pivot; they become the keypointsheadandtailof that individual, while other targets keepcentroid. Once corrected, AnimalTA saves the head and tail as two targets,Ind<i>_part0andInd<i>_part1, in the coordinates file and in the names of the detailed data files; these read as the sameheadandtail. AnimalTA writes no centroid for such a target. A target renamed in AnimalTA keeps its name, with its case, as itsindividual.read_trex()(CSV export),read_animalta()andread_idtracker()(CSV export) setsampling_ratefrom the frame rate their time column states (#149). None of these files records the rate, but each times its rows by frame: TRex and AnimalTA write a frame number beside the time, and idtracker.ai writes one row per frame. When every time is the frame number divided by one rate, to within the rounding of the time column, that rate is set, as a whole number when one fits; otherwisesampling_ratestaysNA. All three sample files give their recorded rate: 30, 30 and 28 Hz.read_idtracker()names the individuals of an idtracker.ai.h5by itsidentities_labelsattribute, the identity names set in idtracker.ai’s validator, rather than by position, and records itswidthattribute, written by newer releases, as the x extent inaxis_extents(#149). A file whose identities were never renamed reads as before, since idtracker.ai then writes"1","2", ….read_idtracker(), and soread_dataset(), keeps what an idtracker.ai.h5records about the recording (#146). Theversionattribute becomessource_versionandframes_per_secondbecomessampling_rate, each leftNAwhen the file does not record it.timestays the frame number, sounit_timeis still"frame". The frame height is now read from theheightattribute, where idtracker.ai writes it, so y is reflected around the frame rather than around the furthest tracked point. The CSV export keeps these in a separateattributes.json, so a frame read from it is unchanged.-
read_sleap()reads SLEAP’s analysis CSV export (#87).get_supported_sources()advertisedcsvfor SLEAP while the reader aborted with “We hope to support SLEAP CSV import soon!”, so the registry had been narrowed toh5as a stopgap; it advertises both again.The columns are
track,frame_idx,instance.scoreand a.x/.y/.scoretriple per node, which is how sleap-io defines the format. Node names are read from the columns rather than assumed, since a recording has whatever skeleton it was tracked with, andinstance.scoreis dropped rather than becoming a keypoint calledinstance— it scores the whole instance, where the h5 reader takes confidence from the per-node scores.One recording reads the same from either export, checked against the h5 it was generated from. Two things make that true:
timeisframe_idx, counted from 0 as the h5 counts frames; and a frame in which an instance was not detected comes back as an all-NArow rather than being absent, since the CSV holds a row per instance and omits those entirely — the same reinstatementread_octron()does. detect_source()recognises a SLEAP analysis CSV, by theframe_idxandinstance.scorecolumns sleap-io uses to identify one. It previously inspected only HDF5 names, so a SLEAP CSV was not detected at all andread_dataset()could not route it.read_sleap()records which export it read in thesource_formatmetadata field.Every reader now records the export it read in the
source_formatmetadata field (#118), so which layout a frame came from no longer has to be guessed.read_boris()records"aggregated"or"tabular",read_fictrac()its layout by column count,"23col","24col"or"25col", andread_deeplabcut()andread_lightningpose()the file type, single- or multi-animal, and 3D, such as"csv_multi_animal"or"h5_single_animal_3d"; a reader of a single layout records its file type, such as"csv"forread_octron().get_supported_sources()gains aformatlist column with the values each reader records, so the layouts aniread reads can be listed, and checked against the test fixtures.-
read_trex()reads TRex’s native.npzexport (#116). It is a zip of.npyarrays, one file per tracked individual, so a whole recording is the vector of pathsget_sample_data("trex")returns — which previously errored, because the registry declared TRex a CSV-only source. The arrays are parsed directly rather than through a new dependency:.npyis a short header over a raw buffer, andunz()reads zip members without unpacking.The
.npzcarries what the CSV export does not, so three of this reader’s documented limitations turn out to be limitations of the CSV rather than of TRex:individualis the identity TRex assigned instead ofNA,confidenceis its per-framedetection_pinstead ofNA, and the pose keypoints are present at all. The frame rate and frame size are recorded too, sosampling_rateis set and the reflection tobottom_leftno longer has to guess the frame height frommax(y). read_trex()gains aformatargument, defaulting to"auto", which reads the export from the file rather than its extension.read_freemocap()reads the 9-column tidy export (#117). FreeMoCap added areprojection_errorcolumn at v1.7.4; the reader accepted a file with fewer than ten columns and rejected everything else, so the current export was read only by accident of that threshold. Both the 8- and the 9-column form are now read deliberately.FreeMoCap data gains a
confidencecolumn, fromreprojection_errorwhere the file has one and all-NAwhere it does not. The two run in opposite directions — an error is a distance in pixels, so zero is best, whileconfidenceeverywhere else in aniread comes from a likelihood or probability where larger is best — so it is mapped through1 / (1 + error)rather than renamed. That is monotone onto(0, 1], gives 1 for a perfect reprojection, and is invertible: the original error is1 / confidence - 1. Renaming it would have madeaniprocess::filter_na_across(method = "confidence")discard the best-tracked points.read_freemocap()reads theby_trajectoryexport and the per-model wide files inoutput_data/(mediapipe_body_3d_xyz.csvand siblings), which it previously rejected (#117). Neither carries a frame column — the row position is the frame — and neither names its models in the data, so point names are parsed the way FreeMoCap’s ownDataSaver._parse_keypoint_name()parses them. One recording therefore gives the samemodelandkeypointvalues whichever of the three layouts it is read from, and identical coordinates: checked across all 126,096 rows of the v1.8.0 release asset.read_freemocap()gains aformatargument, defaulting to"auto", which reads the layout from the column names. It followsread_boris(), whoseformat = c("auto", ...)is the pattern the other readers should converge on (#118).The layout a file was read as is recorded in the
source_formatmetadata field, as"by_frame_8col"or"by_frame_9col", so drift between FreeMoCap releases is visible on the aniframe rather than only in whether reading happened to work.read_c3d(),read_movement(),read_sleap()andread_trackmate()have examples that run (#103). They read new files ininst/extdata, each a few frames of a public recording:c3d.c3d, a Vicon Nexus static trial from pyCGM (MIT);movement.nc, movement’s two-mice sample (CC BY 4.0);sleap.analysis.csvandsleap.analysis.h5, two flies written by sleap-io from its own test data (BSD-3-Clause); andtrackmate.xml, a dividing cell from TrackMate’s C. elegans example (CC BY 4.0), which shows theparentcolumn.inst/extdata/README.mdrecords where each came from, how it was cut, and the licence notices.
Changed
get_sample_data()names sources asread_dataset()does, and serves a sample for every source that has a public one (#169)."idtracker"is now"idtrackerai"and"trackball"is now"trackball_bonsai"; the old names are removed (#223). New datasets:"octron","trackmate"(three recordings),"fasttrack", idtracker.ai’s CSV export ("trajectories_csv"), a second C3D file ("sample-static"), DeepLabCut’s wasp as CSV ("single-wasp_csv"), and SLEAP’s three Aeon mice, with named tracks ("three-mice_Aeon").get_sample_data("lightningpose")now downloads the 172 kB"IBL-paw_EKS-left"by default rather than the 24 MB"mouse-face", which is still available by name.write_intracktive()numbers tracks by the frame’s identity keys (anicore::get_keys()) rather than by a fixed list ofsession,trial,model,individualandkeypoint. A frame read byread_trackmate(), whose tracks are told apart bytrack, was written with all its tracks under onetrack_id; each track now gets its own. Since the keys are read from the aniframe’s metadata,datamust now be an aniframe: a plain data frame errors, where it was written by whichever of those columns it had.The FreeMoCap v1 example files,
freemocap.csv,freemocap_by_trajectory.csvandfreemocap_wide.csvininst/extdata, are now written by FreeMoCap’s own code (v1.8.2’ssplit_and_save(),DataLoaderandDataSaver) from one synthetic recording, and so are distributed under aniread’s licence. They were excerpts of FreeMoCap’s v1.8.0 test-data release, whose licence is unknown.read_freemocap()’s examples therefore show other values, and the three layouts now hold the same points, so they can be compared row for row.tests/testthat/data/freemocap/README.mdrecords how they were made.timeis the time elapsed since the first frame of the video, so the first frame of the video is attime = 0, whatever the unit (#150). In frames,timeis the frame number counted from 0, and converting it to seconds is a division by the frame rate with no offset; a file that starts later in the video keeps its offset. Sources that count frames from 0 (most of them) are read as they are, and sources that count from 1 are shifted by one. This shiftstimefor anyone indexing by frame number in:read_sleap()(.h5and CSV, one frame earlier),read_idtracker()(.h5, and the CSV export and tidy CSV and Parquet exports when they have no frame rate, one frame earlier),read_boris()withunit_time = "frame"for an observation of images (one image earlier; a video’s frames are unchanged), andread_c3d(), which now keeps the frame of the recording the file starts at from its header, so a trimmed file no longer starts at 0 s. Every other reader already started at 0. Code that picks rows by frame number from the SLEAP, idtracker.ai and BORIS readers needs the number one lower (framenis nowtime == n - 1), and code that subtracted 1 to line them up with other sources no longer should. The “Time” section of?read_datasetlists each source’s own convention and what its reader does.get_sample_data("freemocap")downloads a real recording with a clear licence: movement’s FreeMoCap star-jump session (CC BY 4.0, shared by Max Staras), written by FreeMoCap’s own saver without the face mesh (animovement/movement-data#10). The default dataset,"star-jump", is the 9-columnby_frame.csvFreeMoCap writes from v1.7.4, withreprojection_error;"star-jump_v1.7"is the same recording in the 8-column layout of earlier versions, and"star-jump_by_trajectory"and"star-jump_wide"are itsby_trajectory.csvandmediapipe_body_3d_xyz.csv. The 10.7 MB 8-column file it used to download,"test-data", whose origin and licence are unclear, is no longer offered. The files are cached under new names, so a cache from before holds no stale copy.get_sample_data("movement")downloadsMOVE_two-mice_octagon.analysis.ncfrom SWC GIN, saved by movement 0.17.0 or later with the singular dimension names (#167). The file it used to download, the same recording saved with the plural names of earlier versions, is the dataset"legacy-plural". Both are cached under new file names, so a cache from before holds no stale copy.read_animalta()takes the layout asformat = c("auto", "fixed", "variable", "detailed"), followingread_boris()andread_freemocap()(#118), and records it in thesource_formatmetadata field. The layoutdetailed = TRUEnamed,Frame;Time;Arena;Ind;X;Y, is not AnimalTA’s detailed data but its coordinates file for a variable number of targets, so it is nowformat = "variable", the one-pair-per-target coordinates file isformat = "fixed", andformat = "detailed"names the detailed data files.detailedis removed (#223): useformat = "variable"fordetailed = TRUEandformat = "fixed"fordetailed = FALSE.read_idtracker()’sversionargument is removed (#118, #223). It was never used: the reader recognises the export from the file, asformatnames it, and reads the version that wrote it intosource_versionwhere the file records one.read_trackmate()labels tracks by the name TrackMate gave them rather than by the numericTRACK_ID(#149). TrackMate’s default namesTrack_0,Track_1, … are read as their numbers,0,1, …, since the column already says they are tracks, and a name you gave a track in TrackMate is kept as written, so a file with some tracks renamed reads as, say,0,2andCell A. It falls back toTRACK_IDwhen a track has no name, or with a warning when two tracks would get the same id. The levels oftrackare now in numeric order,2before10, rather than sorted as text, with any names after the numbers.Functions carry a lifecycle badge when they are not stable (animovement/.github#46).
read_structure(),read_structure_deeplabcut()andread_structure_sleap(), which are new in this release, andread_freemocap()’s newformatargument are experimental: they may still change without a deprecation cycle while their design settles (#118). Every function without a badge is stable, and changes only through a deprecation cycle.-
read_sleap()names individuals by the track SLEAP recorded, rather than by position (#125). The h5 reader readtrack_namesonly to count them and then labelled individualsindividual1,individual2, …, discarding names the file already held — soSLEAP_three-mice_Aeon_mixed-labels.analysis.h5came back asindividual1/2/3instead ofAEON3B_NTP/TP1/TP2. A recording with no tracks, such as a single untracked instance, still falls back to the positional names, because there is nothing else to use.This changes the
individualvalues returned for any h5 with named tracks. Code matching on"individual1"will need the real name instead;levels(data$individual)shows them. get_sample_data("trex")defaults to"five-locusts"(#116). The previous default,"beetles", is a 19-frame CSV excerpt with one unnamed individual and no confidence — too small to carry an example or a tutorial."five-locusts"is a real 2845-frame recording of five individuals with pose and detection probability."beetles"is still available, and is still the fixture exercising the CSV path.read_trex()treatsInfas missing in both exports. TRex marks a frame it could not track with an infinity rather than aNaN— its own documentation masksnp.infout before plotting — so these were reaching the aniframe and propagating through every downstream calculation. Usesanicore::convert_inf_to_na(), added for this.read_trex()no longer requires the CSV’s optional columns.VX,VYandtimestampwere dropped by name, which errors on a file that does not have them — and which columns a TRex CSV carries is set per run by itsoutput_fieldsparameter.read_trex()declaresunit_timeas"s". TRex reports seconds in both exports, and leaving it unset meantanicore::set_sampling_rate()treated the column as frames and divided it by the frame rate.read_freemocap()’s error names the layout it found rather than only the one it wanted. Told aby_trajectory.csvor a per-modelmediapipe_body_3d_xyz.csv, it said to look for a file ending inby_frame.csv— unhelpful when the recording never produced one. Neither layout is read yet; both are now recognised well enough to say so.
Fixed
get_sample_data()downloads every file in binary mode. It chose text mode for any suffix not on a list, which left out.c3d,.xmland.npz; on Windows, text mode rewrites line endings, which corrupts a binary file such as a C3D.read_trackball()records that a trackball sensor has no fixed rate (#195). The sensor reports motion only as it happens, so thesampling_ratea frame is given is the rate of the windows its readings are integrated into, and anicore (from 0.8.0.9008) took that first declared rate for the device’s own assource_sampling_rate.source_sampling_rateis nowNaN, anicore’s marker for a device with no fixed rate, andsampling_rateis still the window rate.write_intracktive()writes inTRACKtive’stas frame numbers counted from 0, as inTRACKtive reads it (#191). It wrotetimeunchanged, and inTRACKtive caststto a whole number, so times in seconds collapsed several rows onto onetand times in minutes left empty frames between them. A frame whose time is already in frames is written as before, and the writer now stops if any of those times is not whole. A frame in another unit is converted withanicore::convert_unit_time(data, "frame"): by its recorded frame numbers when it has aframecolumn, and otherwise by itssampling_rate, so at 30 Hz times of 0, 1/30 and 2/30 seconds become 0, 1 and 2, and TrackMate’s C. elegans sample, imaged every 2 minutes, becomes 0, 1, 2, …. Rather than invent frame numbers, the writer stops, saying how to declare the rate, when nosampling_rateis declared or the times are not regularly spaced at it. aniread now requires anicore 0.8.0.9008.-
read_sleap()reads the analysis exports that sleap-io writes, as SLEAP does from 1.6.3 on (#170).- An
.h5written with sleap-io’s"standard"preset or custom axes failed or came back scrambled, since the reader assumed SLEAP’s original axis order. The order is now read from each dataset’sdimsattribute, and SLEAP’s layout is assumed only where there is none, so files SLEAP wrote itself read as before. - A very old
.h5withoutpoint_scoresfailed; it now reads withNAconfidence. - When the
provenancerecord names no SLEAP version,source_versionis the sleap-io version that wrote the file, as"sleap-io 0.9.2"for example, rather thanNA. - A sleap-io
.h5spans the whole video, so frames after the last detection come back asNArows, as undetected frames always have. - In the CSV, a row with an empty
trackis an untracked instance. It hadindividualNA, and an untracked recording with several instances in a frame failed; such rows are now namedindividual1,individual2, … by their place in the frame, as the.h5reader names the instances of a file without track names. sleap-io’s own.h5of an untracked recording names themtrack_0,track_1, …, and those names are kept. Where a track has two rows in one frame, a user-labelled and a predicted instance, the first, user-labelled, one is kept, as sleap-io’s.h5export keeps it. A CSV without score columns reads withNAconfidence. - sleap-io sorts the CSV’s node columns by name, with
.scorebefore.xand.y. The reader matches them by name, so this needed no change, and is now tested.
- An
read_trackmate()splits a track that divides, as a cell lineage does, into its branches, and records the lineage in a newparentcolumn. From its first division such a track holds more than one spot in a frame, which a frame keyed bytrackandtimecannot hold, and the reader warned about duplicate track-frame combinations and returned them. Each branch is now a track of its own, starting at its first spot after the division, so nothing is measured across one. The branch before the first division keeps the track’s id, and the others are numbered on from the largest track number in the file, track by track and, within a track, by the frame they start in, then the track they divided from, then x.parentholds the id of the track each track divided from, as thePof the Cell Tracking Challenge’sres_track.txtdoes, and isNAfor a track that did not divide from another, so for every track of a file without divisions. It is a plain column with the levels oftrack, not an identity key. A track whose branches also merge is left whole, with the warning as before.read_trackmate()reads the blank spatial unit (spatialunits=" ") that TrackMate writes for an image whose length unit is a space, as in files from TrackMate 7.13, as pixels when the pixel size is 1, as ImageJ treats an image with no length unit. It warned that" "had no equivalent in anicore and setunit_spaceto"none", as it still does when the pixels are scaled.read_idtracker()no longer replaces factors with their codes when it turns the NaN idtracker.ai writes for a lost position intoNA(#165). An.h5read with the keypoint"1"rather than"centroid", and a CSV export of ten or more individuals mixed them up: their names sort as text ("1","10","11","2", …), so individual 10 was named"2". The individuals of a CSV export are now also ordered by number.-
read_deeplabcut(), and soread_lightningpose()andread_dataset(), reads every DeepLabCut-layout file it rejected or misread (#168):- An
.h5in pandas’ “fixed” format, which is what pandas writes by default and so what movement’sto_dlc_file()and any other re-save produce. Only DeepLabCut’s own “table” format was read, so movement’s DBTravelator sample files aborted. - Stitched multi-animal tracklets (
*_el.h5), which DeepLabCut keeps under the HDF keytracksrather thandf_with_missing.detect_source()recognises them too; a SLEAP analysis file, which has atracksdataset rather than a group, is not taken for one. - 3D files, from DeepLabCut’s triangulation or movement, whose coords are
x,yandzwith no likelihood.confidenceisNA, the aniframe is 3D, and y is not reflected, since triangulated positions are not in image pixels;video_heightis not used. - Multi-animal
.h5files. The check for anindividualslevel read the attributes of the wrong node, so it never found one, and a multi-animal file was parsed as single-animal: there was noindividualcolumn, the individuals came back as keypoints, and the values did not belong to the keypoints they were on. - Multi-animal
.csvfiles whose bodyparts or individuals have an underscore in their name, such asleft_ear. The names were split at the underscore and the reader aborted. -
.h5files with a bodypart or individual name outside ASCII, which aborted. - Lightning Pose’s Ensemble Kalman Smoother output, which has nine coords per keypoint. The ensemble medians and the ensemble and posterior variances became extra keypoints such as
nose_x_ensand straymedianandvarcolumns; nowx,yandlikelihoodare read and the rest is not. Its multi-camera 3D output,multicam_3d_results.csv, aborted and now reads as 3D.
A multi-animal project tracks the bodyparts it does not assign to an animal, its unique bodyparts, under the pseudo-individual
single; these are kept as the keypoints of an individual called"single". The header is read from the file’s own levels in every case, so the.csvand.h5of the same data read the same, and thetimeread from an.h5is a plain vector rather than a one-dimensional array. A missing value from an.h5isNArather thanNaN, as it is from a.csv. - An
get_sample_data()downloads the movement sample datasets from their new home, SWC GIN. They moved from G-Node GIN, which was often unreachable and made these downloads time out (neuroinformatics-unit/movement#1080). The file paths are unchanged.read_fictrac()reads.datfiles from every FicTrac 2 release (#172). It named 25 columns whatever the file held, so the 23 columns written by FicTrac 2.0 to 2.02, and the 24 written by untagged versions from July 2019 until 2.03, failed to read. The column count now decides the names, andtimecomes from the time since midnight where the file has one (column 25 from FicTrac 2.03 on, column 22 in a 24-column file) and from the timestamp in column 22 of a 23-column file. A file with any other number of columns gets an error saying so.read_fictrac()keepstimerunning forward when a recording crosses midnight (#149, #172). The time since midnight that it reads starts again from zero at midnight, sotimejumped back by a day there. A drop of more than twelve hours between two rows now adds a day from that row on.read_boris()setssampling_ratefor an observation of several media files (#173). BORIS lists one FPS per file in a single cell, such as25.000;25.000, which did not parse as a number, so the rate was left out. It is now set when the files agree.read_boris()puts a behaviour without a category in the"behavior"channel when reading an aggregated export from current BORIS (#173). That export writes"Not defined"in theBehavioral categorycolumn where older exports and the tabular export leave it empty, so such behaviours landed in a channel called"Not defined".read_idtracker()reads an idtracker.ai CSV export that has no time column (#149). idtracker.ai writes none when it could not read the video’s frame rate, and the reader aborted with “Columntimedoesn’t exist”.timeis now the frame number, the row counted from 0 as the.h5reader counts frames, withunit_time"frame"andsampling_rateNA.detect_source(), and soread_dataset(), recognises idtracker.ai’strajectories.csvwhatever its time column:seconds, thetimethat newer releases write, or none. It recognised onlyseconds, althoughread_idtracker()has readtimesince #60.read_idtracker()(CSV export),read_animalta()andread_bonsai()declareunit_timeas"s"(#148, #149). Theirtimeis in seconds, but the metadata said frames, so anything that reads the unit misread it:anicore::convert_unit_time()divided the seconds by the frame rate, and speeds came out per frame rather than per second. Thetimevalues are unchanged, but results that depend on the unit will differ.read_idtracker()keeps"frame"for the.h5, whosetimeis the frame number.read_bonsai()reflects y around the frame height the file records (#149). A workflow that writes the image alongside the centroid writes itsSize.WidthandSize.Heighton every row, but the reader reflected y around the largest tracked y, so every y was off by the difference: 254 px on the 1080 px frame of the test file. When every image in the file has the same size, that size is now used, and recorded as theaxis_extentsof x and y.video_heightstill takes precedence.read_animalta()keeps individuals in different arenas apart with anarenaidentity key (#149). AnimalTA numbers individuals from 0 within each arena, and the reader dropped theArenacolumn of the layout for a variable number of targets, formerly called detailed, so in a file with several arenas the first individual of every arena became one individual with several rows per time. The aniframe now has anarenacolumn, AnimalTA’s arena number, and its keys arearena,individualandkeypoint, so functions that work per individual keep arenas apart.individualis AnimalTA’s name for the target,Ind<i>, in every layout: it was0,1, … in the variable layout andarena0_ind0, … in the fixed one. A corrected file, where AnimalTA writesIndasInd0,Ind1, …, gives the same names. Every layout has thearenacolumn, also for a file with a single arena.read_trex()declaresunit_spaceas"cm"(#149). TRex gives positions in centimetres in both exports, but the metadata said pixels, so anything that reads the unit misread them. The positions are unchanged. TRex converts with itscm_per_pixel, which assumes an image 30 cm wide unless the real width was set, so the centimetres are only as real as that setting. The.npzexport’s frame width is now recorded too, as the x extent inaxis_extents.read_trackmate()reflects y around the height of the image in the unit of the positions,height * pixelheightfromSettings/ImageData, rather than aroundheightin pixels (#149). In a file calibrated in microns or any other unit than pixels, every y was off by the difference.read_trackmate()reads files in any time or space unit (#149). It recognised only"sec","pixel"and"micron", and aborted on anything else, such as"frame","min","msec"or"µm". TrackMate’s units are now mapped onto anicore’s, and one with no equivalent, such as days or inches, becomes"unknown"or"none"with a warning.read_movement()keeps theconfidenceof each point (#149). It was read from the file and never joined, so every frame came back without one.read_movement()reads 3D files (#149). The axes were fixed atxandy, so a dataset whosespacecoordinate holdsx,yandzaborted; they are now read fromspace.-
read_movement()anddetect_source()read files saved by movement 0.17.0 and later (#167). movement renamed the dimensionsindividualsandkeypointstoindividualandkeypoint, so these files were not detected andread_movement()aborted with “Object ‘individuals’ does not exist”. Both names are now read, so files saved by earlier versions keep reading. Along with the rename:- A
confidencescored per individual, with dimensions (time,individual), which movement accepts since 0.17.0, is repeated for every keypoint of that individual. - A file without a
source_fileattribute, such as a dataset movement built from arrays, takes the name of the file read as itsfilenamerather than aborting. - A movement bounding boxes dataset or a multi-view dataset now aborts with a message saying it is not a single-view poses dataset, rather than with an error from deep inside the reader.
- A
read_movement()reads files that movement saved without a frame rate (#149). movement then writestime_unit = "frames"and nofps, and the reader aborted because"frames"is not one of anicore’s units. It now becomes"frame", andsampling_ratestaysNArather than becoming an empty number.write_aniframe()writes.csvfiles comma-separated (#136). It passed the call tovroom::vroom_write(), whose default delimiter is a tab, so.csvand.tsvboth came out tab-separated. The delimiter now follows the extension — a comma for.csv, a tab for.tsv— and an explicitdelimstill wins.detect_freemocap_format()no longer mistakes aby_trajectoryfile for a wide one. It told them apart by aframecolumn that FreeMoCap does not write in either; they are distinguished by the timestamps, which onlyby_trajectorycarries.detect_source()recognises FreeMoCap files written by v1.7.4 and later (#117). It compared the header for exact equality with the eight columns of the older export, so a file withreprojection_errorwas not identified as FreeMoCap at all andread_dataset()failed on it. The header is now matched by inclusion, which also survives the next column FreeMoCap appends.
aniread 0.7.0 (2026-08-28)
Added
-
read_custom()takes anindexargument, so a frame indexed by something other thantimecan be read (#107). The index used to be smuggled in throughvariables_whenand told apart by the literal string"time"; since these became separate roles in anicore,read_custom()’s own documented example — a frame indexed byframewithintrial— could not be expressed at all.c("trial", "frame")normalised to"trial", leaving the frame indexed by atimecolumn the data does not have.
Changed
The core data structures come from
anicore, which is what theaniframepackage was renamed to in its 0.8.0 (animovement/anicore#84). Theaniframeclass keeps its name; only the package providing it changed, soanicorereplacesaniframeinImportsand in everyaniframe::call.The minimum
anicoreis 0.8.0, which is the first version published under that name. The constraint read>= 0.6.0— a version ofanicorethat never existed, carried over unchanged fromaniframewhen the dependency was renamed.Axis geometry is declared through
anicore’s axis directions and extents, replacingset_origin()andset_y_height(), anddefault_metadata()follows its rename tolist_default_metadata().
Fixed
-
read_trackball()anddetect_source()cope with a run of serial-port junk before the first complete record, not just a single partial row (#94). The skip was computed fromutils::count.fields(), which silently drops blank lines, so on a capture with blank lines among the junk it landed early — on a noise line, which was then accepted as a header, and the read failed withColumn index 4 is out of bounds.
aniread 0.6.0 (2026-08-18)
Added
read_dataset()reads any supported format through one entry point, working out which source software wrote the file rather than requiring you to know in advance (#73). Passsourceto name the format explicitly, or...to reach a reader’s own arguments. It returns whatever the underlying reader returns — ananiframe, or ananieventforread_boris().detect_source()reports which software wrote a file without reading it. Candidates are narrowed by suffix, then each detector inspects the contents, which matters because twelve sources read.csv. DeepLabCut and LightningPose export structurally identical files, so it returns the combined name"deeplabcut/lightningpose"rather than guessing. Detectors needing an optional package (rhdf5,arrow,xml2,c3dr) are skipped when it is absent, and the error names what was skipped.?read_trackballdocuments the raw Bonsai layout, the requirement thatcol_timebe a shared clock with two sensors, and that empty time bins are filled with zero motion — an assumption about this logger rather than about optical flow generally.
Changed
get_supported_sources()no longer listscsvas a SLEAP suffix —read_sleap()cannot read it, and auto-detection would have routed such files straight into that error. Restored when the reader gains support (#87).get_supported_sources()renames thetrackballsource totrackball_bonsai, matching thesourcemetadataread_trackball()actually stamps.
Fixed
read_trackball()reads real two-sensor Bonsai optical-flow captures (#85). It previously either aborted with an error pointing nowhere near the cause, or silently returned a misaligned trajectory. Sensor alignment,start_datetime, corrupt rows, leading junk, microsecond clocks, gap filling and argument handling were each at fault; see the PR for the breakdown.read_trackball()warns whencol_timeresolves to a non-datetime column and two sensors are given — a per-board counter has a sensor-local origin and cannot align two files. Warning classaniread_sensor_local_clock.read_animalta()works out which export layout a file uses instead of being told (#88).detaileddefaults to"auto"and reads the answer from the header. This was the one case wheredetect_source()identified a file correctly andread_dataset()then failed on it.detect_source()recognises a Bonsai optical-flow capture whether or not it carries a header row.ensure_header_match()no longer rejects a charactercol_timeon files that do have named headers.
aniread 0.5.1
Added
-
get_supported_sources()returns the source softwareanireadcan read as a tibble ofsource/reader/suffix, so downstream packages can discover supported formats programmatically instead of hard-coding them. Closes #74.
Fixed
-
read_octron()no longer drops frames in which nothing was detected. Octron omits such frames entirely; the reader now reinstates them as all-NA rows across the full track × frame grid (using the analysed-frame count from the CSV header) so the time axis is gap-free. Closes #80. -
read_boris(unit_time = "frame")no longer fails on exports with an inconsistent image index (e.g. a STOP on the last video frame recorded as frame 1, givingstop < start). When FPS is known, the offending frame interval is recovered fromround(time_s * fps). Closes #81.
aniread 0.5.0
Added
-
read_boris()imports behavioural events from a BORIS export into ananicore::anievent(). Supports the two flat-text BORIS exports — aggregated events (one row per bout) and tabular events (one row per START / STOP / POINT transition; paired into bouts by the reader) — and auto-detects the format from the file’s first row. Channels are taken from BORIS’sBehavioral categorywhen populated, falling back to the literal"behavior"; modifiers travel via themodifierslist-column in both the newer multi-column (Modifier #1,Modifier #2, …) and the legacy single-column pipe-separated layouts. State-vs-point classification is recorded inmetadata$variables_event.unit_time = "s"(default) readsStart (s)/Stop (s); passunit_time = "frame"to use the image-index columns instead, which keeps event timestamps row-aligned with a host aniframe (and falls back to seconds when no image-index columns are present). FPS is recorded assampling_ratemetadata without rescaling timestamps. Closes #76.
Fixed
- File validation no longer rejects readable files on Windows network (UNC) shares.
file.access()returns false negatives for read permission on such paths; the read check now falls back to a non-destructive open attempt whenfile.access()reports no access.
Changed
-
aniframe (>= 0.6.0)is now required, sinceread_boris()produces ananieventobject — a new class added in aniframe 0.6.0.
aniread 0.4.1
Added
-
read_octron()gains apropertiesargument for picking which region-property columns to read ("all"by default; pass a character vector for a subset orNULLto skip them).areais auto-included whenmethod = "weighted". -
read_octron()normalises hyphens to underscores in column names (moments_hu-0→moments_hu_0).
Changed
-
read_octron()is now substantially faster on large multi-segment files, especially when only a fewpropertiesare requested.
aniread 0.4.0
Changed
- Readers whose source data uses image (top-left) origin now reflect
yso the returned aniframe is in the conventionalbottom_leftorigin. This fixes plots being upside-down without manual reorientation. Affectsread_animalta(),read_bonsai(),read_deeplabcut(),read_fasttrack(),read_idtracker(),read_lightningpose(),read_movement(),read_octron(),read_sleap(),read_trackmate(), andread_trex()(#61). -
aniframe (>= 0.5.0)is now required, since the reflection uses the newset_origin()/set_y_height()API.
Added
- All affected readers gain an optional
video_heightargument for supplying the source frame height when the format does not record it (DeepLabCut, LightningPose, SLEAP, AnimalTA, Bonsai, FastTrack, TRex, idtracker.ai CSV, movement netCDF). When omitted, the reader falls back to source-extracted values where available, and finally tomax(y). -
read_idtracker()now reads/heightfrom the trajectories h5 file by default. -
read_trackmate()now reads the frame height fromSettings/ImageData/@heightin the XML by default. -
read_octron()continues to readvideo_height:from the CSV header, but now also accepts avideo_heightoverride and stores the value in the aniframe metadata. -
read_octron()gains amethodargument to handle frames where Octron emitted multiple mask segments for the same track (#67). One of"weighted"(default; area-weighted mean of position and shape props, sum of areas),"largest"(single largest segment per row), or"segments"(one row per segment, with a newsegmentidentity variable).
Fixed
-
read_idtracker()now accepts both the legacysecondsand the newertimeleading column in idtracker.ai CSV exports (#60).
aniread 0.3.2
Added
-
read_c3d()for C3D motion-capture data, andread_fasttrack()for FastTrack data. -
read_deeplabcut()reads HDF5 exports as well as CSV.
Fixed
-
read_octron()handles the newer Octron output format.
aniread 0.3.1
Added
-
read_aniframe()reads a saved aniframe back from parquet. -
read_movement()imports data from the movement Python package. -
read_trackmate()reads TrackMate XML. Adapted from the reader in TrackMateR, with thanks to @quantixed. -
read_octron()reads Octron CSV. -
calibrate_trackball()for trackball calibration.
aniread 0.3.0
Added
-
write_aniframe()writes an aniframe to parquet, andwrite_intracktive()exports for intracktive. -
read_anipose(),read_fictrac(),read_freemocap()andread_custom(). -
get_sample_data()fetches example files for the readers.
aniread 0.2.0
Added
- The first readers:
read_deeplabcut(),read_sleap(),read_lightningpose(),read_trex(),read_idtracker(),read_animalta(),read_bonsai(),read_movement()andread_trackball(), withvalidate_trackball(). - A
NEWS.mdfile, to track changes to the package.