Summary
py3r.behaviour.summary.summary.Summary ¶
Summary(trackingfeatures: Features)
stores and computes summary statistics from features objects
save ¶
save(dirpath: str, *, data_format: str = 'parquet', overwrite: bool = False) -> None
Save this Summary (including nested Features/Tracking) to a directory.
Examples:
>>> import tempfile, os, pandas as pd
>>> from py3r.behaviour.util.docdata import data_path
>>> from py3r.behaviour.tracking.tracking import Tracking
>>> from py3r.behaviour.features.features import Features
>>> from py3r.behaviour.summary.summary import Summary
>>> with data_path('py3r.behaviour.tracking._data', 'dlc_single.csv') as p:
... t = Tracking.from_dlc(str(p), handle='ex', fps=30)
>>> f = Features(t)
>>> # add a boolean feature for summary methods to use
>>> mask = pd.Series([True, False] * (len(t.data)//2 + 1))[:len(t.data)]
>>> mask.index = t.data.index
>>> f.store(mask, 'mask', meta={})
>>> s = Summary(f)
>>> with tempfile.TemporaryDirectory() as d:
... s.save(d, data_format='csv', overwrite=True)
... os.path.exists(os.path.join(d, 'manifest.json'))
True
load
classmethod
¶
load(dirpath: str) -> 'Summary'
Load a Summary previously saved with save().
Examples:
>>> import tempfile, pandas as pd
>>> from py3r.behaviour.util.docdata import data_path
>>> from py3r.behaviour.tracking.tracking import Tracking
>>> from py3r.behaviour.features.features import Features
>>> from py3r.behaviour.summary.summary import Summary
>>> with data_path('py3r.behaviour.tracking._data', 'dlc_single.csv') as p:
... t = Tracking.from_dlc(str(p), handle='ex', fps=30)
>>> f = Features(t)
>>> f.store(pd.Series(range(len(t.data)), index=t.data.index), 'counter', meta={})
>>> s = Summary(f)
>>> with tempfile.TemporaryDirectory() as d:
... s.save(d, data_format='csv', overwrite=True)
... s2 = Summary.load(d)
>>> isinstance(s2, Summary) and 'counter' in s2.features.data.columns
True
count_onset ¶
count_onset(column: str) -> SummaryResult
counts number of times boolean series in the given column changes from False to True, ignoring nan values if first non nan value in series is true, this counts as an onset
Examples:
>>> import pandas as pd
>>> from py3r.behaviour.util.docdata import data_path
>>> from py3r.behaviour.tracking.tracking import Tracking
>>> from py3r.behaviour.features.features import Features
>>> from py3r.behaviour.summary.summary import Summary
>>> with data_path('py3r.behaviour.tracking._data', 'dlc_single.csv') as p:
... t = Tracking.from_dlc(str(p), handle='ex', fps=30)
>>> f = Features(t)
>>> mask = pd.Series([False, True, False, True, False][:len(t.data)], index=t.data.index)
>>> f.store(mask, 'mask', meta={})
>>> s = Summary(f)
>>> res = s.count_onset('mask')
>>> bool(res.value == 2)
True
time_true ¶
time_true(column: str) -> SummaryResult
returns time in seconds that condition in the given column is true
Examples:
>>> import pandas as pd
>>> from py3r.behaviour.util.docdata import data_path
>>> from py3r.behaviour.tracking.tracking import Tracking
>>> from py3r.behaviour.features.features import Features
>>> from py3r.behaviour.summary.summary import Summary
>>> with data_path('py3r.behaviour.tracking._data', 'dlc_single.csv') as p:
... t = Tracking.from_dlc(str(p), handle='ex', fps=30)
>>> f = Features(t)
>>> mask = pd.Series([True] * len(t.data), index=t.data.index)
>>> f.store(mask, 'mask', meta={})
>>> s = Summary(f)
>>> res = s.time_true('mask')
>>> bool(res.value > 0)
True
time_false ¶
time_false(column: str) -> SummaryResult
returns time in seconds that condition in the given column is false
Examples:
>>> import pandas as pd
>>> from py3r.behaviour.util.docdata import data_path
>>> from py3r.behaviour.tracking.tracking import Tracking
>>> from py3r.behaviour.features.features import Features
>>> from py3r.behaviour.summary.summary import Summary
>>> with data_path('py3r.behaviour.tracking._data', 'dlc_single.csv') as p:
... t = Tracking.from_dlc(str(p), handle='ex', fps=30)
>>> f = Features(t)
>>> mask = pd.Series([False] * len(t.data), index=t.data.index)
>>> f.store(mask, 'mask', meta={})
>>> s = Summary(f)
>>> res = s.time_false('mask')
>>> bool(res.value > 0)
True
total_distance ¶
total_distance(point: str, startframe: int | None = None, endframe: int | None = None) -> SummaryResult
returns total distance traveled by a tracked point between optional start and end frames
Examples:
>>> from py3r.behaviour.util.docdata import data_path
>>> from py3r.behaviour.tracking.tracking import Tracking
>>> from py3r.behaviour.features.features import Features
>>> from py3r.behaviour.summary.summary import Summary
>>> with data_path('py3r.behaviour.tracking._data', 'dlc_single.csv') as p:
... t = Tracking.from_dlc(str(p), handle='ex', fps=30)
>>> f = Features(t)
>>> s = Summary(f)
>>> res = s.total_distance('p1', 0, 4)
>>> isinstance(res.value, (int, float))
True
sum_column ¶
sum_column(column: str) -> SummaryResult
Sum all non-NaN values in a features.data column and return as a SummaryResult.
Examples:
>>> import pandas as pd
>>> from py3r.behaviour.util.docdata import data_path
>>> from py3r.behaviour.tracking.tracking import Tracking
>>> from py3r.behaviour.features.features import Features
>>> from py3r.behaviour.summary.summary import Summary
>>> with data_path('py3r.behaviour.tracking._data', 'dlc_single.csv') as p:
... t = Tracking.from_dlc(str(p), handle='ex', fps=30)
>>> f = Features(t)
>>> s = pd.Series([1, 2, 3, 4, 5][:len(t.data)], index=t.data.index)
>>> f.store(s, 'x', meta={})
>>> summ = Summary(f)
>>> res = summ.sum_column('x')
>>> bool(res.value == 15)
True
mean_column ¶
mean_column(column: str) -> SummaryResult
Mean of all non-NaN values in a features.data column and return as a SummaryResult.
Examples:
>>> import pandas as pd
>>> from py3r.behaviour.util.docdata import data_path
>>> from py3r.behaviour.tracking.tracking import Tracking
>>> from py3r.behaviour.features.features import Features
>>> from py3r.behaviour.summary.summary import Summary
>>> with data_path('py3r.behaviour.tracking._data', 'dlc_single.csv') as p:
... t = Tracking.from_dlc(str(p), handle='ex', fps=30)
>>> f = Features(t)
>>> s = pd.Series([1, 2, 3, 4, 5][:len(t.data)], index=t.data.index)
>>> f.store(s, 'x', meta={})
>>> summ = Summary(f)
>>> res = summ.mean_column('x')
>>> bool(res.value == 3)
True
median_column ¶
median_column(column: str) -> SummaryResult
Median of all non-NaN values in a features.data column and return as a SummaryResult.
Examples:
>>> import pandas as pd
>>> from py3r.behaviour.util.docdata import data_path
>>> from py3r.behaviour.tracking.tracking import Tracking
>>> from py3r.behaviour.features.features import Features
>>> from py3r.behaviour.summary.summary import Summary
>>> with data_path('py3r.behaviour.tracking._data', 'dlc_single.csv') as p:
... t = Tracking.from_dlc(str(p), handle='ex', fps=30)
>>> f = Features(t)
>>> s = pd.Series([1, 2, 3, 4, 5][:len(t.data)], index=t.data.index)
>>> f.store(s, 'x', meta={})
>>> summ = Summary(f)
>>> res = summ.median_column('x')
>>> bool(res.value == 3)
True
max_column ¶
max_column(column: str) -> SummaryResult
Max of all non-NaN values in a features.data column and return as a SummaryResult.
Examples:
>>> import pandas as pd
>>> from py3r.behaviour.util.docdata import data_path
>>> from py3r.behaviour.tracking.tracking import Tracking
>>> from py3r.behaviour.features.features import Features
>>> from py3r.behaviour.summary.summary import Summary
>>> with data_path('py3r.behaviour.tracking._data', 'dlc_single.csv') as p:
... t = Tracking.from_dlc(str(p), handle='ex', fps=30)
>>> f = Features(t)
>>> s = pd.Series([1, 2, 3, 4, 5][:len(t.data)], index=t.data.index)
>>> f.store(s, 'x', meta={})
>>> summ = Summary(f)
>>> res = summ.max_column('x')
>>> bool(res.value == 5)
True
min_column ¶
min_column(column: str) -> SummaryResult
Min of all non-NaN values in a features.data column and return as a SummaryResult.
Examples:
>>> import pandas as pd
>>> from py3r.behaviour.util.docdata import data_path
>>> from py3r.behaviour.tracking.tracking import Tracking
>>> from py3r.behaviour.features.features import Features
>>> from py3r.behaviour.summary.summary import Summary
>>> with data_path('py3r.behaviour.tracking._data', 'dlc_single.csv') as p:
... t = Tracking.from_dlc(str(p), handle='ex', fps=30)
>>> f = Features(t)
>>> s = pd.Series([1, 2, 3, 4, 5][:len(t.data)], index=t.data.index)
>>> f.store(s, 'x', meta={})
>>> summ = Summary(f)
>>> res = summ.min_column('x')
>>> bool(res.value == 1)
True
store ¶
store(summarystat: Any, name: str, overwrite: bool = False, meta: Any = None) -> None
stores a summary statistic and optional metadata, with optional overwrite protection
Examples:
>>> from py3r.behaviour.util.docdata import data_path
>>> from py3r.behaviour.tracking.tracking import Tracking
>>> from py3r.behaviour.features.features import Features
>>> from py3r.behaviour.summary.summary import Summary
>>> with data_path('py3r.behaviour.tracking._data', 'dlc_single.csv') as p:
... t = Tracking.from_dlc(str(p), handle='ex', fps=30)
>>> f = Features(t)
>>> s = Summary(f)
>>> s.store(123, 'num_events', meta={'unit':'count'})
>>> s.data['num_events'] == 123 and s.meta['num_events']['unit'] == 'count'
True
make_bin ¶
make_bin(startframe: int, endframe: int) -> 'Summary'
creates a copy of the Summary object with the dataframes restricted from startframe to endframe, inclusive
Examples:
>>> from py3r.behaviour.util.docdata import data_path
>>> from py3r.behaviour.tracking.tracking import Tracking
>>> from py3r.behaviour.features.features import Features
>>> from py3r.behaviour.summary.summary import Summary
>>> with data_path('py3r.behaviour.tracking._data', 'dlc_single.csv') as p:
... t = Tracking.from_dlc(str(p), handle='ex', fps=30)
>>> f = Features(t)
>>> s = Summary(f)
>>> b = s.make_bin(0, 2)
>>> isinstance(b, Summary)
True
make_bins ¶
make_bins(numbins: int) -> List[Summary]
creates a list of Summary objects, with frames restricted into numbins even intervals. start/endpoints are duplicated between intervals to ensure no loss in e.g. distance calculations
Examples:
>>> from py3r.behaviour.util.docdata import data_path
>>> from py3r.behaviour.tracking.tracking import Tracking
>>> from py3r.behaviour.features.features import Features
>>> from py3r.behaviour.summary.summary import Summary
>>> with data_path('py3r.behaviour.tracking._data', 'dlc_single.csv') as p:
... t = Tracking.from_dlc(str(p), handle='ex', fps=30)
>>> f = Features(t)
>>> s = Summary(f)
>>> bins = s.make_bins(3)
>>> len(bins) == 3 and all(isinstance(b, Summary) for b in bins)
True
transition_matrix ¶
transition_matrix(column: str, all_states=None) -> SummaryResult
Returns a transition matrix for a given column in self.features.data, with rows and columns as the unique values of the column or as specified by all_states.
Examples:
>>> import pandas as pd
>>> from py3r.behaviour.util.docdata import data_path
>>> from py3r.behaviour.tracking.tracking import Tracking
>>> from py3r.behaviour.features.features import Features
>>> from py3r.behaviour.summary.summary import Summary
>>> with data_path('py3r.behaviour.tracking._data', 'dlc_single.csv') as p:
... t = Tracking.from_dlc(str(p), handle='ex', fps=30)
>>> f = Features(t)
>>> states = pd.Series(['A','A','B','B','A'][:len(t.data)], index=t.data.index)
>>> f.store(states, 'state', meta={})
>>> s = Summary(f)
>>> res = s.transition_matrix('state')
>>> isinstance(res.value, pd.DataFrame)
True
count_state_onsets ¶
count_state_onsets(column: str) -> SummaryResult
counts the number of times a state is entered in a given column
Examples:
>>> import pandas as pd
>>> from py3r.behaviour.util.docdata import data_path
>>> from py3r.behaviour.tracking.tracking import Tracking
>>> from py3r.behaviour.features.features import Features
>>> from py3r.behaviour.summary.summary import Summary
>>> with data_path('py3r.behaviour.tracking._data', 'dlc_single.csv') as p:
... t = Tracking.from_dlc(str(p), handle='ex', fps=30)
>>> f = Features(t)
>>> states = pd.Series(['A','A','B','B','A'][:len(t.data)], index=t.data.index)
>>> f.store(states, 'state', meta={})
>>> s = Summary(f)
>>> res = s.count_state_onsets('state')
>>> hasattr(res, 'value')
True
time_in_state ¶
time_in_state(column: str) -> SummaryResult
returns the time spent in each state in a given column
Examples:
>>> import pandas as pd
>>> from py3r.behaviour.util.docdata import data_path
>>> from py3r.behaviour.tracking.tracking import Tracking
>>> from py3r.behaviour.features.features import Features
>>> from py3r.behaviour.summary.summary import Summary
>>> with data_path('py3r.behaviour.tracking._data', 'dlc_single.csv') as p:
... t = Tracking.from_dlc(str(p), handle='ex', fps=30)
>>> f = Features(t)
>>> states = pd.Series(['A','A','B','B','A'][:len(t.data)], index=t.data.index)
>>> f.store(states, 'state', meta={})
>>> s = Summary(f)
>>> res = s.time_in_state('state')
>>> hasattr(res, 'value')
True