
## Problem Statement

There are **n pirates** dividing a treasure.

- Pirate **1** takes **$\frac{1}{n}$** of the **total** treasure.
- Pirate **2** takes **$\frac{2}{n}$** of **what remains**.
- Pirate **3** takes **$\frac{3}{n}$** of the remaining amount.
- …
- Pirate **i** takes **$\frac{i}{n}$** of the remaining pile at his turn.

We must determine the **index of the pirate who gets the largest share**  
(older pirates have smaller indices, so answer is between 1 and n).

---

### Example

If $n = 3$:

| Pirate | Share Taken |
|-------|-------------|
| 1 | $\frac{1}{3}$ |
| 2 | $\frac{2}{3}(1 - \frac{1}{3}) = \frac{4}{9}$ |
| 3 | $\frac{3}{3}(1 - \frac{1}{3} - \frac{4}{9}) = \frac{2}{9}$ |

The **largest share** is $\frac{4}{9}$, taken by **Pirate 2**.

## Formal Definition

Let $S_i$ be the share of Pirate $i$.

$$
S_i = \frac{i}{n} \cdot \prod_{k=1}^{i-1}\left(1 - \frac{k}{n}\right)
$$

The product term is the **fraction of treasure remaining** after pirates 1 to $i-1$ have taken their shares.

Our goal:

$$
\text{Find } \arg\max_{1 \le i \le n} S_i.
$$

---

## Comparing Consecutive Shares

Instead of computing every share, compare two neighbors:

$$
\frac{S_{i+1}}{S_i}
= \frac{(i+1)(n-i)}{in}
$$

- If **> 1**, shares are increasing at $i$
- If **< 1**, shares are decreasing after $i$
- So the **maximum occurs where increasing stops and decreasing starts**

This happens when:

$$
\frac{(i+1)(n-i)}{in} = 1
$$

which simplifies to:

$$
i^2 + i - n = 0
$$

This is a **quadratic equation** in $i$.

---

## Solving the Quadratic

For:
$$
i^2 + i - n = 0
$$

Using the quadratic formula:

$$
i = \frac{-1 + \sqrt{1+4n}}{2}
$$

We only take the **positive root** since pirate indices are positive.

Let:
$$
p = \left\lfloor\frac{\sqrt{1+4n}-1}{2}\right\rfloor
$$

Now check:

- If $n = p(p+1)$, then **pirates p and p+1 tie** → choose the earlier pirate → return **p**
- Otherwise, the maximum occurs at **p + 1**

---

## Python Implementation (Big-Integer Safe)

### Using Integer Square Root

```python
from math import isqrt

def pirate_with_largest_share(n):
    # Compute p = floor((sqrt(1 + 4n) - 1) / 2) using integer sqrt to avoid precision issues
    p = (isqrt(1 + 4*n) - 1) // 2

    # Check for tie case
    return p if p * (p + 1) == n else p + 1
```

### Using brute force

```python
def pirate_largest_bruteforce_float(n: int) -> int:
    remaining = 1.0
    best_i, best_share = 1, 0.0

    for i in range(1, n + 1):
        share = (i / n) * remaining
        if share > best_share:
            best_share, best_i = share, i
        remaining -= share  # same as: remaining *= (1 - i/n)

    return best_i
```


Pirate Treasure



**Why I Wrote This Post**

I came across a coding challenge that asked to create a custom scikit-learn transformer to handle missing values using a robust statistic called the trimmed mean.

**What Is the Trimmed Mean?**

The trimmed mean (also called the truncated mean) is a robust measure of central tendency, a middle ground between:

- the mean, which is sensitive to extreme values, and
- the median, which ignores most of the data.

In many real-world datasets such as income distributions, sensor readings, or user behavior metrics, a few extreme values can heavily distort the regular mean.

By trimming a fixed fraction of the lowest and highest values before computing the average, we get a measure that is:

- Less affected by outliers
- Still uses most of the data (unlike the median)
- Smooth and differentiable, making it suitable for optimization and statistical modeling

**Mathematical Formula of the Trimmed Mean**

Let $x_{(1)}, x_{(2)}, \ldots, x_{(n)}$ be the **sorted sample** of $n$ data points, arranged in ascending order.  
Let $\alpha$ represent the **trimming proportion**, the fraction of data to remove from each tail.

We define:

$$
k = \lfloor \alpha n \rfloor
$$

where $\lfloor \cdot \rfloor$ is the **floor function**, which rounds a real number down to the nearest integer.

The **trimmed mean** is then computed as:

$$
\text{TrimmedMean}_{\alpha}(x) =
\frac{1}{n - 2k}
\sum_{i=k+1}^{n-k} x_{(i)}
$$

This formula means we:
1. Remove the lowest $k$ and highest $k$ values  
2. Compute the mean of the remaining $n - 2k$ values

**I wonder why is $\alpha$ Limited to $0 \leq \alpha < 0.5$?**

We require at least one data point to remain after trimming.  
That gives us the condition:

$$
n - 2k > 0
$$

Substituting $k = \lfloor \alpha n \rfloor$:

$$
n - 2\lfloor \alpha n \rfloor > 0
$$

---

**Key Property of the Floor Function**

For any real number $x$:

$$
\lfloor x \rfloor \leq x
$$

Applying this property:

$$
n - 2\lfloor \alpha n \rfloor \geq n - 2(\alpha n) = n(1 - 2\alpha)
$$

To ensure the expression is positive:

$$
n(1 - 2\alpha) > 0
$$

Since $n > 0$, we can divide both sides by $n$:

$$
1 - 2\alpha > 0
$$

$$
\boxed{\alpha < 0.5}
$$

Without using mathematical proof, we can also reason that if we trim half or more of the data ($\alpha \geq 0.5`), there are no values left to average.  

If you trim half or more of the data ( $\alpha \geq 0.5$ ), there are no values left to average.  
That’s why the valid range is:
$$
0 \leq \alpha < 0.5
$$

---

**How to Calculate the Trimmed Mean in Python**

There are two common approaches to calculate the trimmed mean in Python:

- Using a scipy function
- Using a numpy function

```python
import numpy as np
from scipy import stats
x = np.array([1, 2, 3, 4, 5, 100, 101])  # two large outliers
def trimmed_mean(x, alpha=0.1):
    """
    Compute the trimmed mean manually, ignoring NaNs.
    alpha: fraction (0 <= α < 0.5) of data to trim from each tail.
    """
    x = np.asarray(x, dtype=float)
    x = x[~np.isnan(x)]               
    n = len(x)
    if n == 0:
        return np.nan
    k = int(np.floor(alpha * n))
    if 2 * k >= n:                    
        return np.mean(x)
    x_sorted = np.sort(x)
    trimmed = x_sorted[k:n - k]
    return np.mean(trimmed)
print(f"Trimmed mean scipy (α={alpha}):", stats.trim_mean(x, proportiontocut=0.3))
print(f"Trimmed mean numpy (α={alpha}):", trimmed_mean(x,0.3))
print("Regular mean:", np.mean(x))

Trimmed mean scipy (α=0.3): 4.0
Trimmed mean numpy (α=0.3): 4.0
Regular mean: 30.857142857142858
```

**Implement Trimmed Mean as a Custom Transformer in Sklearn**

Scikit-learn provides two base classes that make it easy to create reusable and pipeline-compatible components:

1. **BaseEstimator**

- Gives your class access to methods like .get_params() and .set_params().
- These are essential for grid search and hyperparameter tuning.
- It also standardizes the initialization pattern , parameters passed in `__init__` are stored as attributes automatically.

Example:
When you call GridSearchCV, it can automatically find and modify parameters like trim_fraction inside your transformer because it inherits BaseEstimator.

2. **TransformerMixin**

- Provides a default implementation of the .fit_transform() method.
- Ensures that your transformer follows scikit-learn’s expected API: it must implement both .fit() and .transform().
- Once you inherit TransformerMixin, you only need to define these two methods, and your class can plug directly into any Pipeline.

**Implementation Details**

1. **Implement helper function to calculate the trimmed mean**

```python
def _trimmed_mean_1d(x, alpha):
    x = np.asarray(x, dtype=float)
    x = x[~np.isnan(x)]
    n = x.size
    if n == 0:
        return np.nan
    k = int(math.floor(alpha * n))
    if 2 * k >= n:
        return float(np.mean(x))
    xs = np.sort(x)
    return float(np.mean(xs[k:n-k]))
```

2. **Wrap helper function in a custom transformer**

- Inherit BaseEstimator and TransformerMixin
- Implement `fit` to calculate the trimmed mean
- Implement `transform` to apply the trimmed mean to the data

Small details: use `check_array` and `check_is_fitted` as checks to ensure the input is valid and the transformer is fitted.


For the complete working code, including the helper function, the TrimmedMeanImputer class, and example usage inside a scikit-learn pipeline, you can check the notebook here: [Trimmed Mean Pipeline Sklearn](https://github.com/rzsgrt/backpocket/blob/main/Trimmed%20Mean%20Pipeline%20Sklearn.ipynb)

Trimmed Mean Pipeline in Sklearn


I'll begin by discussing counterfactuals example. Suppose we have a machine learning model that predicts the likelihood of a patient developing diabetes, with one of its features is the patient's glucose level. In this scenario, the model predicts that a patient has a high likelihood of developing diabetes, based on their glucose level. Now we may wonder what glucose level would be required for the prediction to change to not indicate diabetes. To answer this question, we can run a counterfactual analysis using the machine learning model, where we simulate changing the patient's glucose level and observe how this affects the prediction.
So, with this example, we can see that counterfactual can be used for *interpreting* (its not *casual relationship*) model prediction for specific instance.

When generating counterfactual example, we want feature changes to be minimal and the new value is actionable. To formalize that requirement, we can refer to loss function proposed by Wachter et al[1]

$$
L(x', x) = \lambda \cdot (f(x') - y')^2 + d(x, x')
$$

where:

- $x$ is the original input.
- $x'$ is the counterfactual.
- $f(x')$ is the model's prediction on the counterfactual.
- $y'$ is the desired output.
- $d(x, x')$ is a distance function.
- $\lambda$ is a regularization parameter that controls the trade-off between achieving the desired prediction and staying close to the original instance.

For distance function above:  
$$
d(x, x') = \sum_{i} \frac{|x_i - x'_i|}{\text{MAD}_i}
$$

where:

$$
\text{MAD}_i = \text{median}(|x_i - \text{median}(x_i)|)
$$
This normalization ensures scale invariance across features.

Along with Watcher, I found another paper proposing loss function more robust since they include diversity in generated example. Mothilal[2] add new component in loss function:

$$
L(x') = L_{\text{pred}} + \lambda_1 L_{\text{prox}} + \lambda_2 L_{\text{div}}
$$

The first and second component similar with we see in Watcher. The last component encourages diversity among the generated counterfactuals which results different feature combinations being altered. Using this approach, we can get multiple alternative paths to achieve the desired outcome.

Luckily, both Wachter version or Mothilal version are available in python. The first is implemented in mlextend while the second has official implementation on github.

---

***(Disclaimer: I use an LLM while write this post to ensure my writing is grammatically correct and easy to understand. All generated content is reviewed to prevent any changes in meaning. However, any incorrect information in this post may result from my own misunderstandings. If you notice any inaccuracies, please let me know.)***

---
Source:

[1] Wachter, S., Mittelstadt, B., & Russell, C. (2017). Counterfactual explanations without opening the black box: Automated decisions and the GDPR. [link](https://arxiv.org/abs/1711.00399)  
[2] Mothilal, Ramaravind K., Amit Sharma, and Chenhao Tan. (2019). Explaining Machine Learning Classifiers through Diverse Counterfactual Explanations. [link](https://arxiv.org/pdf/1905.07697)  
[3] Interpreting models via counterfactuals (Code) [link](https://rasbt.github.io/mlxtend/user_guide/evaluate/create_counterfactual/)  
[4] Diverse Counterfactual Explanations (DiCE) for ML (Code) [link](https://github.com/interpretml/DiCE)  
[5] Counterfactual Explanations [link](https://christophm.github.io/interpretable-ml-book/counterfactual.html)


Counterfactual Machine Learning


Decorator is one of design pattern type. It allow you to add additional functionality to your function or class. For note:this functionality should be out of scope your function, because your function should have one thing to do. And to achieve this, we just create function that accept main function as argument

---

For simple start, we create one simple function that print hello world

```python
def hello_world():
    print("hello world!")
```

This function just print one line, takes no input and return none. We decide that **scope of this function is to print only one line hello world.** Now, if we want to call hello world function twice, we create another function to call hello_world function. Why we can pass function as function argument Because in **python we treat function as any other variable**.

```python
def repeat(fn):
    fn()
    fn()

def hello_world():
    print("hello world!")

# Call repeat function with argument hello_world function
repeat(hello_world)
```

Output:

```bash
>> hello world!
>> hello world!
```

As mentioned in first paragraph that decorator can add function functionality, we can try add another print statement (let say this is another functionality) inside repeat function. but now we also create wrapper inside repeat function. In code below, function repeat_with_wrapper return wrapper_fn. So first we assign it to variable then we call it as function. (this behavior inline with statement function as variable above).

```python
def repeat_with_wrapper(fn):
    def wrapper_fn():
        fn()
        print("print another word")
        fn()
    return wrapper_fn

def hello_world():
    print("hello world!")

repeat_wrapper = repeat_with_wrapper(hello_world) 
repeat_wrapper()

# same behavior
hello_world = repeat_with_wrapper(hello_world) 
hello_world()
```

output

```bash
>> hello world!
>> print another word
>> hello world!
```

Code above not efficient and redundant if you working on bigger codebase. So turns out we can simplify using `@repeat_with_wrapper` above function hello_world. So, code above could be simplified to

```python
def repeat_with_wrapper(fn):
    def decorated_fn():
        fn()
        print("print another word")
        fn()
    return decorated_fn


@repeat_with_wrapper
def hello_world():
    print("Hello world!")

hello_world()
```

&nbsp;  
&nbsp;  
And that decorator in python! As written above, we can add another functionality to main function. From now on we can identify if we saw `@` above function in python. We already know how to create simple decorator. But what if our function more complex and need argument? The answer: we modify it by passing
**`*args, **kwargs`** to our wrapper function.  
&nbsp;  

```python
def repeat_with_wrapper(fn):
    def decorated_fn(*args, **kwargs):
        print("print another word")
        fn(*args, **kwargs)
    return decorated_fn

@repeat_with_wrapper
def hello_world(name: str):
    print(f"Hello {name}!")

hello_world("Reza")
```

Output:

```bash
Hello Reza!
```

&nbsp;  
&nbsp;  
I hope we can identify or create some decorator. Now let's see some python built-in decorator.

1.@staticmethod  
As its name, @staticmethod transform method into static method. It allow us use method inside class without create any class instance. For example:

```python
class SampleClass:
    @staticmethod
    def get_today_date()
    ...

# You can access get_total_data by
# Method 1
sample = SampleClass()
sample.get_today_date()
# Method 2
SampleClass.get_today_date()
```

2.@classmethod  
Similar with staticmethod, @classmethod transform a method into a class method. This class method also known as factory method, or to construct class itself. For example:

```python
from datetime import date
class User:
    def __init__(self,name,age):
    ...

    @classmethod
    def fromBirthYear(self,cls,name,birth_year):
        return cls(name,date.today().year - birth_year) 

# To create class
User('Lorem',40)
User.fromBirthYear('Ipsum',1950)
```

3.@property
This decorator name really self explanatory. You need these to get attribute

```python
class Dog:
    ...
    @property #Getter
    def weight(self):
        return self.weight

oleng = Dog()
poleng.weight
```

&nbsp;  
&nbsp;  
So far we talked about decorator in function and function as decorator, but can we create decorator in class or can we create decorator from class?

Most known decorator for class is dataclass. You will see how it works by sample code below:

```python
from dataclass import dataclass

@dataclass #Decorator for whole class
class User:
    name:str
    age:int
    bio: str

# equivalent with
class User:
    def __init__(self,name:str,age:int,bio:str):
        self.name = name
        self.age = age
        self.bio = bio
```

Now what if we want to make decorator from class? Well first, the principle still same with decorator for function. but now we need to pass **`func`** to class and implement method **`__call__`**

```python
import functools

class LoremIpsum:
    def __init__(self,func):
        functools.update_wrapper(self, func)
    
    def __call__(self, *args, **kwargs): #Argument for function
        print("Class as decorator")
        return self.func(*args, **kwargs)

@LoremIpsum
def class_decorator():
    ....
```

&nbsp;  
&nbsp;  
That's all! In real world application you might find useful usage of decorator like [compiling using jit](https://numba.pydata.org/numba-doc/latest/user/jit.html) or using decorator for [caching](https://docs.python.org/3/library/functools.html)

---

Source:  

- A Gentle Introduction to Decorators in Python [link](https://machinelearningmastery.com/a-gentle-introduction-to-decorators-in-python/)  
- Decorator Design Pattern [link](https://sourcemaking.com/design_patterns/decorator)  
- Python Decorators [link](https://www.scaler.com/topics/python/python-decorators/)  
- Built-in Functions [link](https://docs.python.org/3/library/functions.html)
- classmethod() in python [link](https://www.geeksforgeeks.org/classmethod-in-python/)
- Data Classes [link](https://docs.python.org/3/library/dataclasses.html)


Python Decorator


If we want to share our jupyter notebook, but want to hide all messy code behind it, we can use the following command:

Long version:

```bash
jupyter nbconvert --to pdf --TemplateExporter.exclude_input=True --TemplateExporter.exclude_input_prompt=True --no-prompt notebook-name.ipynb --output outputfilename
```

You can change `--to pdf` to another extension, like `--to html` or `--to markdown`.  
`TemplateExporter` only cover some basic setting, so for specific setting each extension see [nbconvert docs](https://nbconvert.readthedocs.io/en/latest/config_options.html?highlight=TemplateExporter.exclude)

Simple version:

```bash
jupyter nbconvert --to pdf --no-input --no-prompt notebook-name.ipynb
```

But before run that command, make sure you already install `ipywidget` and enable `widgetsnbextension`

```bash
jupyter nbextension enable --py widgetsnbextension
```

Nbconvert command to export jupyter-notebook


To list all docker container that been running on our machine, we can use the following command:

```bash
docker container ls
```

But if we want to focus only on docker name, port and image we can use specific command:

```bash
docker container ls --format "table {{.Names}}\t{{.Ports}}\t{{.Image}}"
```

So now we want to see specific and filter our docker container ( by name or by port). We can use the following command:

```bash
docker container ls -a -q --filter=name=(container name) --format "table {{.Names}}\t{{.Ports}}\t{{.Image}}"
```

---
Source:  
Docker container command [link](http://manpages.ubuntu.com/manpages/bionic/man1/docker-container-ls.1.html)  
Escaping double curly braces in markdown [so question](https://stackoverflow.com/questions/24102498/escaping-double-curly-braces-inside-a-markdown-code-block-in-jekyll)

Docker command to list all docker information


As developers, writing documentation can feel tedious, especially when you hit writer’s block. Here are some points that can help you create better documentation.

This post is summarized from [this source](https://www.youtube.com/watch?v=R6zeikbTgVc).

**1. Start with what the reader needs**

Begin by asking: **What does the reader need to know?**  
What information will help them get their job done?
For example, your reader (maybe a new teammate) might need to know:

- How to use an internal tool your team relies on.
- How a past project was structured.
- How to reproduce an environment locally.

**2. Write less**

Keep it concise. You don’t need to write long documentation — just what’s necessary.  
Always ask:

- Does the reader need this context?
- Do they really need this detailed CLI command?

Long documentation requires more maintenance, and unmaintained docs quickly become outdated.  
Outdated documentation isn't just useless — it can mislead users.

**3. Write an outline first**

Start by answering the key questions mentioned above, then draft an outline of headings based on what the reader needs.  
Under each heading, add bullet points or notes you’ll expand later.  
This makes the writing process easier and more organized.

**4. Use the rubber duck method**

This isn't specific to writing docs, but it helps. Try explaining your topic out loud — as if you’re talking to a “rubber duck.”  
It's often easier to explain things verbally first, and documentation doesn't need to sound overly formal.

**5. Write for readability**

Your goal is to make the reader’s job easier. Write in a way that’s simple to follow.

- Use short bullet points instead of long paragraphs.
- Prefer instructional language over general explanations.

For example:

> ✅ “Run command A and expect result B.”  
> ❌ “You can expect result B if you execute command A.”

Also, make headers actionable:
- Instead of “Custom code generation,” use “Writing a code generator.”  
  The latter makes it clear what the reader will learn.

**6. Don't use documentation to patch problems**

If you're writing documentation to fix a recurring issue, you might be addressing the wrong problem.  
Fix the root cause instead of documenting around it.

**Source:**  
[Writing Effective Documentation (YouTube Video)](https://www.youtube.com/watch?v=R6zeikbTgVc)

Pirate Treasure

Trimmed Mean Pipeline in Sklearn

Counterfactual Machine Learning

Python Decorator

Nbconvert command to export jupyter-notebook

Docker command to list all docker information

On How to Write (good or just ordinary) Documentation