函数参考

函数说明为英文，与 R 版的帮助文档对应。

日常巡检

run_monitor

run_monitor(data, days=7, end_date=None, house_width=1, low_feed_kg=0.5, max_unidentified_pct=5, max_feed_drop_pct=30, iqr_k=1.5, station=None, time_zone='local', verbose=1)

Monitor the stations over the last days.

Prepare the visits once, compute the daily tables of the monitoring window (stations, houses, pigs, hours of the last day) and list the alerts of the last day.

参数：

名称	类型	描述	默认
data		Station data: a folder or files of NEDAP or FIRE exports, a raw export as a DataFrame (e.g. load_example("nedap")), or the result of read_station() or prep_visits().	必需
days	int	Number of days in the window, ending on end_date. Default 7.	7
end_date		Last day of the window ("YYYY-MM-DD" or a date). Default None: the last day in the data, or yesterday when the last day is today (an export taken during the day is incomplete).	None
house_width	int	Number of leading characters of the station ID that name its house, e.g. 1 for station "203" in house "2".	1
low_feed_kg	float	A pig that ate less than this on a day (kg) is "low_feed". Default 0.5.	0.5
max_unidentified_pct	float	Alert when more than this percentage of the visits of a station are unidentified on the last day. Default 5.	5
max_feed_drop_pct	float	Alert when the feed intake of a station on the last day is more than this percentage below its mean of the earlier days of the window. Default 30.	30
iqr_k	float	Body weights of a pig on a day outside the Tukey fences (quartiles -/+ iqr_k times the interquartile range) are outliers. Default 1.5.	1.5
station	str | None	"nedap", "fire" or None (detect).	None
time_zone	str	Times written with a time zone (e.g. 2025-01-24T00:34:17Z) are converted to this time zone before the days are counted. "local" (default): the time zone of this computer; or a name such as "Asia/Shanghai".	'local'
verbose	int	0 (silent), 1 (summary) or 2 (details).	1

返回：

类型	描述
Monitor	A Monitor with the tables stations,
Monitor	houses, pigs, pig_summary, hours, alerts,
Monitor	visits and settings.

Alerts of the last day:

type	level	when
station_down	danger	no visit at all on the station
unidentified	warning	more than max_unidentified_pct % of the visits unidentified
feed_drop	warning	feed intake more than max_feed_drop_pct % below the station mean of the earlier days
pig_no_visit	danger	a pig seen in the window did not visit its station
pig_low_feed	warning	a pig ate less than low_feed_kg

Pigs of a station without any visit get no pig alert: the station_down alert covers them.

Monitor dataclass

Result of run_monitor().

属性：

名称	类型	描述
stations	DataFrame	One row per station and day (monitor_stations()).
houses	DataFrame	One row per house and day.
pigs	DataFrame	One row per pig and day.
pig_summary	DataFrame	One row per pig over the window.
hours	DataFrame	One row per station and hour of the last day.
alerts	DataFrame	The alerts of the last day.
visits	DataFrame	The visits of the window.
settings	dict	The arguments, the window and the station type.

monitor_to_folder

monitor_to_folder(data, out_dir, format='xlsx', open=False, workers=None, verbose=1, **monitor_args)

Run the monitor and write the report and the tables into out_dir/<last day>/.

This is what the command line (tidypptsdm run), the desktop app and the scheduled task do.

参数：

名称	类型	描述	默认
data		Folder or files of exports, or a DataFrame (see run_monitor()).	必需
out_dir		Folder for the results; one subfolder per day.	必需
format	str	Format of the tables, "xlsx" or "csv".	'xlsx'
open	bool	Open the report in the web browser when done.	False
workers	int | None	Processes that draw the plots, see write_monitor_report().	None
verbose	int	0 (silent), 1 or 2.	1
**monitor_args		Arguments of run_monitor() such as days, house_width or low_feed_kg.	{}

返回：

类型	描述
dict	A dict with monitor, folder, report and tables.

日表

monitor_stations

monitor_stations(data, days=7, end_date=None, iqr_k=1.5, station=None, verbose=1)

Daily table per station.

One row per station (location) and date of the window, also for days without visits: n_pigs (pigs with an identified visit), n_visits, n_unidentified, pct_unidentified, occupation_h (hours the station was occupied), feed_kg (all visits), feed_per_pig_kg (identified feed / n_pigs), weight_kg (mean over the pigs of their daily median weight, outliers excluded) and pct_weight_outlier (recorded weights outside the Tukey fences of the pig and day, see iqr_k). Arguments as in run_monitor().

monitor_houses

monitor_houses(data, days=7, end_date=None, house_width=1, station=None, verbose=1)

Daily table per house.

Stations are grouped by the first house_width characters of their ID. One row per house and date: n_stations, n_pigs, n_visits, feed_kg, feed_per_pig_kg and weight_kg.

monitor_pigs

monitor_pigs(data, days=7, end_date=None, low_feed_kg=0.5, station=None, verbose=1)

Daily table per pig.

One row per pig and day, from the first day the pig was seen (or the start of the window) to the last day. A day without visit is kept with status = "no_visit". Columns: location (station with most visits in the window), responder, date, n_visits, feed_kg, occupation_min, weight_kg (median of the day) and status ("no_visit", "low_feed" or "ok").

monitor_hours

monitor_hours(data, date=None, station=None, verbose=1)

Hourly table per station for one day (default: the last full day).

One row per station and hour (0-23, from the entrance time): date, n_pigs, n_visits, occupation_min and feed_kg.

wide_table

wide_table(x, value)

One column of a daily table as a wide table.

Stations, houses or pigs in rows, days ("MM-DD") or hours ("00" to "23") in columns, plus total for counts, kg and time and mean otherwise.

参数：

名称	类型	描述	默认
x	DataFrame	A table from monitor_stations(), monitor_houses(), monitor_pigs() or monitor_hours() (or of a Monitor).	必需
value	str	The column to show, e.g. "feed_kg".	必需

作图

plot_monitor

plot_monitor(mon, type='trend', locations=None)

Plot the monitor, one plot per station.

参数：

名称	类型	描述	默认
mon	Monitor	Result of run_monitor().	必需
type	str	"trend" (default): pigs, visits, unidentified visits, occupation time, feed intake, feed intake per pig and body weight (mean of the pigs' daily medians; band from the lightest to the heaviest pig) per day; days without visits shaded red. "intake": stacked bars, one colour per pig: share of the station's feed (top) and kg (bottom) with the daily total; pigs without visit or with low feed on the last day are marked in the legend. "weight": box plots of the recorded body weights per day. "hours": visits, occupation time and feed intake per hour of the last day.	'trend'
locations		Stations to plot. Default None: all.	None

返回：

类型	描述
list[StationPlot]	A list of StationPlot: location,
list[StationPlot]	type, figure (a matplotlib Figure) and width and
list[StationPlot]	height in cm.

StationPlot dataclass

A plot of one station. width and height are in cm.

save_monitor_plots

save_monitor_plots(plots, path, device='png', dpi=150, verbose=1)

Save plots from plot_monitor() to files.

Files are named station_<location>_<type>.<device>.

参数：

名称	类型	描述	默认
plots	list[StationPlot]	One or more results of plot_monitor() (lists can be added with +).	必需
path		Folder to write to (created if needed).	必需
device	str	"png" (default) or "pdf".	'png'
dpi	int	Resolution of PNG files. Default 150.	150
verbose	int	0 (silent) or 1.	1

返回：

类型	描述
DataFrame	A DataFrame with location, type, file and saved.

输出

write_monitor_report

write_monitor_report(mon, path, title=None, locations=None, dpi=150, open=False, workers=None, progress=None, verbose=1)

Write an HTML report to browse station by station.

Writes index.html and the plots (img/) into path. Open index.html in a web browser: the first page is an overview of the last day (stations, pigs, visits, feed intake, the alerts, a table of all stations and houses, the settings), then one page per station with its alerts, the plots trend, intake, weight and hours and a table of its pigs. Turn the pages with the arrow keys; type a pig ID to jump to its station. The folder works offline.

参数：

名称	类型	描述	默认
mon	Monitor	Result of run_monitor().	必需
path		Folder to write to (created if needed).	必需
title	str | None	Title of the report. Default: station type and window.	None
locations		Stations to include. Default None: all.	None
dpi	int	Resolution of the plots. Default 150.	150
open	bool	Open the report in the web browser when done.	False
workers	int | None	Number of processes that draw the plots at the same time. Default None: one per CPU core (at most 8) when there are 6 stations or more, otherwise 1. 1 draws one station at a time.	None
progress		A function called as progress(done, total) after the plots of each station (e.g. for a progress bar).	None
verbose	int	0 (silent) or 1.	1

返回：

类型	描述
Path	The path of index.html.

write_monitor_tables

write_monitor_tables(mon, path, format='xlsx', file='monitor', verbose=1)

Write the monitor tables to an Excel workbook or CSV files.

The workbook has the long tables Alerts, Stations, Houses, Pigs (pig summary) and Pig days, and wide sheets (see wide_table()) with a colour scale from red (a possible problem) over yellow to green: Visits, Unidentified pct (red for high), Feed kg, Feed per pig kg, Occupation h, Weight outliers pct (red for high), House feed per pig kg, House weight kg, Pig feed kg, Hours visits and Hours feed kg (blue scales).

参数：

名称	类型	描述	默认
mon	Monitor	Result of run_monitor().	必需
path		Folder to write to (created if needed).	必需
format	str	"xlsx" (default) or "csv": the six long tables as <file>_alerts.csv and so on, UTF-8 with a byte order mark so that Excel shows Chinese text correctly.	'xlsx'
file	str	File name without extension, or prefix of the CSV files.	'monitor'
verbose	int	0 (silent) or 1.	1

返回：

类型	描述
Path | list[Path]	The path of the workbook, or the paths of the CSV files.

每天定时运行

schedule_monitor

schedule_monitor(folder, out_dir, time='07:30', taskname='tidypptsdm_monitor', script_dir=None, format='xlsx', register=True, verbose=1, **monitor_args)

Run the monitor every day.

Writes a small script that runs tidypptsdm run on folder and writes the report and the tables into out_dir/<last day>/, then:

• on Windows registers it in the Task Scheduler (schtasks), to run every day at time;
• on Linux and macOS prints the line to add with crontab -e.

参数：

名称	类型	描述	默认
folder		Folder with the station exports.	必需
out_dir		Folder for the results; one subfolder per day.	必需
time	str	Time of the daily run, "HH:MM". Default "07:30".	'07:30'
taskname	str	Name of the task and of the script: letters, digits, _ and -.	'tidypptsdm_monitor'
script_dir		Folder for the script. Default out_dir.	None
format	str	"xlsx" or "csv".	'xlsx'
register	bool	Register the task (Windows) or print the crontab line. With False only the script is written.	True
verbose	int	0 (silent) or 1.	1
**monitor_args		Arguments of run_monitor() such as days, house_width or low_feed_kg.	{}

返回：

类型	描述
Path	The path of the script (.bat on Windows, .sh otherwise).

unschedule_monitor

unschedule_monitor(taskname='tidypptsdm_monitor', verbose=1)

Remove the daily task registered by schedule_monitor() (Windows).

On Linux and macOS, remove the line with crontab -e.

读取和整理数据

read_station

read_station(files, station=None, format=None, pattern=DEFAULT_PATTERN, sheet=0, time_zone='local', verbose=1)

Read NEDAP or FIRE exports into one standard table.

参数：

名称	类型	描述	默认
files		A folder (all files matching pattern, also in subfolders) or one or more file paths. CSV and TXT (separator detected) and Excel .xlsx files are read.	必需
station	str | None	"nedap", "fire" or None to detect the type from the column names of the first file.	None
format		None for the built-in format, or a station format: the path of a tab-separated format file, a DataFrame with columns field, column and unit, or a dict {field: column}. See station_format().	None
pattern	str	Regular expression for file names when files is a folder.	DEFAULT_PATTERN
sheet		Sheet name or index for Excel files.	0
time_zone	str	Times written with a time zone, such as 2025-01-24T00:34:17Z (UTC), are converted to the clock time of this time zone, so that days run from local midnight to midnight. "local" (default): the time zone of this computer; or a name such as "Asia/Shanghai". Times without a time zone are taken as they are.	'local'
verbose	int	0 (silent), 1 (summary) or 2 (details per file).	1

返回：

类型	描述
DataFrame	A DataFrame with the standard fields (feed intake in g, body weight
DataFrame	in kg, duration in s) plus source_file. df.attrs["station"]
DataFrame	holds the station type.

station_format

station_format(station='nedap', file=None)

The built-in station format of a station type.

参数：

名称	类型	描述	默认
station	str	"nedap" or "fire".	'nedap'
file	str | PathLike | None	Optional path. The format is written there as a tab-separated text file, a template to edit for exports with other column names and to pass to read_station(format=).	None

返回：

类型	描述
DataFrame	A DataFrame with one row per field: field, column, unit,
DataFrame	required and description.

In the format, column is the column name or its position ("6"); alternatives are separated by | ("Tag|耳标号"); two columns joined with , give a date and a clock time ("Date,Entry"); - means the export has no such column. unit is kg, g or auto for masses, s or min for the duration, and - or a strptime format such as %d/%m/%Y %H:%M for times.

prep_visits

prep_visits(data, station=None, format=None, duration_max=DURATION_MAX, misread_max_visits=MISREAD_MAX_VISITS, time_zone='local', verbose=1)

Prepare a standard visit table from NEDAP or FIRE data.

参数：

名称	类型	描述	默认
data	DataFrame	The result of read_station(), or a raw export already in Python (e.g. load_example("nedap")).	必需
station	str | None	"nedap", "fire" or None: taken from data.attrs["station"] or detected from the column names.	None
format		Station format for raw data whose columns differ from the usual export (see station_format()).	None
duration_max	float	Longest plausible visit, s. A FIRE visit whose exit clock time is before its entry is a midnight crossing when the corrected duration is not longer than this. Default 3600.	DURATION_MAX
misread_max_visits	int	A pig's run of at most this many consecutive visits at another station, inside its visits at its own station, is a transponder misread: these visits become unidentified. Default 2.	MISREAD_MAX_VISITS
time_zone	str	For raw data with time-zone aware times (e.g. ending in Z): convert them to this time zone, see read_station(). Default "local".	'local'
verbose	int	0 (silent), 1 (summary) or 2 (details).	1

返回：

类型	描述
DataFrame	A DataFrame, one row per visit, ordered by location and
DataFrame	entry_time: responder (None for unidentified visits),
DataFrame	responder_raw, identified, location, date,
DataFrame	seq_days, seq_in_day, seq_in_location, entry_time,
DataFrame	exit_time, duration (s), feed_intake (g), weight (kg,
DataFrame	NaN when not recorded), trough_in, trough_out, topup
DataFrame	(g, FIRE only) and source_file when present.
DataFrame	attrs["station"] holds the station type and attrs["stations"]
DataFrame	one row per pig with its station history.

Body weights of 0 or below mean no weight was recorded. Rows without an entry time and exact duplicates are dropped.

示例数据

load_example

load_example(station='nedap')

Load an example export.

参数：

名称	类型	描述	默认
station	str	"nedap": 31,863 visits at two NEDAP stations, 30 pigs, 2024-02-19 to 2024-05-25. Body weight in g, duration in s, responder empty for 211 unidentified visits. "fire": 9,794 visits at two FIRE stations, 26 pigs, 2023-12-19 to 2024-02-22. Masses in kg, Tag 0 for 51 unidentified visits; 68 visits cross midnight.	'nedap'

返回：

类型	描述
DataFrame	The raw export as a DataFrame, as read from the CSV file (all
DataFrame	columns as text, like read_station()).

write_example

write_example(folder, station='nedap')

Write an example export as a CSV file into folder, to try the functions that read files (run_monitor(folder), the GUI).

返回：

类型	描述
Path	The path of the written file.