# Metadata System Documentation

## Overview

The metadata system allows you to add flexible metadata to your plots and folders using YAML or JSON files. Metadata is inherited hierarchically from parent folders and can be overridden at any level.

## File Structure

### Folder Metadata
- **File names**: `meta.yaml`, `meta.yml`, or `meta.json`
- **Location**: Place in any folder containing plots
- **Scope**: Applies to all plots in the folder and subfolders (unless overridden)

### Plot-specific Metadata
- **File names**: `{plot_name}.yaml`, `{plot_name}.yml`, or `{plot_name}.json`
- **Location**: Place in the same folder as the plot PDF file
- **Scope**: Applies only to the specific plot with the same name

## Hierarchy and Inheritance

1. **Root folder**: Start with folder metadata in your source directory
2. **Subfolders**: Each subfolder can have its own `meta.yaml` that merges with parent metadata
3. **Plot-specific**: Individual plots can have their own metadata files that override folder metadata

## Example Usage

### Folder Structure
```
analysis_results/
├── meta.yaml                 # Root folder metadata
├── signal/
│   ├── meta.yaml            # Signal-specific metadata
│   ├── mass_plot.pdf
│   └── mass_plot.yaml       # Plot-specific metadata
└── background/
    ├── meta.yaml            # Background-specific metadata
    └── qcd_plot.pdf
```

### Example Metadata Fields

**Common fields for folder metadata:**
- `title`: Folder title
- `description`: Folder description
- `experiment`: Experiment name (CMS, ATLAS, etc.)
- `dataset`: Dataset identifier
- `analysis_type`: Type of analysis
- `author`: Author information
- `parameters`: Analysis parameters
- `tags`: Categorization tags

**Common fields for plot metadata:**
- `plot_type`: Type of plot (histogram, scatter, etc.)
- `variables`: Variable information (x_axis, y_axis, units)
- `selection`: Selection criteria
- `statistics`: Statistical information
- `display`: Display options (highlight, featured, order_priority)

## Configuration

The metadata system can be configured in `config.yaml`:

```yaml
metadata:
  cache_enabled: true           # Enable metadata caching
  inherit_from_parent: true     # Enable hierarchical inheritance
```

## Output

### HTML Template
Metadata is available in the HTML template as:
- `folder_metadata`: Current folder's resolved metadata
- `item.metadata`: Individual plot metadata (in items loop)

### Cache Files
- `meta_cache.json`: Generated in each web directory
- Contains resolved metadata for all plots in that directory
- Used for performance optimization and debugging

## Usage Tips

1. **Start simple**: Begin with basic folder metadata and add complexity as needed
2. **Use inheritance**: Put common metadata in parent folders to avoid repetition
3. **Override selectively**: Use plot-specific metadata only when needed
4. **Consistent naming**: Use consistent field names across your metadata files
5. **Validate format**: Ensure YAML/JSON files are valid before running the generator

## Integration with Templates

In your HTML templates, you can access metadata like:

```html
<!-- Folder metadata -->
<h2>{{ folder_metadata.title }}</h2>
<p>{{ folder_metadata.description }}</p>

<!-- Plot metadata -->
{% for item in items %}
  <div class="plot-item">
    <h3>{{ item.name }}</h3>
    {% if item.metadata.plot_type %}
      <span class="plot-type">{{ item.metadata.plot_type }}</span>
    {% endif %}
    {% if item.metadata.tags %}
      <div class="tags">
        {% for tag in item.metadata.tags %}
          <span class="tag">{{ tag }}</span>
        {% endfor %}
      </div>
    {% endif %}
  </div>
{% endfor %}
```