Skip to contents

Frame Analytics Database Access Functions

Source: R/db-frame-analytics.R
db-frame-analytics.Rd

Functions for accessing pre-calculated per-frame analytics from the artwork_frame_analytics table. These functions provide the interface between the database and application code for retrieving frame-by-frame statistics.

Usage

getFrameAnalytics(artist, artwork, cn = NULL)

Arguments

artist

Character. Artist UUID

artwork

Character. Artwork UUID

cn

Database connection (optional, will create if NULL)

Value

getFrameAnalytics() returns a data.table with 21 columns of per-frame statistics. If no frame analytics exist for the artwork, the function will return an empty data.table (0 rows). In production, all artworks in artwork_index MUST have frame analytics data.

Details

Data Structure

The returned data.table from getFrameAnalytics() contains:

  • Identifiers: art_uuid, artist_uuid, frame

  • Temporal: elapsed_minutes, elapsed_hours, cumulative_strokes, estimated_bpm

  • Color: unique_colors, total_pixels, dominant_hex, dominant_pixels, color_diversity, avg_red, avg_green, avg_blue

  • Delta: colors_added, colors_removed, pixels_added, palette_change_score

  • Phase: technique_phase

  • Metadata: created_utc

Usage Pattern

Typical usage in application code:

# Retrieve frame analytics - will return empty data.table if none exist
frame_data <- getFrameAnalytics(artist, artwork)

# Use in getAppdata() for rich per-frame insights
appdata$artwork$frame_stats <- getFrameAnalytics(artist, artwork, cn)

Note: The platform enforces a "fail fast" philosophy. All artworks in artwork_index MUST have corresponding frame analytics data. If analytics are missing, it indicates a data pipeline failure that should be resolved immediately by running artpipelines::createFrameAnalytics().

Data Source

Frame analytics are generated by artpipelines::createFrameAnalytics() which processes raw artwork_colors data and stores results in the artwork_frame_analytics table. If analytics don't exist for an artwork, they need to be generated first using the pipeline function.

Functions

  • getFrameAnalytics(): Retrieve frame analytics data for artwork

See also

getArtworkStats

Other data-access: artHasNFT(), getArtistOpensea(), getArtistStyleMap(), getArtworkIndex(), getArtworkMeta(), getArtworkOpensea(), getArtworkProfile(), getArtworkProfileFull(), getArtworkStats(), getImageRaster(), getVerificationInfo(), get_artist_by_slug(), get_artist_collections_summary(), get_artist_recent_works(), get_artist_stats()

Examples

if (FALSE) { # \dontrun{
# Retrieve frame analytics for an artwork
frame_stats <- getFrameAnalytics(
  artist = "746b8207-72f5-4ab6-8d19-a91d03daec3d",
  artwork = "99a61148-1d3b-4340-8cf6-92ad26046b0f"
)

# Analyze the rich per-frame data
summary(frame_stats$palette_change_score)
table(frame_stats$technique_phase)
plot(frame_stats$frame, frame_stats$estimated_bpm)

# Examine color evolution
plot(frame_stats$frame, frame_stats$unique_colors, type = "l")

# Track dominant color changes
hist(frame_stats$palette_change_score)

# Using with a persistent connection
cn <- artcore::..dbc()
frames <- getFrameAnalytics(artist, artwork, cn = cn)
artcore::..dbd(cn)
} # }